> For the complete documentation index, see [llms.txt](https://nytshift.gitbook.io/nytshift-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://nytshift.gitbook.io/nytshift-docs/release-and-readiness/release-capacity.md).

# Release capacity and retention

NYTSHIFT production releases are immutable directories under `/opt/nytshift/releases/<7-hex>` selected by the `/opt/nytshift/current` symlink. Disk exhaustion can prevent extraction, service restart, logging, certificate renewal, or database writes, so every deployment must reserve capacity before upload and retain bounded rollback history after acceptance.

## Safety contract

`pnpm release:capacity:audit` is read-only. It recognizes a release only when all of these are true:

* the entry is a plain direct child directory named with exactly seven lowercase hexadecimal characters;
* `RELEASE_COMMIT` is an exact lowercase 40-byte Git commit beginning with that directory name;
* `RELEASE_SHA256` is an exact lowercase SHA-256 digest;
* the current symlink resolves to a verified direct child of the release root.

Unknown, legacy, incomplete, symlinked, or marker-mismatched entries are reported as `ignored` and are never deletion candidates. A malformed current release fails the whole command closed.

The retention plan always preserves the current release plus at least one verified rollback. It is content-addressed by `planDigest`. Mutation requires a second command with the exact current name and digest, so any promotion or inventory change invalidates the approval.

## Pre-deployment check

Use exact byte counts from the packaged archive and extracted standalone tree:

```sh
pnpm release:capacity:plan -- --incoming-archive-bytes 100000000 --incoming-unpacked-bytes 500000000
```

The default reserve is 2 GiB. `readyWithoutPrune` is the preferred state. `readyAfterPlannedPrune` means the exact dry-run candidates must be reviewed and applied before upload. A false value exits with status 2; increase the filesystem rather than reducing the reserve below operational requirements.

## Apply reviewed retention

Run the dry-run on the production host, record `current` and `plan.planDigest`, then apply those exact values:

```sh
pnpm release:capacity:audit
pnpm release:capacity:apply -- --expected-current d706b3a --plan-digest <64-hex-digest>
```

The default keeps two rollback releases. `--keep-rollbacks` may be increased from 2 to 10, but cannot be zero. After deletion the tool re-scans the filesystem and proves the current symlink and retained inventory still validate. It never restarts services, changes Nginx/systemd/TLS, uploads an artifact, or deletes an ignored path.

## Deployment order

1. Build and verify a fresh detached exact revision.
2. Measure archive and extracted byte counts.
3. Run the capacity plan on the target host.
4. If needed, apply only the exact reviewed plan while the currently accepted service remains live.
5. Upload, checksum, extract and promote the new release.
6. Verify service, health, public routes and assets.
7. Re-run the audit. Keep the accepted current release and two verified rollbacks.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://nytshift.gitbook.io/nytshift-docs/release-and-readiness/release-capacity.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.