Add Policies domain (drafting, versioning, tracked acceptance)

Implements #6: studio admins draft, version, and publish policies; the
public registration gate reads the current published version of each, and
acceptance is recorded against the exact version so a new version must be
re-accepted at the next booking.

- src/Policy/: Policy, PolicyVersion, PolicyAcceptance value objects;
  PolicyRepository, PolicyVersionRepository, AcceptanceRepository;
  PolicyService (orchestrates create/add-draft/publish across the policies
  and versions tables); PolicyEndpoint (REST); PolicyController +
  templates/admin/policies.php (Policies admin menu, manage_policies)
- us_policies, us_policy_versions, us_policy_acceptances tables in Schema
- REST: public GET /policies (current published versions); manage_policies
  for create, add version, edit draft, and publish
- Wiring in Plugin, RestRegistrar, AdminMenu

AcceptanceRepository is built now and consumed by the booking/enrolment
gate in #3/#4.

Also bump PHPStan to --memory-limit=1G in the composer lint script; the
default 128M now crashes the analysis as the codebase has grown.

Tests: tests/Unit/Policy/ (value objects, repositories, service).
composer test (90 total), cs, and PHPStan level 6 all pass.

Refs #6

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

src/Policy/PolicyEndpoint.php

@@ -0,0 +1,197 @@
+<?php
+declare(strict_types=1);
+
+namespace Unsupervised\Schedular\Policy;
+
+use Unsupervised\Schedular\Auth\RoleManager;
+
+class PolicyEndpoint {
+
+	public function __construct(
+		private PolicyRepository $policies,
+		private PolicyVersionRepository $versions,
+		private PolicyService $service,
+	) {}
+
+	public function registerRoutes( string $route_namespace ): void {
+		register_rest_route(
+			$route_namespace,
+			'/policies',
+			[
+				[
+					'methods'             => \WP_REST_Server::READABLE,
+					'callback'            => [ $this, 'index' ],
+					'permission_callback' => '__return_true',
+				],
+				[
+					'methods'             => \WP_REST_Server::CREATABLE,
+					'callback'            => [ $this, 'create' ],
+					'permission_callback' => [ $this, 'canManage' ],
+				],
+			]
+		);
+
+		register_rest_route(
+			$route_namespace,
+			'/policies/(?P<id>\d+)/versions',
+			[
+				[
+					'methods'             => \WP_REST_Server::CREATABLE,
+					'callback'            => [ $this, 'addVersion' ],
+					'permission_callback' => [ $this, 'canManage' ],
+				],
+			]
+		);
+
+		register_rest_route(
+			$route_namespace,
+			'/policies/(?P<id>\d+)/versions/(?P<vid>\d+)',
+			[
+				[
+					'methods'             => \WP_REST_Server::EDITABLE,
+					'callback'            => [ $this, 'updateVersion' ],
+					'permission_callback' => [ $this, 'canManage' ],
+				],
+			]
+		);
+
+		register_rest_route(
+			$route_namespace,
+			'/policies/(?P<id>\d+)/versions/(?P<vid>\d+)/publish',
+			[
+				[
+					'methods'             => \WP_REST_Server::CREATABLE,
+					'callback'            => [ $this, 'publish' ],
+					'permission_callback' => [ $this, 'canManage' ],
+				],
+			]
+		);
+	}
+
+	/**
+	 * Public: the current published version of every policy (the registration gate).
+	 */
+	public function index(): \WP_REST_Response {
+		$out = [];
+
+		foreach ( $this->policies->findAll() as $policy ) {
+			if ( null === $policy->currentVersionId ) {
+				continue;
+			}
+
+			$version = $this->versions->findById( $policy->currentVersionId );
+			if ( null === $version || ! $version->isPublished() ) {
+				continue;
+			}
+
+			$out[] = [
+				'id'                => $policy->id,
+				'title'             => $policy->title,
+				'slug'              => $policy->slug,
+				'policy_version_id' => $version->id,
+				'version_number'    => $version->versionNumber,
+				'body'              => $version->body,
+			];
+		}
+
+		return new \WP_REST_Response( $out, 200 );
+	}
+
+	public function create( \WP_REST_Request $request ): \WP_REST_Response|\WP_Error {
+		$title = sanitize_text_field( (string) $request->get_param( 'title' ) );
+		if ( '' === $title ) {
+			return $this->invalid( __( 'A policy title is required.', 'unsupervised-schedular' ) );
+		}
+
+		$slugParam = sanitize_text_field( (string) $request->get_param( 'slug' ) );
+		$slug      = sanitize_title( '' !== $slugParam ? $slugParam : $title );
+		if ( '' === $slug ) {
+			return $this->invalid( __( 'A valid policy slug is required.', 'unsupervised-schedular' ) );
+		}
+
+		if ( null !== $this->policies->findBySlug( $slug ) ) {
+			return new \WP_Error( 'duplicate_slug', __( 'A policy with that slug already exists.', 'unsupervised-schedular' ), [ 'status' => 409 ] );
+		}
+
+		$id = $this->service->createPolicy( $title, $slug );
+
+		return new \WP_REST_Response( [ 'id' => $id ], 201 );
+	}
+
+	public function addVersion( \WP_REST_Request $request ): \WP_REST_Response|\WP_Error {
+		$policy = $this->policies->findById( absint( $request->get_param( 'id' ) ) );
+		if ( null === $policy ) {
+			return $this->notFound();
+		}
+
+		$body = wp_kses_post( (string) $request->get_param( 'body' ) );
+		$id   = $this->service->addDraftVersion( (int) $policy->id, $body );
+
+		return new \WP_REST_Response( [ 'id' => $id ], 201 );
+	}
+
+	public function updateVersion( \WP_REST_Request $request ): \WP_REST_Response|\WP_Error {
+		$version = $this->loadVersionForPolicy( $request );
+		if ( $version instanceof \WP_Error ) {
+			return $version;
+		}
+
+		if ( PolicyVersion::STATUS_DRAFT !== $version->status ) {
+			return $this->invalid( __( 'Only draft versions can be edited.', 'unsupervised-schedular' ) );
+		}
+
+		$body = wp_kses_post( (string) $request->get_param( 'body' ) );
+		$this->versions->updateBody( (int) $version->id, $body );
+
+		return new \WP_REST_Response(
+			[
+				'id'   => $version->id,
+				'body' => $body,
+			],
+			200
+		);
+	}
+
+	public function publish( \WP_REST_Request $request ): \WP_REST_Response|\WP_Error {
+		$version = $this->loadVersionForPolicy( $request );
+		if ( $version instanceof \WP_Error ) {
+			return $version;
+		}
+
+		$this->service->publishVersion( (int) $request->get_param( 'id' ), (int) $version->id );
+
+		return new \WP_REST_Response(
+			[
+				'id'     => $version->id,
+				'status' => PolicyVersion::STATUS_PUBLISHED,
+			],
+			200
+		);
+	}
+
+	public function canManage(): bool {
+		return is_user_logged_in() && current_user_can( RoleManager::CAP_MANAGE_POLICIES );
+	}
+
+	/**
+	 * Load the version named in the route and confirm it belongs to the policy.
+	 */
+	private function loadVersionForPolicy( \WP_REST_Request $request ): PolicyVersion|\WP_Error {
+		$policyId = absint( $request->get_param( 'id' ) );
+		$version  = $this->versions->findById( absint( $request->get_param( 'vid' ) ) );
+
+		if ( null === $version || $version->policyId !== $policyId ) {
+			return $this->notFound();
+		}
+
+		return $version;
+	}
+
+	private function notFound(): \WP_Error {
+		return new \WP_Error( 'not_found', __( 'Policy or version not found.', 'unsupervised-schedular' ), [ 'status' => 404 ] );
+	}
+
+	private function invalid( string $message ): \WP_Error {
+		return new \WP_Error( 'invalid_policy', $message, [ 'status' => 400 ] );
+	}
+}