# Trusted fast deploys

Status: implemented for the access-controlled `sites.smol.ai` Alpha.

Forge can publish a small, buildless application without starting the
repository build sandbox. This is a trusted control-plane optimization, not a
weaker deployment mode: Forge still deploys one exact commit, validates every
byte, produces immutable artifacts, applies the same runtime wrapper and
policy, records a deployment, and activates only an eligible branch head.

The deployment page labels the selected path, explains the decision, shows the
time to live and phase timings, and reports reused assets and runtimes. A
repository never needs to choose the fast path.

## Eligible repositories

A deployment uses the fast path when all of these are true:

- the repository and site are already admitted to the Deploy trial;
- the Site configuration and `forgeBuild.ts` have no build command;
- `forgeBuild.ts` is present at the exact deployment commit;
- static assets are committed under `app.assets.directory`;
- an optional application entrypoint is a committed `.js` or `.mjs` file;
- the entrypoint is self-contained ESM with one default export and no imports;
- source plus assets fit the 1 MiB fast-source ceiling;
- the Git tree contains only regular files and directories; and
- the normal Forge manifest, application, asset, and quota checks pass.

TypeScript, package imports, generated assets, larger sources, and repository
build commands automatically use the existing restricted sandbox. That is a
supported fallback, not a deployment failure.

Example:

```ts
import { defineForge } from '@smolai/forge/config';

export default defineForge({
  version: 1,
  app: {
    entrypoint: 'src/server.js',
    assets: {
      directory: 'web',
      fallback: 'index.html',
    },
  },
  routes: [
    { pattern: '/api/*', to: 'app.http' },
    { pattern: '/*', to: 'app.assets' },
  ],
});
```

## Execution flow

```mermaid
flowchart LR
  Push["Forge Git push<br/>exact SHA"] --> Decide{"Fast-path eligible?"}
  Decide -->|yes| Read["Read verified Git objects<br/>from Forge R2"]
  Decide -->|no| Sandbox["Restricted exact-SHA sandbox"]
  Read --> Validate["Strict manifest, tree,<br/>source and asset validation"]
  Validate --> Parallel["Publish in parallel"]
  Parallel --> Assets["Reuse/upload assets<br/>by SHA-256"]
  Parallel --> Runtime["Reuse/publish site runtime<br/>by provider digest"]
  Sandbox --> Ingest["Trusted ingest"]
  Assets --> Activate["Record deployment<br/>and activate eligible head"]
  Runtime --> Activate
  Ingest --> Activate
```

### Exact source without a clone

The runner receives read-only access to Forge's Git-object bucket. It resolves
only the deployment's stored repository ID and exact lowercase commit SHA. For
each compressed Git object it:

1. inflates and parses the declared object type and length;
2. recomputes the canonical Git SHA-1 over the complete object;
3. rejects digest or size mismatches, invalid UTF-8 names, duplicate or unsafe
   paths, malformed trees, symlinks, gitlinks, and special file modes; and
4. walks only the manifest entrypoint and asset subtree required by the
   deployment.

The branch name is never used to select source after the deployment is
created.

### Content reuse

Assets are stored at `sites/content/sha256/<digest>`. A version 2 trusted asset
manifest maps each public path to exactly that validated key. Existing version
1 per-deployment manifests remain readable, so legacy static Sites are
unchanged.

Dynamic code is wrapped and published per Site under a name derived from the
Site identity and provider-artifact digest. The digest includes the application
bundle, trusted-wrapper version, provider compatibility settings, and the
private runtime binding. A later deployment with identical provider bytes
reuses the ready script even if routes or deployment IDs differ.

This slice intentionally does not delete shared artifacts. Garbage collection
needs reference accounting and is a separate operation.

## Observability

Each new deployment records:

- `execution_path`: `trusted_fast` or `sandbox`;
- a stable selection reason;
- source, validation, compile, asset, runtime-publication, activation, and
  total fast-path milliseconds;
- reused asset file and byte counts; and
- whether the dynamic runtime was reused.

Older deployments display “Path not recorded.” The API exposes the sanitized
summary as one `execution` object and does not expose raw trusted manifests or
storage keys.

## Failure and rollout behavior

- Eligibility failures fall back before a deployment is marked running.
- A failure after trusted publication starts fails the normal run and
  deployment; it does not silently retry in a different execution model.
- The global fast-path flag disables new fast deployments without affecting
  the sandbox or already-hosted Sites.
- Content-addressed uploads are idempotent, and runtime publication is
  reconciled through the Site runtime-artifact catalog.
- Production activation still verifies that the deployment SHA is the current
  configured branch head. Preview creation does not move production.

## Fixture benchmark

The controlled fixtures establish the sandbox baseline below. These verified
results come from production deployment records after ordinary Forge Git
pushes on July 23, 2026, not from a local microbenchmark. “Cold” includes the
first content-addressed asset and runtime publication. “Reused” is a later
exact-commit deployment with unchanged application content.

| Fixture | Sandbox time to live | Cold fast path | Reused fast path | Reused improvement |
| --- | ---: | ---: | ---: | ---: |
| Static SPA | 12.747 s | 1.951 s | 1.632 s | 7.81× |
| Durable reservations | 15.210 s | 2.550 s | 2.118 s | 7.18× |
| Durable realtime | 14.779 s | 2.399 s | 1.867 s | 7.92× |

The reused deployments each reported two reused assets. Reservations and
realtime also reported a reused runtime. The trial did not reach the aspirational
10× target consistently; the remaining latency is primarily control-plane
activation and remote Git-object/database round trips, not repository build
work.