How-to Guides

RazorWire form loading gives an accepted Turbo form submission visible feedback while the browser waits for token preparation or the server. It applies to forms enhanced with `rw-active="true"`; it does not add a general request or navigation loading API. The app can supply a nearby status message, and RazorWire shows its accessible top bar when no app indicator applies.

Use RazorWire form interactions when a server-rendered form needs small local mechanics without page-specific JavaScript: reveal or disable conditional fields, add and duplicate model-bound rows at multiple collection levels, and remove rows while keeping ASP.NET Core model binding predictable. The package owns row mechanics; the application still owns its model, field markup, validation policy, persistence, and failed-post rendering keys.

RazorWire's first-party browser assets are authored in TypeScript and delivered through the same package paths that hosts already use. The package also carries an exact, byte-copied Turbo runtime under its own custody checks. Application code does not need to move RazorWire script URLs, globals, custom events, DOM hooks, CSS hooks, or island strategy names.

RazorWire page navigation enhances same-page section links without turning your page into a client-side app. Use it when a server-rendered page already has normal anchors and sections, but needs active section state, reduced-motion-aware navigation, optional compact panel close behavior, and Turbo/frame lifecycle cleanup.

When using RazorWire Turbo Streams to replace or update parts of a page that contain forms, the original Anti-Forgery token hidden input may be lost. To prevent `400 Bad Request` errors on subsequent form submissions, ensure the token is included in your updated HTML.

Use RazorWire Behavior Kit when a server-rendered app needs small app-authored JavaScript that follows RazorWire's page lifecycle. Behavior Kit is for progressive enhancement, not for replacing your frontend architecture.

Hybrid hosting keeps static pages cheap while leaving RazorWire-managed live behavior on a real ASP.NET Core app. The public site can serve exported files from `https://www.example.com`, while streams, islands, and safe RazorWire forms call `https://api.example.com`.

Use RazorWire section copy when a server-rendered documentation page, reference page, or long-form article needs stable "copy link to this section" behavior without app-specific clipboard JavaScript.

See browser status pages and production error pages move from local startup policy to a named AppSurface Web behavior contract.

RazorWire dialogs let an MVC action explicitly present a response in one accessible, package-owned native dialog shell. The application owns the Razor body and decides which response needs attention. Start with the [MVC dialog sample](../../../examples/razorwire-mvc/README.md#server-selected-dialogs) and the [RazorWire package guide](../README.md#server-selected-dialog-responses).

Configure explicit no-evidence rules, coverage evidence, resource-backed browser E2E, and release envelopes without claiming skipped tests are complete coverage.

Approved plan: [version aliases](issue-176-version-aliases.md). Make-it-so began 2026-10-09. Branch: `codex/make-it-so-docs-version-aliases`, base `main`. Initial base `40de2ef`; current integrated base `c2f062f2`. Goal: complete every approved facet through a validated **draft** PR.

This planned proof belongs to the [persona fixture activation design](../designs/issue-772-persona-scoped-fixture-activation.md). The checklist was written before implementation. Measured results are recorded below, separately from the planned checks.

Status: Complete as a test-only v0 pilot. A real-source follow-up found that the motivating Skoolit accessors are outside v0. No production coverage-policy change is proposed.

Invocation 1, cycle budget 4. Cycle 1 started 2026-09-10. Review uses the canonical gstack review checklist and plan-completion, specialist and adversarial sections. Base: `origin/main`. Target includes new untracked files as well as the branch diff. The approved plan remains authoritative.

Approved scope: [design](../designs/issue-800-typed-work-definitions.md), [plan](issue-800-typed-work-definitions.md), [verification groups](issue-800-typed-work-definitions-test-plan.md).

**Disposition: reviewed planning remedies PASS; approved plan ready for implementation.** Overall planning remains DONE_WITH_CONCERNS because actual candidate/OS, timing, adopter and doctor evidence is still required. This targeted pass addresses concerns in the [approved design](../designs/issue-806-durable-worker-template.md); it does not replace the earlier full Autoplan or claim implementation completion.

Target: the [approved template plan](../designs/issue-806-durable-worker-template.md), branch `codex/make-it-so-durable-worker-template`, base `origin/main` at `7ae38084`. Default cycle budget: four. This is implementation review, not the earlier planning remedy recheck. Local fixes are authorized by make-it-so. No push, PR or release has occurred.

Result: **PASS on the local macOS arm64 host** after an approved filesystem/process sandbox override for this private temporary experiment. This is native-cluster feasibility evidence; candidate template/provider and GitHub-runner proofs remain required.

Branch: `codex/make-it-so-dialog-responses`. Approved scope: [implementation plan](issue-828-dialog-responses.md). Goal: validated draft PR.

Capture one real migration-job change across the current AppHost, deployment workflow, environment file, and OpenTofu root. Record the deployed Job and imported-provider representation, including task count, parallelism, retries, timeout, provenance labels, IAM policy, network, Cloud SQL attachment, secret reference, and service account. Values omitted by a legacy command are not AppSurface defaults.

For the historical schema-11 runtime heartbeat cleanup rollout, use the [heartbeat retention operations guide](heartbeat-retention-operations.md). The current role recipe requires schema 12 and must not be run on an older store; use the recipe matching that historical package until the coordinated upgrade. The schema 9→10 transcript below remains the historical runtime-health adoption proof. For retry-policy choices, start with the [execution-policy guide](execution-policies-v1.md) and its [migration checklist](migrations/execution-policies-v1.md).

These guidelines apply to all changes made in this repository.

Rule ID | Category | Severity | Notes --------|----------|----------|------- ASFLOWA001 | AppSurface.Flow.Authoring | Error | Generated Flow outcome is not mapped. ASFLOWA002 | AppSurface.Flow.Authoring | Error | Generated Flow target does not exist. ASFLOWA003 | AppSurface.Flow.Authoring | Error | Generated Flow target is ambiguous or incompatible. ASFLOWA004 | AppSurface.Flow.Authoring | Error | Generated Flow start node is invalid. ASFLOWA005 | AppSurface.Flow.Authoring | Error | Generated Flow authoring declaration is invalid. ASFLOWA006 | AppSurface.Flow.Authoring | Warning | Generated Flow authoring mixes generated and low-level registration.

`KeycloakCanonicalJson.ReadRecipe(ReadOnlySpan<byte>)` and `ReadPolicy` reject unknown, duplicate, missing, trailing, or incorrectly typed JSON properties and validate the closed schema. `Write` emits the canonical bytes used for recipe and policy identities. Canonical bytes, rather than formatting or file paths, produce the recipe SHA256.

This note is the CI-000 baseline for build-time work. Historical timing samples below describe the runs taken at the dates shown; the current coverage decision path is governed by the shared [evidence policy](https://github.com/forge-trust/AppSurface/blob/main/.github/evidence.policy.json) and the tracked workflows.

Issue `#425` defines the design contract for future AppSurface CLI authentication. It does not add auth commands yet.

AppSurface deployment turns explicit application-topology intent into reviewable provider artifacts while leaving cloud authority with the consuming application's release workflow.

AppSurface Docs should feel like a focused documentation workspace, not a marketing site and not a generic SaaS dashboard. The UI should help people orient quickly, scan densely, and move deeper into docs with very little friction.

This note keeps the in-repo AppSurface Docs plan aligned with the phased GitHub roadmap.

AppSurface Flow is the typed long-running process surface for AppSurface. It lets package authors describe a process as a stable graph of nodes, run that graph locally for tests and examples, then map the same node outcomes into durable orchestration decisions.

Explains the OSS license boundary, commercial purchase intent, and package-readiness signals.

AppSurface Web owns a small, composable [Progressive Web App](https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps) foundation: install metadata, application-icon badging requests, explicit offline behavior, push-event plumbing, service-worker registration metadata, and privacy-safe diagnostics. Each capability is opt-in. Badging does not own an attention count or prove that an icon changed. Enabling push does not request notification permission, create a subscription, choose recipients, or send a message.

Local AppHost composition and native deployment-pipeline integration for .NET Aspire applications.

Implement one typed provider contract and ship it with the coordinated AppSurface package family. The [logical-key reference](config-logical-keys.md) defines grammar, collision domains, precedence, and native representability. The [upgrade guide](config-key-migration.md) covers the intentional pre-1.0 source and binary break.

Final plan APPROVED by the user with answer A on 2026-10-01. Aggregated only from this workflow on main, full HEAD in the recent five-commit window. Exact-match key: component + sorted files + title. Twelve distinct task records remain; semantic overlap is retained and marked, so estimates must not be summed. Use the [ordered execution checklist](issue-772-persona-scoped-fixture-activation.md) to sequence actual work. Authored deliverables and focused/browser acceptance are complete. The acceptance baseline on `16aee8e1` passed the solution/package and artifact checks, but a later full ship run failed with six unchanged timeout/process-cleanup tests; fresh exact-gate verification remains pending after the sample Host-filter patch. The [evidence ledger](issue-772-implementation-evidence.md#full-validation-history) records the baseline and [later ship follow-through](issue-772-implementation-evidence.md#final-ship-follow-through). Final ship reviews and draft publication remain pending.

This guide documents the optional `ForgeTrust.AppSurface.Durable.CloudTasks` adapter for submitting one named, empty Google Cloud Tasks wake to an existing Durable external-activation host. It covers the public API, identity boundary, request and response limits, result meanings, recovery, and known pitfalls.

This directory contains libraries and tools for building command-line applications.

AppSurface maintains a coordinated release contract. This file explains the contribution rules that feed the public release surface.

This guide explains how an AppSurface upgrade is intended to manage its own coverage artifacts across worktrees while leaving current reports readable at their established paths. It also gives consumers a way to find direct test lanes that collect coverage implicitly. Storage warnings and cleanup are separate from coverage quality: keep the existing [coverage run](../Cli/ForgeTrust.AppSurface.Cli/README.md#appsurface-coverage-run), [coverage merge](../Cli/ForgeTrust.AppSurface.Cli/README.md#appsurface-coverage-merge), and [coverage gate](../Cli/ForgeTrust.AppSurface.Cli/README.md#appsurface-coverage-gate) configuration, exclusions, metrics, and thresholds.

This record accompanies the [approved design](coverage-artifact-storage.md) and [consumer adoption guide](../../guides/coverage-storage.md). It distinguishes implemented behavior from release evidence that remains incomplete. All observations below are local to macOS/APFS unless stated otherwise.

Generated by /office-hours on 2026-10-20 Repository: forge-trust/AppSurface Branch: main; inspected source: 1991280e8af049db592ebcb705cbf66f4b4c6e8b Status: APPROVED — autoplan gate revision 1; all recommendations accepted on 2026-10-20

**What:** Evaluate one consenting internal workflow using the exact execution observer and measure classification usefulness and replaced custom code.

Integrations with various dependency injection containers and advanced DI utilities.

Every deployment validation failure uses an `ASDEPLOY1xx` or Aspire-adapter `ASDEPLOY2xx` code and safe Problem, Cause, Fix, and Docs fields. Diagnostics contain identifiers when useful but must not contain parameter values, inherited environment contents, connection strings, raw secret material, or unsanitized tool output.

`DeploymentIntent` is a schema-versioned, provider-neutral snapshot of one evaluated Aspire environment and an explicit full source revision. Version 1 accepts one or more `MigrationJobIntent` values. Jobs are sorted by `DeploymentLogicalId`; duplicate ids and empty targets fail before rendering.

Generated by /office-hours on 2026-09-01 Branch: main Repo: forge-trust/AppSurface Status: APPROVED — /autoplan final gate (2026-09-02) Mode: Builder Supersedes: andrew-main-design-20260823-issue-776-evidence-coverage-core.md

Generated by /office-hours on 2026-10-10. Branch: `codex/make-it-so-781-structural-classifier-pilot` (planning checkout). Repo: `forge-trust/AppSurface`. Status: APPROVED. Mode: Builder, open-source maintenance. Issue: [#865](https://github.com/forge-trust/AppSurface/issues/865).

Generated by /office-hours on 2026-08-19 Branch: main Repo: forge-trust/AppSurface Status: APPROVED (office-hours and autoplan, 2026-08-20) Mode: Builder Supersedes: andrew-main-design-20260813-043247-issue147-rich-authoring.md

Generated by /office-hours on 2026-09-10 Branch: main Repo: forge-trust/AppSurface Status: APPROVED Mode: Builder Supersedes: andrew-main-design-20260909-154331.md

Generated by /office-hours on 2026-09-23 Branch: main Repository: forge-trust/AppSurface Status: APPROVED Mode: Builder Builds on: [coverage run issue #499](https://github.com/forge-trust/AppSurface/issues/499) and [private Evidence coverage core design](https://github.com/forge-trust/AppSurface/blob/main/docs/designs/evidence-coverage-core-extraction.md) Issue: [#815](https://github.com/forge-trust/AppSurface/issues/815)

Generated by /office-hours on 2026-08-31 Branch: HEAD (detached worktree) Repo: forge-trust/AppSurface Status: APPROVED — final autoplan gate accepted 2026-09-06 Mode: Builder

Generated by /office-hours on 2026-10-07 Branch: main Repo: forge-trust/AppSurface Issue: [#176](https://github.com/forge-trust/AppSurface/issues/176) Status: APPROVED Mode: Builder (open source / research)

Generated by /office-hours on 2026-10-03 (America/New_York) Repository: `forge-trust/AppSurface` Issue: [#765](https://github.com/forge-trust/AppSurface/issues/765) Inspected branch: `codex/make-it-so-845-runtime-preflight` at `9612cdeb` Status: APPROVED Approved: 2026-10-03, user selection D7/A, with the specification-review limitation acknowledged Mode: Builder, open source Builds on: [typed Work exits](issue-783-durable-work-exits.md), [immutable typed Work definitions](issue-800-typed-work-definitions.md), and the [executable-contract adoption rail](durable-executable-contract-adoption-rail.md).

Generated by `/office-hours` on 2026-09-06 Branch: `main` Repo: `forge-trust/AppSurface` Status: APPROVED Mode: Builder Supersedes: `andrew-main-design-20260901-020115-issue790-tailwind-host-scoped-cli.md` for office-hours branch lineage only; the issue #790 product decision remains independent.

Generated by /office-hours on 2026-09-09 Branch: main Repo: forge-trust/AppSurface Status: APPROVED — autoplan reviewed 2026-09-10 Mode: Builder Supersedes: andrew-main-design-20260906-015125.md for Case 1 only; the parent adoption rail remains authoritative for the other cases

Generated by `/office-hours` on 2026-08-23 Branch: `main` Repository: `forge-trust/AppSurface` Status: APPROVED — private-core extraction selected and autoplan-reviewed Mode: Builder Supersedes: none; the nearest `main` design is the unrelated #771 Python-docstring spike. Builds on: [contract-first EvidenceHost design](https://github.com/forge-trust/AppSurface/blob/main/docs/designs/appsurface-evidencehost-contract-first.md) and [#775](https://github.com/forge-trust/AppSurface/pull/775)

Generated by `/office-hours` on 2026-09-05 Repo: `forge-trust/AppSurface` Issue: [#781](https://github.com/forge-trust/AppSurface/issues/781) Status: APPROVED Mode: Builder

Generated by /office-hours on 2026-09-28 Branch: main Repo: forge-trust/AppSurface Status: APPROVED Supersedes: andrew-main-design-20260928-184112-issue828-server-selected-dialogs.md Mode: Builder Issue: [#828](https://github.com/forge-trust/AppSurface/issues/828) Related: [#827 form loading feedback](https://github.com/forge-trust/AppSurface/issues/827)

A user submits a RazorWire form while the serverless host wakes. The click appears to do nothing, so they may click again or abandon the task. This occurred in a consumer application, although the exact form route and cold-start duration have not been recorded. The first release covers remotely submitted rw-active forms; navigation, islands, and arbitrary app requests can join later.

Generated by `/office-hours` on 2026-09-10

The mapped [Google Secret Manager provider](../../Config/ForgeTrust.AppSurface.Config.GoogleSecretManager/GoogleSecretManagerConfigProvider.cs) exposes synchronous configuration resolution and calls a synchronous Google client. On a cache miss, it currently queues `Fetch` with `Task.Run` and blocks the resolving caller on the task. A cold startup therefore needs a second thread to do each winning synchronous lookup. There is no recorded production startup or thread-pool baseline, so this design does not promise a measured speedup.

The mapped [Google Secret Manager provider](../../Config/ForgeTrust.AppSurface.Config.GoogleSecretManager/GoogleSecretManagerConfigProvider.cs) exposes synchronous configuration resolution and calls a synchronous Google client. On a cache miss, it currently queues `Fetch` with `Task.Run` and blocks the resolving caller on the task. A cold startup therefore needs a second thread to do each winning synchronous lookup. There is no recorded production startup or thread-pool baseline, so this design does not promise a measured speedup.

Generated by /office-hours on 2026-10-13 Branch: `main` Repository: [forge-trust/AppSurface](https://github.com/forge-trust/AppSurface) Issue: [#869](https://github.com/forge-trust/AppSurface/issues/869) Status: APPROVED Mode: Builder, open source / research Source baseline: `161dae679b54d21ba3490a1b06cd9e08de77e1a4` Builds on: [PostgreSQL Work protocol](../../Durable/work-protocol-v1.md), [immutable execution policies](../../Durable/execution-policies-v1.md), and the July 18 design reflected in the [Slice 3 reconstruction record](../../Durable/slice3-reconstruction.md). This is an independent #869 design; the recent #866 main-branch design remains in force.

Generated by /office-hours on 2026-08-23T14:55:33-04:00 Branch: main Repo: forge-trust/AppSurface Status: APPROVED Mode: Builder Supersedes: andrew-main-design-20260821-033503.md

Generated by /office-hours and queued for /autoplan on 2026-06-21 Branch: codex/localsecrets-secret-tool-autoplan Repo: forge-trust/AppSurface Status: DRAFT Mode: Builder

Generated by /office-hours on 2026-10-24 Branch: main Repo: forge-trust/AppSurface Status: APPROVED Mode: Builder Issue: [#890](https://github.com/forge-trust/AppSurface/issues/890) Supersedes: andrew-main-design-20261020-coverage-storage.md for office-hours branch discovery only; the coverage-storage design remains independent.

Generated by /office-hours on 2026-09-11 Branch: HEAD (detached planning checkout at `48c6db61`) Repo: forge-trust/AppSurface Status: APPROVED Approved by user: 2026-09-11 Mode: Builder Design base: `0a9a4213a197533d607904f0cf3c6ec124313335` (`origin/main`, including #791) Builds on: approved #790 Host-Scoped Tailwind CLI design Supersedes: andrew-HEAD-design-20260607-issue491-tunit-tailwind-pilot.md for the branch design index only; this document does not change #491's decisions.

Generated by /office-hours on 2026-10-24 Branch: `codex/make-it-so-781-structural-classifier-pilot` Repo: `forge-trust/AppSurface` Status: APPROVED Mode: Builder, open source / research Source: [#892](https://github.com/forge-trust/AppSurface/issues/892) Builds on: [#804 activation service](https://github.com/forge-trust/AppSurface/issues/804), [#793 adoption rail](https://github.com/forge-trust/AppSurface/issues/793) Supersedes: `andrew-codex-make-it-so-781-structural-classifier-pilot-design-20261010-000850-issue865.md` for branch lineage only; that unrelated design's decisions remain unchanged.

Related issue: [#771](https://github.com/forge-trust/AppSurface/issues/771)

Generated by /office-hours on 2026-09-24

Generated by `/office-hours` on 2026-08-18 Branch: `HEAD` (detached) Repo: `forge-trust/AppSurface` Status: APPROVED Mode: Builder

Generated by `/office-hours` on 2026-08-31 Branch: detached HEAD at `b34970c8` Repo: forge-trust/AppSurface Status: IMPLEMENTED Mode: Builder

Generated by /office-hours on 2026-09-10 Branch: main Repo: forge-trust/AppSurface Status: APPROVED Autoplan review: APPROVED on 2026-09-11 Mode: Builder Supersedes: andrew-main-design-20260909-154331.md for branch lineage only; it does not supersede that document's durable-runtime decisions

Generated by /office-hours on 2026-10-22 Planning branch: codex/make-it-so-845-runtime-preflight Execution branch: codex/make-it-so-887-keycloak-security-recipes Repo: forge-trust/AppSurface Status: APPROVED — office-hours design and autoplan amendments (2026-10-22, gate_rev 1, owner reply `rec`). Maintainer acceptance, feasibility, API commitment and release authorization remain pending. Mode: Builder, open source / research Builds on: [#658 theme lifecycle](https://github.com/forge-trust/AppSurface/issues/658) Source case: [#887](https://github.com/forge-trust/AppSurface/issues/887) Coordinates with: [#888 identity and readiness](https://github.com/forge-trust/AppSurface/issues/888), [Skoolit #608 adoption](https://github.com/forge-trust/skoolit/issues/608)

`appsurface durable doctor` reads one connected store using a restricted runtime credential. It reports schema compatibility, configured versus active epoch, local heartbeat-retention structure, and optionally one selected heartbeat. A clean result says **store/runtime checks passed** at the captured database observation and links the [canonical Durable worker starter](../start-here/durable-worker.md). Run your application's composition verifier afterward; the [external-activation reference and verifier](../examples/durable-external-activation/README.md) show that separate proof for an existing host.

SDK operations report `KeycloakSecurityException`; the strict `KeycloakCanonicalJson` readers report malformed JSON as `JsonException`, which the compiled sample converts to a safe input-error message. Its `Code`, `Phase`, `OperationId`, `Effect`, `Recovery`, `NextAction`, `CorrelationId`, `DiagnosticReference`, `ProfileKey`, and `RetryMetadata` are safe structured diagnostics. The `DiagnosticReference` anchors this page by lowercase failure code.

This guide defines the internal, versioned W3C trace-context contract for PostgreSQL-backed durable Flow execution. It is an operational correlation feature: it is never authorization, scope routing, payload storage, or a substitute for PostgreSQL RLS.

This document is the normative persistence and processing contract for the PostgreSQL Schedule implementation. It completes the public `IDurableScheduleClient` preview contract without starting a hosted scheduler. A caller invokes one bounded `PostgreSqlDurableScheduleProcessor.ProcessDueAsync` pass from its own trusted trigger.

This ledger records how the public surface from the original durable-contract commit was treated when the contract was rebuilt as three preview packages. The checked-in [Durable](https://github.com/forge-trust/AppSurface/blob/main/Durable/ForgeTrust.AppSurface.Durable/PublicAPI.Shipped.txt), [Provider](https://github.com/forge-trust/AppSurface/blob/main/Durable/ForgeTrust.AppSurface.Durable.Provider/PublicAPI.Shipped.txt), and [PostgreSQL](https://github.com/forge-trust/AppSurface/blob/main/Durable/ForgeTrust.AppSurface.Durable.PostgreSql/PublicAPI.Shipped.txt) snapshots are the exhaustive member-level source of truth; this ledger explains the intentional package and visibility decisions.

This ledger is the audit boundary for reconstructing the PostgreSQL Work provider on current `main`. Commit `226346bc` is evidence, not merge-ready history or an independent specification. The current [`ForgeTrust.AppSurface.Durable`](ForgeTrust.AppSurface.Durable/README.md) and [`ForgeTrust.AppSurface.Durable.Provider`](ForgeTrust.AppSurface.Durable.Provider/README.md) contracts, the [`Work protocol v1`](work-protocol-v1.md), and the [`slice 3 reference workload`](slice3-reference-workload.md) are authoritative.

This is the first-success and conformance workload for the PostgreSQL Work provider. It proves atomic acceptance, process-loss recovery, exact effect permission, stable provider identity, and safety-class handling.

This ledger is the audit boundary for reconstructing the PostgreSQL Flow engine on current `main`. Commit `456dbfa3` is evidence, not merge-ready history or an independent specification. The current [`ForgeTrust.AppSurface.Durable`](ForgeTrust.AppSurface.Durable/README.md) and [`ForgeTrust.AppSurface.Flow`](../Flow/README.md) contracts, the [`Flow protocol v1`](flow-protocol-v1.md), and the [`slice 4 reference workload`](slice4-reference-workload.md) are authoritative.

This is the first-success and conformance workload for the PostgreSQL Flow engine (slice 4). It proves atomic Flow instance creation, transition step evaluation, external event delivery, timer expiry, child Work activity integration, recovery invariants across 11 protocol boundaries, options reuse, RLS scope isolation, and operator release/disable safety. The timer-winner boundary is certified by force-terminating a separate process after the database commit; the other Flow boundaries use transaction rollback and fresh processor instances. The existing slice-3 workload separately certifies child Work process loss after an effect permit.

Schema `12` raises the compatible reader/writer floor. Before applying migration `0012`, stop new submissions and drain every pre-schema-12 reader, writer, host, and activator; use the [migration and rollback checklist](migrations/execution-policies-v1.md). Do not stage the floor change as a mixed-version rolling upgrade.

This checklist upgrades an existing Durable PostgreSQL store for immutable attempt plans and absolute execution deadlines. Read the [execution-policy reference](../execution-policies-v1.md) first to select legacy, deadline-only, or planned behavior. This migration changes the compatible package floor; it is not a zero-downtime rolling upgrade for old workers.

The public boundary is deliberately small. `Validation` checks closed recipe shape, canonical paths, supported platform/profile/template families, operation ordering, exact material references, and maximum resource values before effects. `Canonical` is the sole recipe/policy identity serializer and strict reader. Do not use a general JSON serializer for canonical recipe or policy bytes.

This test plan was approved before implementation. Use the public Testing APIs and exact production contracts; never use reflection to reach private state.

The [runtime doctor](../runtime-doctor.md) addresses the repeated health interpretation recorded below. Previously, an operator combined schema status, [runtime health assessments](../operational-assessments.md#health-predicates), process logs and application tests to decide which prerequisite failed. Doctor returns the connected store's diagnosis and its next action in one report; [deployment preflight](../heartbeat-retention-operations.md#complete-runtime-set-preflight-and-proof-checklist) and application verification still require their own evidence.

This is the canonical reference for the provider-neutral external activation API, its outcome and cancellation rules, operator response, and telemetry contract. It is for hosts that receive a payload-free wake from HTTP, a scheduler, a webhook, or another external signal and then ask the configured Durable provider to attempt one bounded pass. The [authenticated ASP.NET Core reference-host contract](../examples/durable-external-activation/README.md) describes one transport; this service has no HTTP dependency.

Start here when adding automatic cleanup of old `runtime_heartbeat` identities to an existing [Durable PostgreSQL provider](ForgeTrust.AppSurface.Durable.PostgreSql/README.md). The table contains one row per configured worker ID. A stopped process cannot remove its row, and deployments that create new IDs can accumulate stale rows. The provider keeps 24 hours of heartbeat history by default, then removes eligible rows in bounded batches. Cleanup manages capacity; it does not determine Work correctness or readiness.

The supported host is Unix-like and must preserve executable modes, provide Docker 29-compatible OCI layout build contexts with the containerd snapshotter, and create absent snapshot/context destinations. The host supplies the complete explicit recipe, policy, capture bindings, and actual immutable image identity. The repository-held schema is not currently published; future publication depends on the separate pure publish decision and coordinated dependency authorization. The package uses managed .NET code and two runtime dependencies: `BouncyCastle.Cryptography` for signed Release verification and `ZstdSharp.Port` for compressed Debian payload handling. Python is used only by CI harnesses.

Status: APPROVED Approved: 2026-09-18 — user selected A (approve as-is) Review date: 2026-09-15 Source: [approved design](../designs/issue-798-tailwind-artifact-provenance.md) Reviewed source base: `e0618ac8dcc3b5903517e9a711f42959534b7fb5` (`origin/main`). Planning checkout: `188bc3e4d2a3f23c27bff376a7525842b4e8820f` (detached HEAD). Implementation must branch from the reviewed main base and carry the design and plan forward.

Source: [confirmed issue #802](https://github.com/forge-trust/AppSurface/issues/802). Review target: commit `9d185f43` on `main`.

Source design: [approved form loading design](razorwire-form-loading-feedback.md). This plan implements its agreed form scope and leaves navigation and arbitrary requests for later. It is the input to `/autoplan` and may be amended by its reviews.

Status: APPROVED — /autoplan review complete; user approved as-is on 2026-09-24.

Status: APPROVED — user approved the reviewed plan and all recommendations on 2026-09-10.

Generated by the autoplan task aggregator from this run's CEO, DX and engineering reviews. [Implementation plan](issue-798-tailwind-artifact-provenance.md) · [Test matrix](issue-798-tailwind-artifact-provenance-test-plan.md).

Generated by autoplan on 2026-09-10 from the latest CEO, DX and engineering runs for this branch. Exact tuple deduplication retained all 11 distinct task records. Implementation source is present for all tasks. Execution evidence is tracked in the [progress record](issue-800-execution-progress.md) and [completion audit](issue-800-plan-completion-audit.md); all tasks passed their final validation on commit `2872507c`.

This is the [alias plan](../issue-176-version-aliases.md)'s local fixture. Both exact releases passed the archive verifier on 2026-10-07. The implementation's real-release HTTP and two-host retarget checks passed on 2026-10-09; the recorded boundaries below distinguish those checks from the remaining human acceptance observation.

Every actual scheduler barrier receives a row before it is changed. Do not add a lifecycle timer or modify a fixture until the exact coverage-step baseline leaves two candidates indistinguishable.

Use this page to publish the implementation result. A safe no-change ceiling is a complete outcome.

Complete this committed record before changing any sharing or scheduler boundary. Raw local `TestResults/coverage-merged/` output remains uncommitted; each row below links the workflow run, commit SHA, command, and retained `coverage-efficiency-evidence` artifact that produced it.

This artifact records only measurements actually executed for the [Durable operational-assessment adoption guide](../operational-assessments.md). Targets from the approved design are listed separately from observations so an unrun journey cannot be mistaken for evidence.

Snapshot date: 2026-10-01. This audit maps the approved design’s B01–B31 allocation to source and test files. It does not change the approved plan. A linked test file establishes source presence. Compilation and execution claims are limited to the run evidence listed separately. The B01–B31 evidence rows preserve that October 1 snapshot: their “latest” 137/137 or 140/140 counts and `/private/tmp/issue-804*` paths are historical receipts, not proof for the 2026-10-02 candidate. Those temporary paths were removed externally during the interruption; see the [implementation evidence history](../designs/issue-804-progress.md).

Date: 2026-10-04 Branch: `codex/make-it-so-durable-worker-template` Inputs: `TestResults/coverage-merged/coverage.cobertura.xml`, `/tmp/issue806-coverage-attempt1.log`, current tracked diff and intentional untracked code.

The unchanged command was `./scripts/coverage-solution.sh`, with 95% line/85% branch aggregate and patch policy against `origin/main`, Codecov line semantics and the existing 0.5 percentage point tolerance. The baseline was clean commit `12d048d8b5dc49eb64ee403c2745a9a8321bf5d2`. All 56 projects completed; 55 passed. The sole failure was `NativeRuntimeProbesRealPortsAndValidatesOwnedProcessPidFile`: it expected a released port to remain free, but another process could reuse that port. The regression now holds a bound socket, verifies it does not listen, then calls `Listen` and verifies the owned listener.

Exact command:

The [unchanged solution coverage command](https://github.com/forge-trust/AppSurface/blob/a628c7588b22732b4adc8131ce3be0b35fa973d6/scripts/coverage-solution.sh) ran with its actual native prerequisite:

Goal: implement the approved [Durable worker template](../designs/issue-806-durable-worker-template.md) through a validated draft PR.

This document records the migration, rollback, lifetime, and performance evidence for the file declared secret reference implementation. The initial passing repository and packed-consumer gates below ran against code commit `db45ecf5857b2903d50749a596810ad73385c8ff` on September 15, 2026. The post-cleanup confirmation records the final passing run at `d1561e396eb0c1cadfc1023ebff17c621dd02040`. Later evidence-only documentation changes do not change the code that was tested.

Status: **PASSED** for the 44 minimum IDs and mandatory supplemental executions, using the final committed-source native and fresh packed receipts recorded below. Test source, a local build, or an earlier unrelated green suite does not mark a row passed. This plan preserves the approved 44 scenario IDs and all required parameterized and supplemental executions from the [approved implementation plan](issue-869-transaction-bound-handoff-fence.md).

**Historical static audit, 2026-10-14:** read-only audit of the dirty working tree on `codex/make-it-so-869-handoff-fence` whose HEAD/base was `2f805e60d7aba9249fe7ffe848f826629dc67869` (same SHA reported for `origin/main`). This SHA identifies the base of the uncommitted implementation, not the final feature source. The approved scope is [the transaction-bound handoff-fence plan](issue-869-transaction-bound-handoff-fence.md) and its [44-ID test plan and mandatory supplements](issue-869-handoff-test-plan.md). Implementation/test changes were reviewed as existing working-tree content. The source mapping below remains historical; it is not a new execution receipt.

As of **October 15, 2026**. The [approved execution plan](plans/issue-869-transaction-bound-handoff-fence.md) is implemented on `codex/make-it-so-869-handoff-fence` in [PR #877](https://github.com/forge-trust/AppSurface/pull/877). Verification below is tied to specific revisions; subsequent local changes require fresh affected checks.

Scope: [ASCOV201 volume identity diagnosis](https://github.com/forge-trust/AppSurface/issues/899). Decision and native observations: [domain identity design](../designs/issue-899-domain-identity.md).

Schema-v1 coverage domains keep the existing native identity mismatch refusal. There is no safe in-place reconciliation for a persisted marker whose identity differs from the current directory because schema v1 has no independent continuity proof. The diagnostic classifies the observed mismatch; it does not explain its root cause or grant ownership.

Approved scope: [external activation plan](issue-804-external-activation.md). Feature branch: `codex/make-it-so-804-external-activation`, initially based on `fd0b124e`. The current base is `4aa8329c`. Four pre-existing plan-review artifacts were preserved byte-for-byte at `/private/tmp/issue-804-preserved-plan-review-8YsHpT` so task commits exclude generated review output. The [completion audit](../plans/issue-804-plan-completion-audit.md) maps B01–B31 to implementation and proof sources.

Date: October 4, 2026

This implementation record accompanies the [approved testing-hook plan](issue-866-pre-activation-testing-hooks.md) and [pinned Skoolit inventory](issue-866-skoolit-scenario-inventory.md). The proof uses .NET SDK 10.0.102, Hosting 10.0.8 and Aspire 13.4.4. All graphs and values are synthetic; no application resources were started by profile activation.

Plan: [approved design](../designs/issue-867-evidence-readiness.md). Verification requirements: [test plan](issue-867-readiness-test-plan.md).

Current status: the [atomic file publication correction](#atomic-file-publication-correction--2026-10-24) is a newer production change awaiting final candidate verification. The [integrated qualification v3](#current-integrated-qualification-v3--2026-10-24) remains retained production/sample proof for its earlier source checkpoint. Earlier sections preserve their historical pending/failure states.

Status: owner approved the explicit Micrometer inventory correction on 2026-10-23; current production qualification now passes all four retained recipes. The failed unchanged-fixture observations below are retained as history.

Scope: the [approved amended execution plan](../designs/issue-891-cloud-run-execution-observation.md), current branch implementation, new files and adjacent legacy behavior. Base: `origin/main`. The canonical gstack review checklist was read from the installed review skill. The default four-cycle limit applies.

Plan: [approved execution-observation design](../designs/issue-891-cloud-run-execution-observation.md). Evidence: [initial gcloud feasibility assessment](issue-891-gcloud-feasibility.md). Recovered source evidence: [Skoolit archive assessment](issue-891-skoolit-evidence.md).

This worksheet catalog records the owner-authorized, reviewed offline v1 Cloud Run Execution mapping for the two neutral consumers. It is technical compatibility evidence for parser and classifier tests; it is not provider attestation or live compatibility certification. The owner amendment in [the approved design](../designs/issue-891-cloud-run-execution-observation.md) authorizes this reconciliation and executable fixture evidence.

Initial status on 2026-10-24: **uncertified; integration gate not passed**. This assesses the first gate of the [approved plan](../designs/issue-891-cloud-run-execution-observation.md#minimum-evidence-contract-and-compatibility-gate). It does not assert that v1 is impossible, that a schema-shaped fixture proves provider behavior, or that a live execution has been read.

Status: historical recovery assessment. The owner subsequently authorized the [execution amendment](../designs/issue-891-cloud-run-execution-observation.md#execution-amendment-authorized-on-2026-10-24), which reconciles numeric identity and implicit v1 SQL projection without reducing full configuration parity. Current offline mapping, fixtures and exact SDK evidence are recorded in the [mapping assessment](issue-891-provider-mapping.md); current validation is in the [progress record](issue-891-execution-progress.md). This report preserves what the source search itself established.

`{local-gstack-project-state}` denotes the local gstack project directory for the historical review artifacts cited below; it is a placeholder, not a repository path.

Generated by /office-hours on 2026-10-03 (America/New_York) Repository: `forge-trust/AppSurface` Issue: [#765](https://github.com/forge-trust/AppSurface/issues/765) Inspected branch: `codex/make-it-so-845-runtime-preflight` at `9612cdeb` Status: APPROVED Approved: 2026-10-03, user selection D7/A, with the specification-review limitation acknowledged Mode: Builder, open source Builds on: [typed Work exits](issue-783-durable-work-exits.md), [immutable typed Work definitions](issue-800-typed-work-definitions.md), and the [executable-contract adoption rail](durable-executable-contract-adoption-rail.md).

Generated by /office-hours on 2026-09-30 (America/New_York) Branch: main Repo: forge-trust/AppSurface Issue: [#772](https://github.com/forge-trust/AppSurface/issues/772) Office-hours design status: APPROVED by the user. This records the earlier design decision, not autoplan approval. Autoplan amendments: APPROVED by the user with final-gate answer A on 2026-10-01T06:05:29.610754+00:00. Mode: Builder

Generated by /office-hours on 2026-09-30 Branch: detached HEAD at `fd0b124e16a35b85ee16acde799834af407e18de` Repo: `forge-trust/AppSurface` Office-hours status: APPROVED Autoplan status: APPROVED Mode: Builder Supersedes: `andrew-HEAD-design-20260911-181819-issue798-tailwind-artifact-provenance.md` for office-hours branch lineage only; that unrelated design's decisions remain unchanged. Issue: [#804](https://github.com/forge-trust/AppSurface/issues/804) Builds on: [the approved adoption rail and normative activation contract](durable-executable-contract-adoption-rail.md#normative-external-activation-flow), [operational assessments](../../Durable/operational-assessments.md), and [typed Work definitions](issue-800-typed-work-definitions.md).

**Autoplan status: APPROVED — 2026-10-03; targeted remedy recheck PASS — 2026-10-04.**

Generated by /office-hours on 2026-09-23 Branch: main Repository: forge-trust/AppSurface Status: APPROVED Mode: Builder Builds on: [coverage run issue #499](https://github.com/forge-trust/AppSurface/issues/499) and [private Evidence coverage core design](https://github.com/forge-trust/AppSurface/blob/main/docs/designs/evidence-coverage-core-extraction.md) Issue: [#815](https://github.com/forge-trust/AppSurface/issues/815)

Source: [approved design](../designs/issue-828-server-selected-dialogs.md) and [issue #828](https://github.com/forge-trust/AppSurface/issues/828). The design's latest protocol revision is approved by the user but its independent review is recorded as unreviewed.

**Implementation prerequisite override:** On 2026-09-30, the user selected **A** to permit disposable test roles, a disposable StoreId/epoch, and local candidate packages for implementation and the draft PR. This supersedes the historical “before implementation” requirement for actual deployment inputs below. Actual reviewed deployment inputs and named owners remain required before release and activation. Every verifier, regression, coverage, exact-artifact proof, documentation, and later authorization requirement remains in scope. Illustrative fixture values must never be presented as reviewed production values.

Generated by /office-hours on 2026-10-10. Branch: `codex/make-it-so-781-structural-classifier-pilot` (planning checkout). Repo: `forge-trust/AppSurface`. Status: APPROVED. Mode: Builder, open-source maintenance. Issue: [#865](https://github.com/forge-trust/AppSurface/issues/865).

Generated by /office-hours on 2026-10-10 Branch: main Repo: forge-trust/AppSurface Status: APPROVED — original office-hours design and all Autoplan amendments Approval: user D1=A (approve as-is), recorded 2026-10-10T13:12:07Z; planning approval only. Mode: Startup — internal company project Issue: [#866](https://github.com/forge-trust/AppSurface/issues/866) Supersedes: prior main-branch office-hours record for #255, dated 2026-10-07 (branch sequence only; that separate decision remains in force).

None.

None.

None.

Autoplan status: **APPROVED**, 2026-10-26. Owner reply `rec`, gate revision 1: d1a and p1a.

Historical/reference inventory: current Skoolit implementation and consumer acceptance belong to [case #1259](https://github.com/forge-trust/skoolit/issues/1259). This source snapshot informs the SDK fixture contract; it is not a current consumer migration deliverable or runtime QA result.

Use this procedure when changing the pinned Keycloak image or releasing a new immutable image containing a registered login theme. It applies to the [Keycloak AppHost package](../README.md), not to production automation. Application CI and operators own image publication, health checks, realm mutation, rollout, and rollback.

<https://polyformproject.org/licenses/small-business/1.0.0>

Use LocalSecrets when a solo AppSurface app needs one-machine local development secrets and is not ready for a remote vault. The app keeps the same logical AppSurface config key, while LocalSecrets stores the value under the app and environment on the current machine.

An AppSurface key has one identity across configuration providers. `Payments:ApiKey` and `payments:apikey` compare equal; `Payments:Api-Key` and `Payments:Api:Key` do not. Start with the [Config quickstart](../Config/ForgeTrust.AppSurface.Config/README.md), then use this reference when declaring keys or moving a setting between providers.

Approved source: [logical-key plan](config-logical-key-contract.md), commit `540b59f7`. Execution branch: `codex/config-logical-key-contract`.

The consumer material-policy owner named in the [fixture card](../../../docs/designs/issue-887-feasibility-card.md#required-owners) owns retention. This checkout supplies [complete neutral JSON and receipts](../../../examples/auth-keycloak-security-recipes/fixtures/README.md), without distributing OCI archives, Maven binaries, Debian packages, or keyrings. Upstream registries and snapshot services are acquisition locations, not an indefinite retention promise.

Use this guide when a developer is already authorized to read a Google Secret Manager value and needs a reproducible, local integration-test clone. The `appsurface secrets transfer` workflow moves the value directly between the approved providers so it is not exposed in the terminal, a plan, a receipt, or a shell history.

LocalSecrets does not parse `.env` files directly. Move each secret into the local store using the same AppSurface config key that the app already expects.

Keep the same logical config keys when moving from `dotnet user-secrets` to LocalSecrets.

LocalSecrets is the single-machine pre-vault posture. Google Secret Manager is the remote provider for Google Cloud hosts that need team-safe storage, IAM-mediated access, and production-like source evidence.

Use this guide when a macOS AppHost reports `local-secret-migration-required`. That status means the current process can confirm that a retained legacy Keychain record is readable, but no v2 record exists yet. It is terminal by design: an AppHost never writes Keychain records during configuration resolution or claims cross-process parity before migration.

This package is suitable when an owner can preserve the original bytes and all provenance associations. It is unsuitable when the only input is an old tag, a normalized archive, an image filename, or a package name without its exact signed index and coordinate evidence.

LocalSecrets is a pre-vault step. The migration ladder is:

AppSurface's own acceptance checks should exercise the documented [EvidenceHost](../../start-here/evidencehost.md) extension points. Disposable orchestration that reimplements producer outcomes, resource readiness, deadlines, artifact integrity and cleanup hides gaps that downstream consumers also encounter.

Application-side logging, tracing, and metrics for AppSurface apps.

Status: DONE — reviewed design approved by the user on 2026-10-07 (D8/A). Issue: [#176](https://github.com/forge-trust/AppSurface/issues/176) Design: [Catalog-managed documentation version aliases](issue-176-version-aliases.md) Presentation: [Approved archive wireframe](https://raw.githubusercontent.com/forge-trust/AppSurface/refs/heads/main/docs/designs/issue-176-alias-archive-wireframe.png)

Status: the approved source-only ceiling is implemented in the private proof and the new package source; final-image limits remain unchanged. The [approved fixture card](issue-887-feasibility-card.md) keeps the final-image reader at 128 MiB. The [implementation patch](https://github.com/forge-trust/AppSurface/blob/7bded81f8ae4ff76c2c524e1d9a3e9ab50d93927/docs/designs/issue-887-source-oci-budget-proposal.patch) is a reviewable private-draft adaptation, not a supported API commitment.

This dashboard is a maintainer review surface for package-index evidence. It is not a live NuGet publish, artifact, smoke-install status board, or per-version release evidence bundle; use the release cockpit and protected package workflows for per-version publish proof.

This directory contains the eight P02 package consumer fixtures. Each fixture has one deliberately invalid statement marked with expected-compiler-error: CODE, a matching positive control, a package project template, and a manifest that pins the exact marked line and allowed diagnostic code.

This records execution of the [approved plan](issue-772-persona-scoped-fixture-activation.md) and [contract map](issue-772-test-plan.md). The [design](../designs/issue-772-persona-scoped-fixture-activation.md) remains the decision record. A checked implementation item requires its stated verification; authored code alone is not a pass.

Status: APPROVED by the user with final Autoplan answer A on 2026-10-01. The implementation is published in [PR #849](https://github.com/forge-trust/AppSurface/pull/849). This file retains the approved requirements; the [implementation evidence](issue-772-implementation-evidence.md) records the historical validation attempts, later passing checks and verification-fixture repairs. New local edits require fresh verification before publication. Source: [design and decision record](../designs/issue-772-persona-scoped-fixture-activation.md). Case: [#772](https://github.com/forge-trust/AppSurface/issues/772).

Audit date: September 10, 2026 Base: `origin/main` Scope: disk contents, including untracked files; no build or test commands run.

The [runtime doctor](runtime-doctor.md) diagnoses one connected store with a restricted credential and optional worker observation. Its clean result is a captured store/runtime check; deployment preflight and application verification remain separate.

`IDurableWorkHandoffFence` lets a running Durable Work executor make one current database decision from two kinds of authority: Durable's live invocation and permit, plus the application's current authorization and conditional handoff record. The application owns its authority and ledger; Durable continues to own the Work claim and execution lifecycle. A prepared handoff is provisional until the caller commits.

This is the normative operation and lock manifest for Durable slice 4. It specifies observable behavior, transaction boundaries, lock hierarchy, crash recovery boundaries, and execution state transitions for the PostgreSQL Flow engine. The package starts no worker or background polling service; unit and integration tests and future hosted runtime code drive each operation deterministically.

This is the normative operation and lock manifest for Durable slice 3. It specifies observable behavior, transaction boundaries, and ordering. Internal C# and SQL may be decomposed differently, but must preserve these invariants. The package starts no worker; tests and later hosting code drive one operation at a time.

Cold-cache execution and human novice walkthrough: **UNEXECUTED**. This page prepares the accepted measurement; it is not a novice-human usability result. The [fixture card](../../../docs/designs/issue-887-feasibility-card.md#current-production-qualification--2026-10-24) reports automated execution timings separately. The aspirational prepared cold-run target is 2–5 minutes, with no latency guarantee or new release threshold.

The [reviewed fixture card](../../../docs/designs/issue-887-feasibility-card.md#required-owners) names @akrock for the library/profile, consumer material policy, inspector compatibility, security response, and shared-package conflict resolution with #888. Release authorization is a separate responsibility and remains outstanding. These roles establish review routing, without a support SLA.

`ForgeTrust.AppSurface.Docs.ConsumerFixture` is the executable reference host for named Docs composition. It keeps the legacy `/docs` fixture path for existing browser-layout checks and exposes a separate named mode for the public/internal proof.

RazorWire helps server-rendered ASP.NET Core apps update page fragments without asking every app to invent a separate frontend runtime. That means RazorWire occasionally owns small generated UI nodes: enhancement markers, form feedback, stream connection affordances, and other package-created fragments that support RazorWire behavior.

Authorize RazorWire event streams before subscription and map safe denial outcomes.

The generated host and test project belong to your application after creation. Keep the authenticated activation and provider composition in place, then replace the sample Work in these three locations. The paths use `FirstDurableWorker` as the example project name; substitute the name you passed to `dotnet new` when it differs:

AppSurface is pre-`v1.0.0`, but security reports still need a private path.

This ledger records the evidence used to build Schedule persistence. It prevents historical or preview-only fragments from outranking the landed Durable protocols.

This is the checked PostgreSQL Gate A proof for the public preview. It creates a one-time Work Schedule, runs one manual pass, and verifies one immutable occurrence and one accepted Work. It proves durable identity and target acceptance; external provider effects remain governed by the Work registration's provider-safety policy.

Measured on 2026-08-07 from the `codex/durable-slice-7-adoption` working tree after a clean source build. The checked-in [`warm/run.json`](https://github.com/forge-trust/AppSurface/blob/main/Durable/evidence/postgresql-slice7/warm/run.json) records the immutable head and merge-base revisions alongside the working-tree source fingerprint used for the measurement.

The Keycloak recipe package exposes bounded progress observations through [`KeycloakStageEvents`](../README.md) and the BCL [`ActivitySource`](https://learn.microsoft.com/dotnet/api/system.diagnostics.activitysource) named `ForgeTrust.AppSurface.Auth.Keycloak`. The events are intended for a host progress panel, a test observer, or an OpenTelemetry bridge. They are diagnostic observations; they do not authorize publication, release, or deployment.

Use the [Durable worker template](../Durable/ForgeTrust.AppSurface.Durable.Templates/README.md) when a new .NET 10 application needs a small ASP.NET Core host that accepts typed Durable Work separately and exposes an authenticated, payload-free HTTP wake. The generated host uses the PostgreSQL provider and remains passive: it does not start a worker loop, apply schema changes, or grant database privileges.

RazorWire auth helpers are passive UI projection. They do not authorize endpoints, sign users in, sign users out, or turn build-time identity into runtime identity. Static export treats those helpers as public artifact boundaries: protected `rw:auth-allowed` content is never written to CDN or hybrid output.

An [`rw:island` with `swr`](../README.md#rwisland) can refresh its HTML when the page loads or its stream reconnects. A refresh can overlap a live update: its server snapshot may already be in flight when a Turbo Stream updates the island. Applying that older snapshot afterward would erase the newer browser state.

This is the operator and private-tool reference for the approved [#798 design](designs/issue-798-tailwind-artifact-provenance.md) and [implementation plan](plans/issue-798-tailwind-artifact-provenance.md). The flags, records and workflow behavior below describe the release provenance implementation. There is no consumer-facing package API change.

Generated by /plan-eng-review via /autoplan on 2026-10-03 Branch: codex/make-it-so-845-runtime-preflight (inspection only; implementation starts from current main) Repo: forge-trust/AppSurface Target: issue765, deterministic Durable retry plans and execution deadlines

Generated by /plan-eng-review via /autoplan on 2026-10-01 Branch: main Repo: forge-trust/AppSurface Commit: f03ffdb99bc38daf402005c1435577bc325e1c8e

Generated by /plan-eng-review on 2026-10-03 Branch: main Repo: forge-trust/AppSurface Status: plan approved by final gate D1=A; targeted follow-up review on 2026-10-04. Template tests remain proposed and unexecuted.

Generated by /plan-eng-review on 2026-10-15 Branch: main Repo: forge-trust/AppSurface Target: #867 Evidence readiness, plan-only requirements

Generated by autoplan engineering review, 2026-09-15. Planning checkout: detached `188bc3e4d2a3f23c27bff376a7525842b4e8820f`. Implementation base: `e0618ac8dcc3b5903517e9a711f42959534b7fb5`. Repository: forge-trust/AppSurface. Status: APPROVED, NOT EXECUTED. Approved with the implementation plan on 2026-09-18.

The [command reference](../../Durable/runtime-doctor.md) defines the shipped contract. This plan maps the required proof surfaces to their runners; it does not replace execution receipts or the repository coverage gate. There are no browser pages or routes. All database probes use owned disposable PostgreSQL fixtures and synthetic credentials.

Status: Implemented and verified on the supported public Aspire surface Design: [Ordered Local Seed Extension Points](auth-aspire-keycloak-local-seeds.md)

Generated by autoplan engineering review on 2026-09-10. Branch at review: `main`; implementation baseline: `48c6db61ac5f742bea9f1ee434860daf72df791c`.

ForgeTrust.AppSurface.Cli includes the following third-party payloads in addition to the repository license.

ForgeTrust.AppSurface.Docs includes the following third-party components in addition to the repository license.

`ForgeTrust.AppSurface.Web.Push` depends on [Lib.Net.Http.WebPush 3.3.1](https://github.com/tpeczek/Lib.Net.Http.WebPush), copyright Tomasz Pęczek, licensed under the MIT License.

ForgeTrust.AppSurface.Web.Tailwind and its retained direct companion packages include the following third-party attribution in addition to the repository license.

ForgeTrust.RazorWire includes the following third-party component in addition to the repository license.

This review records the compatibility analysis for the package-owned Turbo upgrade in AppSurface issue [#656](https://github.com/forge-trust/AppSurface/issues/656). It covers npm `@hotwired/turbo` 8.0.12 source commit [`ea54ae5a`](https://github.com/hotwired/turbo/commit/ea54ae5ad4b6b28cb62ccd62951352641ed08293) through GitHub tag [`v8.0.23`](https://github.com/hotwired/turbo/releases/tag/v8.0.23).

This guide changes Durable Work authoring syntax. It does not add a database migration, alter the Work fingerprint format, or rewrite accepted records. Read the [Work protocol v1](../work-protocol-v1.md) for acceptance, duplicate, provider-safety, and caller-owned transaction rules.

The train-1 release introduces case-insensitive, colon-delimited [logical keys](config-logical-keys.md) across Config, LocalSecrets, and Google Secret Manager. Upgrade the coordinated package family together. The provider SPI, manager inheritance, environment snapshot contract, wrapper initialization, and typed audit surfaces change intentionally before 1.0. Rebuild external providers and wrappers; there is no V2 adapter. Use the [provider-author guide](config-provider-authors.md) and [conformance package](../Config/ForgeTrust.AppSurface.Config.Testing/README.md).

LocalSecrets is a local user-session feature. CI jobs, containers, service accounts, and headless Linux sessions should prefer environment variables, key-per-file, or a remote secret provider.

The repository's current coverage path is selected by the shared [evidence policy](https://github.com/forge-trust/AppSurface/blob/main/.github/evidence.policy.json) and executed by the C# [repository evidence validation tool](../tools/ForgeTrust.AppSurface.Evidence.Validation/README.md). The workflow's `coverage` scope projects the root policy selection to solution coverage. Test-only changes select only that producer and use its direct Codecov-mode patch gate. Source-code changes select coverage and package checks; on CI pull requests that producer union also requires native fan-in. Local `local` and `local-plan` support `all`, `native`, `coverage`, and `packages` scopes; a scoped run closes only its lane, and `all` is the complete local policy selection.

This directory contains libraries and tools specifically for web application development within the AppSurface ecosystem.