Skip to content

docs(apps): seal Phase 3 release and plan Phase 4 #276

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
Maneek21 merged 1 commit into from
Aug 31, 2026
Merged

docs(apps): seal Phase 3 release and plan Phase 4 #276

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
68 changes: 36 additions & 32 deletions docs/superpowers/audits/2026-08-30-app-platform-phase-3-certification.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,14 +1,20 @@
# App Platform Phase 3 certification checkpoints

- Date: 2026-08-30; consolidated PR D gate 2026-08-31
- Date: 2026-08-30; consolidated PR D and immutable release gates 2026-08-31
- Historical pre-split baseline: `5050b0f1` with C5 source checkpoint
`944b265f`; useful review evidence, superseded for rollout certification
- Current PR D certification checkpoint: `fe66113f` on PR C merge `9c8e9ac9`;
split-control source checkpoint `5cf88c51`
- Current result: consolidated local PR D gate passed; remote PR checks and the
immutable release-artifact gate remain
- Rollout decision: off/off by default; merge alone does not make the legacy MCP
canary supported
- Released baseline: `v0.3.0-preview.14` at `6d39e0e`, image digest
`sha256:e565cc64ee22b5b9f6f99973e3762b639c27e026dc8824852145035acdacf788`
- Current result: PASS. PR D, fix-forward App compatibility, remote CI/security,
immutable publishing, upgrade, recovery, rotation, drain, quiescence, and
rollback gates passed.
- Rollout decision: off/off remains the default. The legacy MCP canary is
supported only as an explicit self-host opt-in using the documented split
controls. App origin remains disabled until Phase 5 grants and bindings.
- Detailed release record:
`2026-08-31-app-platform-phase-3-release-certification.md`

## Current split-control delta

Expand Down Expand Up @@ -88,30 +94,28 @@ explicit release-candidate gates. The one production source build is delegated
to normal PR CI against the exact pushed tip; run it locally only if that CI job
does not execute.

## Remaining PR D remote gate

- Inspect the committed audit delta and open PR D from the exact checkpoint.
- Require normal PR CI, including the production source build, API tests,
typecheck, upgrade/image jobs, and security checks, to pass.
- Keep the branch unmerged until human review; passing PR D does not satisfy the
separate release-artifact gate below.

## Remaining release-artifact gates

- Build and identify the immutable merged candidate image and its supported
predecessor; record both digests and migration ledgers.
- Prove a current pgvector-backed fresh install and supported upgrade through
`.21` on release-capable infrastructure.
- Run deterministic-provider canary and approval/browser smoke without claiming
a public Run UI.
- Back up and restore database, uploads/App artifacts where applicable, and all
Run keyrings at consistent points; exercise rotation and referenced-key
retirement refusal.
- Disable intake, drain and quiesce governed work, then perform the actual
supported image rollback drill.
- Record the first released image containing the final split-control contract as
the operational rollback floor.

Until those gates pass, App origin remains disabled, the legacy MCP canary stays
default-off and unsupported for production widening, and no local source hash
is an operational rollback floor.
## PR D remote gate — complete

- PR D #274 merged after the required typecheck, API, upgrade, production-image,
browser, Hermes, dependency, and CodeQL checks passed.
- The Hello Workspace release gate then exposed a package-byte versus parsed-
manifest digest mismatch. The smallest boundary repair shipped in #275 with
a deterministic red/green regression and the same full remote check set.
- The merged fix-forward revision is `6d39e0e`; no Run state machine, migration,
token, connector, UI, or rollout-control contract changed.

## Release-artifact gates — complete

- The supported predecessor is `v0.3.0-preview.12` at `23694ef8`, digest
`sha256:34b306e53e5c959468a973a50aaeb3b59235c56e631d67003f7780d18002d24b`.
- The target is `v0.3.0-preview.14` at `6d39e0e`, digest
`sha256:e565cc64ee22b5b9f6f99973e3762b639c27e026dc8824852145035acdacf788`.
- Upgrade through `.21`, deterministic-provider canary, App lifecycle,
matched backup/restore, three-purpose key rotation, retirement refusal,
pause/drain/resume, exact quiescence, and immutable image rollback passed.
- This target image is the first operational rollback floor containing the
final split-control and durable job-pause contract.

App origin remains disabled. The legacy MCP canary may be enabled only through
the documented self-host controls after a matched backup and canary; the
release does not authorize default-on production widening.
185 changes: 185 additions & 0 deletions docs/superpowers/audits/2026-08-31-app-platform-phase-3-release-certification.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,185 @@
# App Platform Phase 3 — Immutable release certification

| Field | Certified value |
|---|---|
| Result | PASS, with one explicitly recorded visual-tool limitation |
| Release | `v0.3.0-preview.14` |
| Commit | `6d39e0e0413c82d36c9481849ae582fdf805d1a6` |
| Image | `ghcr.io/maneek21/deft@sha256:e565cc64ee22b5b9f6f99973e3762b639c27e026dc8824852145035acdacf788` |
| Supported predecessor | `v0.3.0-preview.12` at `23694ef832bc11b6e06a704bf9af234697955d80` |
| Predecessor image | `ghcr.io/maneek21/deft@sha256:34b306e53e5c959468a973a50aaeb3b59235c56e631d67003f7780d18002d24b` |
| Release workflow | GitHub Actions run `33355373750` |
| Merged-revision CI | GitHub Actions run `33354900483` |
| Merged-revision security | GitHub Actions run `33354900548` |
| Certification host | Isolated loopback-only Docker/pgvector host; Compose project `deft_phase3_preview13_cert` |

## Decision

`v0.3.0-preview.14` is the Phase 3 operational rollback floor. The separate Run
engine/drain and legacy MCP intake contract is release-supported with these
limits:

- `DEFT_APP_RUNS_ENABLED=false` and
`DEFT_APP_RUN_LEGACY_MCP_CUTOVER_ENABLED=false` remain the default.
- A self-host operator may opt into the legacy MCP canary only after preserving
a matched database/keyring recovery point and following
`docs/app-run-operations.md`.
- Engine-on/intake-off is the drain and recovery state. Intake-on/engine-off is
invalid and fails closed.
- App-origin execution, App grants, App connector bindings, public Run APIs,
automation origins, and default-on rollout remain unsupported.

## Merge and release provenance

PR #274 merged the guarded runtime and split controls. Its first immutable
candidate, `v0.3.0-preview.13` at `4bad79d8`, passed publishing and Run gates but
failed the Hello Workspace install gate. Artifact verification correctly bound
the package digest to exact canonical package bytes; the API then incorrectly
compared that digest with a second digest computed after Module parsing inserted
an optional default.

PR #275 removed only that redundant semantic-digest comparison and added a
regression where a valid Module omits the optional `required` property. It did
not change UI, migrations, tokens, connector ciphertext, App Run state,
provider dispatch, or rollout controls. All ten PR checks and the merged
revision's CI/security workflows passed before `v0.3.0-preview.14` was tagged.

The release workflow passed its two clean-state Hermes certification runs,
built the amd64 image, signed it keylessly, attached GitHub build provenance,
generated an SPDX SBOM, archived the exact source and Hermes bundle, and
published the release manifest. All twelve assets covered by `SHA256SUMS`
matched. `gh attestation verify` passed for the digest above. The exact source
archive checksum is
`0920f15173885ea4ea43b44c031f324c60fa47a78c9374103dcb0fa48f959235`.

## Installation and supported upgrade

The release-capable host preserved an existing, unrelated Compose project named
`app`; only the isolated certification project was operated.

The predecessor fixture contained:

- one organization and owner;
- one streamable-HTTP MCP connection with an encrypted API-key envelope;
- one assigned conservative employee;
- one previously approved action and one pending action;
- one legacy receipt; and
- one deterministic provider effect.

The supported release upgrade wrapper stopped writes, produced a backup, and
upgraded the same database from `v0.3.0-preview.12` through the current ledger.
Migrations `.17`–`.21` were present with their recorded checksums; the
`preview.14` fix-forward had zero additional migrations. Doctor and self-host
smoke passed on the exact target image.

The connector ID, employee ID, assignments, action states, receipt, and
credential envelope survived. The envelope SHA-256 stayed
`addaa126502cf85e83b055bc1e7458b18fa4bf2821757dba74a50017c7b70289`;
no connector ciphertext rewrite occurred.

The merged revision's production-image/browser job also proved a fresh
pgvector-backed schema, self-host Agent Channel/MCP smoke, production browser
smoke, and critical-image vulnerability gate against the exact release commit.

## Rollout controls and governed canary

All four flag combinations were exercised:

| Engine | Legacy intake | Result |
|---|---|---|
| Off | Off | Healthy default; legacy execution |
| On | Off | Healthy drain-only state |
| On | On | Healthy governed canary |
| Off | On | API startup refused; no healthy API was exposed |

The pending predecessor action was approved under the governed canary. It made
one provider call and produced one succeeded Run, one succeeded attempt, one
budget reservation, encrypted input and output rows, seven ordered events, and
signed terminal evidence. Replay returned the existing approval/result and did
not call the provider again.

Across the full gate the deterministic provider recorded exactly three effects:

1. the approved predecessor legacy fixture;
2. the governed post-upgrade canary; and
3. a new legacy call while the image was actually rolled back to the supported
predecessor.

The released-image rollout-transition test independently passed engine-off
approval refusal, approval in drain-only mode, engine-off durable job deferral
with zero retry debit, engine-on completion, and registered-handler replay with
one stubbed provider dispatch.

## Declarative App compatibility

The public App Kit checked and built the unchanged Hello Workspace fixture at
package digest
`sha256:20e62afea91161e503dcecf547ad806c1419797834f6550f781d78bf3bb20884`.
A fresh single-use owner pairing installed and activated it on the released
image. `/api/apps` returned the active installation; `/api/apps/navigation`
returned its `Greetings` entry; and
`/modules/hello-workspace/greetings` returned HTTP 200. Disabling advanced the
lifecycle epoch from 1 to 2 and removed the navigation entry.

The in-app browser controller failed to initialize its local runtime assets, so
an additional interactive visual inspection of that specific route was not
obtained. This is not represented as visual evidence. The exact merged revision
did pass the normal production browser smoke, the release fix changed no web
code, and the App-specific package, API, route, activation, and disable evidence
above passed.

## Backup, restore, and key rotation

A matched recovery point was taken with app writes stopped. It contains the
PostgreSQL dump, uploads archive, App Run keyring, and deployment secrets under
restricted permissions. Representative checksums were:

- database: `c09d08c3579d46d3bc984569e5595dca3633be38cabac54b3be0202091b4aac8`;
- uploads: `de03d92de7b8138d6588d094a3ef65fdbcadab7265d8de22e4953e18c18197ba`;
- App Run keyring: `be9d9a2e598ac361f5863b49d191df1fd5b9ebb10f89fd45e0172a5803072359`.

The database and uploads were restored into a separate Compose project. That
copy booted first with the engine off, then with the matched keyring in
engine-on/intake-off mode. Stable continuity projections before and after
restore had the same canonical SHA-256. An uploads marker survived.

Encryption, receipt-signing, and fingerprint current IDs advanced to `enc-v2`,
`sig-v2`, and `fp-v2` while retaining the three `v1` entries. Before and after
rotation, retained input and output decrypted to identical digests and the
stored terminal receipt verified. Three separate non-serving boots removed one
referenced `v1` key at a time; each exited nonzero with the referenced-key
unavailable error. The healthy rotated configuration was restored after the
test. The disposable restore project and both of its volumes were then removed.

## Quiescence and immutable image rollback

Before rollback, the frozen runbook queries returned:

- zero nonterminal Runs;
- zero pending `app_run_invoke` approvals; and
- zero pending or running `app-run-attempt` jobs.

With intake and engine off, the exact predecessor digest was deployed against
the upgraded database without down-migration. Health reported
`v0.3.0-preview.12` at its recorded commit. The preserved connector executed
one new legacy approval successfully. The exact `preview.14` digest was then
restored, engine-on/intake-off passed the retained-key inventory and payload/
receipt reads, and the project returned to the default off/off state.

Final quiescence again reported zero for all three runbook queries. The only App
Run was succeeded, the deterministic provider count was three, the credential
envelope hash remained unchanged, and the final container used the certified
target digest.

## Cleanup and remaining non-claims

The temporary restore project, primary certification project, their isolated
volumes/networks, and the SSH browser tunnel were removed after the final
evidence snapshot. The on-disk evidence and matched backups were retained under
restricted operator access. The unrelated `app` project remained healthy
throughout.

This evidence does not claim App-origin authority, connected App grants,
ResourceRef, custom UI, automation, external runtimes, sync, public ingress,
hosted KMS, marketplace, billing, or SaaS operations. Those remain owned by
later phases.
29 changes: 18 additions & 11 deletions docs/superpowers/plans/2026-08-29-full-surface-app-platform.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,9 @@

| Field | Value |
|---|---|
| **Status** | Canonical capability map and threat model; Phase 3 PR C merged and guarded PR D closeout in progress; release gate pending |
| **Date** | 2026-08-29; execution rebaseline 2026-08-30 |
| **Baseline inspected** | `origin/master` at PR C merge `9c8e9ac9`; PR D is replayed from that exact merge and remains unreleased |
| **Status** | Canonical capability map and threat model; Phases 0–3 released and certified; Phase 4 planning handoff ready |
| **Date** | 2026-08-29; execution rebaseline 2026-08-30; Phase 3 release certification 2026-08-31 |
| **Baseline inspected** | `v0.3.0-preview.14` at `6d39e0e`, immutable image digest `sha256:e565cc64ee22b5b9f6f99973e3762b639c27e026dc8824852145035acdacf788` |
| **North star** | A Deft user can ask Codex to build a useful application, install it into their Deft workspace, and have it participate natively in the human UI, search and knowledge, tasks and chat, Defty, employee agents, human MCP, automation, approvals, runs, receipts, and audit. |
| **First delivery principle** | Build one safe participation protocol in stages; do not turn `deft.module.json` into an arbitrary plugin runtime. |
| **Relationship to earlier work** | Supersedes the provisional App Protocol v2 implementation sequence while retaining its certified Module, Capability, App Run, and approval-boundary decisions as design input. Absorbs the useful resource-graph and solution-composition ideas from the modular work-management proposal. |
Expand Down Expand Up @@ -778,15 +778,16 @@ and the staged secret/rollback decision. Phase 3 is not one big-bang PR; migrati
identifiers must be re-confirmed at the implementation boundary even though the
planning branch is now rebased onto the Phase 2 merge.

**Implementation status (2026-08-30):** PRs A and B merged the frozen contracts,
**Implementation status (2026-08-31):** PRs A and B merged the frozen contracts,
purpose-separated key service, additive schema, lifecycle, and fake-provider
engine. PR C (#273) merged release/budget evidence, live authority, approval
compatibility, ancestry, receipts, Attention, and internal repair invariants.
PR D now contains the pinned worker runtime plus separate exact default-off Run
engine/drain and legacy MCP intake controls. Its local consolidated gate and
cross-process approval/drain transition passed at `fe66113f`; remote PR and
immutable release-artifact gates remain. App origin remains disabled; existing
connector ciphertext and legacy receipt writers are unchanged.
PR D (#274) merged the pinned worker runtime plus separate exact default-off Run
engine/drain and legacy MCP intake controls. The immutable release gate found
and fixed one unrelated App-package digest compatibility defect in #275, then
certified `v0.3.0-preview.14` at `6d39e0e`. The legacy MCP canary is supported
only as an explicit self-host opt-in; App origin remains disabled. See the
[Phase 3 release evidence](../audits/2026-08-31-app-platform-phase-3-release-certification.md).

- [x] Add a versioned Secret Service with random nonces, AAD-bound ciphertext, current and decrypt-only keys, rotation, and explicit safe projections.
- [x] Add minimum-input rules, strict Run payload/blob limits, retention classes, terminal-state purge, and sanitized audit residue; permission widening cannot silently extend retention.
Expand All @@ -800,7 +801,7 @@ connector ciphertext and legacy receipt writers are unchanged.
- [x] Enforce the actor/App-grant intersection for App origins and the exact current legacy policy for compatibility origins before approval and again immediately before execution.
- [x] Recheck membership, employee health/budget, token scope, connector, schema digest, provider, assignment, grants/policy source, and bound authorization versions at execution.
- [x] Add sanitized receipts, metrics, Attention, internal bounded inspection/repair primitives, and compatibility adapters without rewriting existing action receipts or claiming a public Operations surface.
- [x] Separate disabled-by-default Run engine/drain and legacy MCP intake controls, reject intake without the engine, and retain a bounded drain-first rollback path; immutable release certification remains the D2 gate.
- [x] Separate disabled-by-default Run engine/drain and legacy MCP intake controls, reject intake without the engine, and retain a bounded drain-first rollback path; immutable release certification passed at `v0.3.0-preview.14`.

**Acceptance evidence:** auto and reviewed calls create one Run and at most one provider call; capability cycles stop before a second call and child Runs cannot reset budgets; no pseudo-App grant exists; legacy Runs are not App-discoverable; `always` review cannot be bypassed by an Autonomous employee; payload limits and terminal purge preserve only the declared sanitized residue; restart/replay, encryption/signer/fingerprint rotation, supported-image rollback, low-entropy guessing resistance, unknown-outcome, and ciphertext-leakage tests pass.

Expand Down Expand Up @@ -978,7 +979,13 @@ Do not begin with custom UI, runtime hosting, or Email Lite. The first shippable

This milestone creates a narrow but real user loop while adding no executable App code, new connector authority, background execution, or custom network surface. It also prevents the protocol and tooling from drifting apart.

The next internal milestone extracts CapabilityService with behavior parity. App Runs and the Secret Service follow; Resource Service/privacy follows that. Only after those gates pass does the same package expand into connected grants and Proof A. Governed automation comes next, followed by custom experiences, runtimes, sync, and public ingress as separately revocable planes.
That first milestone, CapabilityService, and governed App Runs are now delivered
through `v0.3.0-preview.14`. The next internal milestone is the Phase 4 Resource
Service/privacy seam described in the current delivery plan and the exact
[Phase 4 loop handoff](2026-08-31-app-platform-phase-4-resource-participation-loops.md).
Only after that gate passes does the package expand into connected grants and
Proof A. Governed automation follows, then custom experiences, runtimes, sync,
and public ingress as separately revocable planes.

## Migration and rollback strategy

Expand Down
Loading
Loading