# Deployment Requirements

## Purpose
Define how the plugin is deployed to the remote WordPress host and how deployment correctness is verified, including an exact-match validation between the approved artifact and deployed runtime files.

## Scope
This document covers:

- Remote host deployment target and access assumptions
- Artifact-only deployment model
- Pre-deploy checks
- Post-deploy validation
- Exact-match validation requirements
- Rollback requirements

This document does not define packaging rules (see `requirements/packaging.md`) or runtime feature behavior.

## Normative References
- Packaging requirements: `requirements/packaging.md`
- Environment/runtime requirements: `requirements/environment.md`
- Architecture/runtime separation requirements: `requirements/architecture.md`
- Smoke/regression expectations: `tests/smoke_tests.md`

## Deployment Model
- Deployments must use a built plugin artifact (zip) produced from approved repository content.
- Direct ad-hoc editing of production plugin files is not permitted.
- Deployment target path must point to the active WordPress plugin directory.
- Deployable runtime must come from `code/` only; compatibility/emulation assets are not deployable.

For the current remote test target:
- WordPress root: `/var/www/wordpress`
- Plugin directory root: `/var/www/wordpress/wp-content/plugins`
- Plugin deploy directory: `/var/www/wordpress/wp-content/plugins/calendar-plugin`

## Pre-Deployment Requirements
Before deployment:

1. Package artifact has passed packaging validation.
2. Local and remote smoke checks required for the release scope are green.
3. Remote path existence/permissions are verified.
4. Backup or rollback artifact for currently deployed version is available.
5. Deployment record includes target host, artifact name, version, timestamp, and operator.

## Deployment Procedure Requirements
Required high-level procedure:

1. Build a fresh deploy artifact as part of deploy execution (package step) using the current repository state.
2. Transfer approved artifact to remote host staging area.
3. Extract artifact to a clean temporary directory on remote host.
4. Validate extracted plugin directory structure.
5. Synchronize extracted plugin directory to deploy directory.
6. Run post-deploy verification checks.

Additional policy requirement:
- Deploy flow should not bypass packaging by deploying an arbitrary stale artifact path; deployment must use the freshly built artifact for that deploy run.
- Deployment tooling may support an explicit version override for controlled releases (for example `1.0.0`); when used, that explicit version must be the packaged and deployed artifact version for that run.

## Exact-Match Validation (Required)
After deployment, deployed plugin files must exactly match the approved artifact contents (excluding allowed mutable runtime files if any are explicitly listed).

Validation must include:

1. File set equality:
- No missing files in deployment compared to artifact.
- No extra files in deployment compared to artifact.

2. File content equality:
- Each deployed file content hash must match artifact file hash.

3. Optional metadata check (recommended):
- File mode/permissions match expected deployment policy.

Accepted implementation options:
- Manifest-based validation: generate a sorted list of `<relative-path> <sha256>` from extracted artifact and deployed directory and compare byte-for-byte.
- Rsync dry-run checksum validation (for example `rsync -avznc --delete`) plus explicit failure on any reported delta.

Any mismatch must fail deployment validation and trigger rollback decision.

## Post-Deployment Verification Requirements
After exact-match validation:

1. Plugin is present and loadable by WordPress.
2. Plugin activation state is verified (as required by release process).
3. CalDAV endpoint discovery and ICS endpoint health checks pass.
4. Critical UI/API smoke checks pass.

## Rollback Requirements
If deployment validation or post-deploy checks fail:

1. Revert to previous known-good plugin artifact.
2. Re-run minimum smoke checks to confirm recovery.
3. Record incident details and remediation before next deploy attempt.

## Audit and Traceability Requirements
Each deployment must record:

- artifact name/version
- source revision/tag
- target host/path
- deploy timestamp
- validation result (including exact-match evidence)
- rollback status if applicable

## Acceptance Criteria
Deployment process is acceptable only if:

1. Artifact-only deployment is enforced.
2. Exact-match file and hash validation is performed and passes.
3. Required post-deploy smoke checks pass.
4. Deployment record contains all traceability fields.
