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>

tests/Unit/Policy/AcceptanceRepositoryTest.php

@@ -0,0 +1,93 @@
+<?php
+declare(strict_types=1);
+
+namespace Unsupervised\Schedular\Tests\Unit\Policy;
+
+use Brain\Monkey\Functions;
+use Mockery;
+use Unsupervised\Schedular\Policy\AcceptanceRepository;
+use Unsupervised\Schedular\Policy\PolicyAcceptance;
+use Unsupervised\Schedular\Tests\Unit\TestCase;
+
+class AcceptanceRepositoryTest extends TestCase
+{
+    private \wpdb $db;
+    private AcceptanceRepository $repo;
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+
+        $this->db         = Mockery::mock(\wpdb::class);
+        $this->db->prefix = 'wp_';
+        $this->repo       = new AcceptanceRepository($this->db);
+    }
+
+    public function testInsertReturnsId(): void
+    {
+        Functions\expect('current_time')->with('mysql')->andReturn('2026-06-02 09:00:00');
+
+        $this->db->shouldReceive('insert')
+            ->once()
+            ->with(
+                'wp_us_policy_acceptances',
+                Mockery::on(static function (array $d): bool {
+                    return $d['policy_version_id'] === 9
+                        && $d['student_id'] === 5
+                        && $d['registration_type'] === PolicyAcceptance::REG_LESSON
+                        && $d['registration_id'] === 12
+                        && $d['ip_address'] === '203.0.113.7';
+                }),
+                ['%d', '%d', '%s', '%d', '%s', '%s']
+            );
+        $this->db->insert_id = 1;
+
+        $acceptance = new PolicyAcceptance(9, 5, PolicyAcceptance::REG_LESSON, 12, '203.0.113.7');
+
+        self::assertSame(1, $this->repo->insert($acceptance));
+    }
+
+    public function testInsertManyReturnsAllIds(): void
+    {
+        Functions\when('current_time')->justReturn('2026-06-02 09:00:00');
+
+        $ids = [11, 12];
+        $this->db->shouldReceive('insert')
+            ->twice()
+            ->andReturnUsing(function () use (&$ids): void {
+                $this->db->insert_id = array_shift($ids);
+            });
+
+        $result = $this->repo->insertMany([
+            new PolicyAcceptance(9, 5, PolicyAcceptance::REG_LESSON, 12),
+            new PolicyAcceptance(10, 5, PolicyAcceptance::REG_LESSON, 12),
+        ]);
+
+        self::assertSame([11, 12], $result);
+    }
+
+    public function testFindByRegistrationMapsRows(): void
+    {
+        $this->db->shouldReceive('prepare')
+            ->once()
+            ->with(Mockery::pattern('/registration_type = %s AND registration_id = %d/'), PolicyAcceptance::REG_LESSON, 12)
+            ->andReturn('SELECT ...');
+
+        $this->db->shouldReceive('get_results')->andReturn([
+            (object) [
+                'id'                => '1',
+                'policy_version_id' => '9',
+                'student_id'        => '5',
+                'registration_type' => PolicyAcceptance::REG_LESSON,
+                'registration_id'   => '12',
+                'accepted_at'       => '2026-06-02 09:00:00',
+                'ip_address'        => null,
+            ],
+        ]);
+
+        $rows = $this->repo->findByRegistration(PolicyAcceptance::REG_LESSON, 12);
+
+        self::assertCount(1, $rows);
+        self::assertInstanceOf(PolicyAcceptance::class, $rows[0]);
+    }
+}

tests/Unit/Policy/PolicyRepositoryTest.php

@@ -0,0 +1,94 @@
+<?php
+declare(strict_types=1);
+
+namespace Unsupervised\Schedular\Tests\Unit\Policy;
+
+use Brain\Monkey\Functions;
+use Mockery;
+use Unsupervised\Schedular\Policy\Policy;
+use Unsupervised\Schedular\Policy\PolicyRepository;
+use Unsupervised\Schedular\Tests\Unit\TestCase;
+
+class PolicyRepositoryTest extends TestCase
+{
+    private \wpdb $db;
+    private PolicyRepository $repo;
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+
+        $this->db         = Mockery::mock(\wpdb::class);
+        $this->db->prefix = 'wp_';
+        $this->repo       = new PolicyRepository($this->db);
+    }
+
+    public function testInsertReturnsId(): void
+    {
+        Functions\expect('current_time')->with('mysql')->andReturn('2026-06-01 12:00:00');
+
+        $this->db->shouldReceive('insert')
+            ->once()
+            ->with(
+                'wp_us_policies',
+                Mockery::on(static fn (array $d): bool => $d['title'] === 'Cancellation' && $d['slug'] === 'cancellation' && $d['current_version_id'] === null),
+                ['%s', '%s', '%d', '%s']
+            );
+        $this->db->insert_id = 7;
+
+        self::assertSame(7, $this->repo->insert(new Policy('Cancellation', 'cancellation')));
+    }
+
+    public function testUpdateCurrentVersion(): void
+    {
+        $this->db->shouldReceive('update')
+            ->once()
+            ->with('wp_us_policies', ['current_version_id' => 9], ['id' => 7], ['%d'], ['%d'])
+            ->andReturn(1);
+
+        self::assertTrue($this->repo->updateCurrentVersion(7, 9));
+    }
+
+    public function testFindBySlugReturnsPolicy(): void
+    {
+        $this->db->shouldReceive('prepare')->andReturn('SELECT ...');
+        $this->db->shouldReceive('get_row')->andReturn((object) [
+            'id'                 => '7',
+            'title'              => 'Cancellation',
+            'slug'               => 'cancellation',
+            'current_version_id' => null,
+        ]);
+
+        $policy = $this->repo->findBySlug('cancellation');
+
+        self::assertInstanceOf(Policy::class, $policy);
+        self::assertSame('cancellation', $policy->slug);
+    }
+
+    public function testFindBySlugReturnsNullWhenMissing(): void
+    {
+        $this->db->shouldReceive('prepare')->andReturn('SELECT ...');
+        $this->db->shouldReceive('get_row')->andReturn(null);
+
+        self::assertNull($this->repo->findBySlug('nope'));
+    }
+
+    public function testFindAllMapsRows(): void
+    {
+        $this->db->shouldReceive('get_results')->andReturn([
+            (object) ['id' => '1', 'title' => 'A', 'slug' => 'a', 'current_version_id' => null],
+        ]);
+
+        $all = $this->repo->findAll();
+
+        self::assertCount(1, $all);
+        self::assertInstanceOf(Policy::class, $all[0]);
+    }
+
+    public function testDeleteCallsWpdb(): void
+    {
+        $this->db->shouldReceive('delete')->once()->with('wp_us_policies', ['id' => 3], ['%d'])->andReturn(1);
+
+        self::assertTrue($this->repo->delete(3));
+    }
+}

tests/Unit/Policy/PolicyServiceTest.php

@@ -0,0 +1,91 @@
+<?php
+declare(strict_types=1);
+
+namespace Unsupervised\Schedular\Tests\Unit\Policy;
+
+use Brain\Monkey\Functions;
+use Mockery;
+use Unsupervised\Schedular\Policy\Policy;
+use Unsupervised\Schedular\Policy\PolicyRepository;
+use Unsupervised\Schedular\Policy\PolicyService;
+use Unsupervised\Schedular\Policy\PolicyVersion;
+use Unsupervised\Schedular\Policy\PolicyVersionRepository;
+use Unsupervised\Schedular\Tests\Unit\TestCase;
+
+class PolicyServiceTest extends TestCase
+{
+    private PolicyRepository $policies;
+    private PolicyVersionRepository $versions;
+    private PolicyService $service;
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+
+        $this->policies = Mockery::mock(PolicyRepository::class);
+        $this->versions = Mockery::mock(PolicyVersionRepository::class);
+        $this->service  = new PolicyService($this->policies, $this->versions);
+    }
+
+    public function testCreatePolicyInsertsPolicy(): void
+    {
+        $this->policies->shouldReceive('insert')
+            ->once()
+            ->with(Mockery::on(static fn (Policy $p): bool => $p->title === 'Cancellation' && $p->slug === 'cancellation'))
+            ->andReturn(7);
+
+        self::assertSame(7, $this->service->createPolicy('Cancellation', 'cancellation'));
+    }
+
+    public function testAddDraftVersionNumbersAfterLatest(): void
+    {
+        $this->versions->shouldReceive('maxVersionNumber')->once()->with(4)->andReturn(2);
+        $this->versions->shouldReceive('insert')
+            ->once()
+            ->with(Mockery::on(static function (PolicyVersion $v): bool {
+                return $v->policyId === 4
+                    && $v->versionNumber === 3
+                    && $v->status === PolicyVersion::STATUS_DRAFT;
+            }))
+            ->andReturn(15);
+
+        self::assertSame(15, $this->service->addDraftVersion(4, '<p>draft</p>'));
+    }
+
+    public function testPublishArchivesPriorCurrentAndPointsPolicyAtNewVersion(): void
+    {
+        Functions\expect('current_time')->with('mysql')->andReturn('2026-06-01 12:00:00');
+
+        $this->policies->shouldReceive('findById')->once()->with(4)->andReturn(new Policy('T', 't', 8, 4));
+        $this->versions->shouldReceive('findById')->once()->with(9)->andReturn(new PolicyVersion(4, 2, '<p>x</p>', PolicyVersion::STATUS_DRAFT, null, 9));
+
+        $this->versions->shouldReceive('updateStatus')->once()->with(8, PolicyVersion::STATUS_ARCHIVED);
+        $this->versions->shouldReceive('updateStatus')->once()->with(9, PolicyVersion::STATUS_PUBLISHED, '2026-06-01 12:00:00');
+        $this->policies->shouldReceive('updateCurrentVersion')->once()->with(4, 9)->andReturn(true);
+
+        self::assertTrue($this->service->publishVersion(4, 9));
+    }
+
+    public function testPublishFirstVersionDoesNotArchive(): void
+    {
+        Functions\expect('current_time')->andReturn('2026-06-01 12:00:00');
+
+        $this->policies->shouldReceive('findById')->once()->with(4)->andReturn(new Policy('T', 't', null, 4));
+        $this->versions->shouldReceive('findById')->once()->with(9)->andReturn(new PolicyVersion(4, 1, null, PolicyVersion::STATUS_DRAFT, null, 9));
+
+        // No archive call expected (no prior current version).
+        $this->versions->shouldReceive('updateStatus')->once()->with(9, PolicyVersion::STATUS_PUBLISHED, '2026-06-01 12:00:00');
+        $this->policies->shouldReceive('updateCurrentVersion')->once()->with(4, 9)->andReturn(true);
+
+        self::assertTrue($this->service->publishVersion(4, 9));
+    }
+
+    public function testPublishRejectsVersionFromAnotherPolicy(): void
+    {
+        $this->policies->shouldReceive('findById')->once()->with(4)->andReturn(new Policy('T', 't', null, 4));
+        $this->versions->shouldReceive('findById')->once()->with(9)->andReturn(new PolicyVersion(99, 1, null, PolicyVersion::STATUS_DRAFT, null, 9));
+
+        // No status/current-version writes when the version belongs elsewhere.
+        self::assertFalse($this->service->publishVersion(4, 9));
+    }
+}

tests/Unit/Policy/PolicyValueObjectsTest.php

@@ -0,0 +1,85 @@
+<?php
+declare(strict_types=1);
+
+namespace Unsupervised\Schedular\Tests\Unit\Policy;
+
+use Unsupervised\Schedular\Policy\Policy;
+use Unsupervised\Schedular\Policy\PolicyAcceptance;
+use Unsupervised\Schedular\Policy\PolicyVersion;
+use Unsupervised\Schedular\Tests\Unit\TestCase;
+
+class PolicyValueObjectsTest extends TestCase
+{
+    public function testPolicyFromRowAndToArray(): void
+    {
+        $policy = Policy::fromRow((object) [
+            'id'                 => '4',
+            'title'              => 'Cancellation',
+            'slug'               => 'cancellation',
+            'current_version_id' => '9',
+        ]);
+
+        self::assertSame(4, $policy->id);
+        self::assertSame('cancellation', $policy->slug);
+        self::assertSame(9, $policy->currentVersionId);
+        self::assertArrayHasKey('current_version_id', $policy->toArray());
+    }
+
+    public function testPolicyHandlesNullCurrentVersion(): void
+    {
+        $policy = Policy::fromRow((object) [
+            'id'                 => '4',
+            'title'              => 'Cancellation',
+            'slug'               => 'cancellation',
+            'current_version_id' => null,
+        ]);
+
+        self::assertNull($policy->currentVersionId);
+    }
+
+    public function testPolicyVersionFromRowAndStatusHelper(): void
+    {
+        $version = PolicyVersion::fromRow((object) [
+            'id'             => '9',
+            'policy_id'      => '4',
+            'version_number' => '2',
+            'body'           => '<p>Policy</p>',
+            'status'         => PolicyVersion::STATUS_PUBLISHED,
+            'published_at'   => '2026-06-01 10:00:00',
+        ]);
+
+        self::assertSame(9, $version->id);
+        self::assertSame(2, $version->versionNumber);
+        self::assertTrue($version->isPublished());
+        self::assertSame('2026-06-01 10:00:00', $version->publishedAt);
+    }
+
+    public function testPolicyVersionDefaultsToDraft(): void
+    {
+        $version = new PolicyVersion(4, 1);
+
+        self::assertSame(PolicyVersion::STATUS_DRAFT, $version->status);
+        self::assertFalse($version->isPublished());
+        self::assertNull($version->publishedAt);
+        self::assertContains(PolicyVersion::STATUS_ARCHIVED, PolicyVersion::VALID_STATUSES);
+    }
+
+    public function testPolicyAcceptanceFromRowAndToArray(): void
+    {
+        $acceptance = PolicyAcceptance::fromRow((object) [
+            'id'                => '1',
+            'policy_version_id' => '9',
+            'student_id'        => '5',
+            'registration_type' => PolicyAcceptance::REG_LESSON,
+            'registration_id'   => '12',
+            'accepted_at'       => '2026-06-02 09:00:00',
+            'ip_address'        => '203.0.113.7',
+        ]);
+
+        self::assertSame(9, $acceptance->policyVersionId);
+        self::assertSame(PolicyAcceptance::REG_LESSON, $acceptance->registrationType);
+        self::assertSame('203.0.113.7', $acceptance->ipAddress);
+        self::assertArrayHasKey('policy_version_id', $acceptance->toArray());
+        self::assertContains(PolicyAcceptance::REG_ENROLLMENT, PolicyAcceptance::VALID_REGISTRATION_TYPES);
+    }
+}

tests/Unit/Policy/PolicyVersionRepositoryTest.php

@@ -0,0 +1,103 @@
+<?php
+declare(strict_types=1);
+
+namespace Unsupervised\Schedular\Tests\Unit\Policy;
+
+use Brain\Monkey\Functions;
+use Mockery;
+use Unsupervised\Schedular\Policy\PolicyVersion;
+use Unsupervised\Schedular\Policy\PolicyVersionRepository;
+use Unsupervised\Schedular\Tests\Unit\TestCase;
+
+class PolicyVersionRepositoryTest extends TestCase
+{
+    private \wpdb $db;
+    private PolicyVersionRepository $repo;
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+
+        $this->db         = Mockery::mock(\wpdb::class);
+        $this->db->prefix = 'wp_';
+        $this->repo       = new PolicyVersionRepository($this->db);
+    }
+
+    public function testInsertReturnsId(): void
+    {
+        Functions\expect('current_time')->with('mysql')->andReturn('2026-06-01 12:00:00');
+
+        $this->db->shouldReceive('insert')
+            ->once()
+            ->with(
+                'wp_us_policy_versions',
+                Mockery::on(static fn (array $d): bool => $d['policy_id'] === 4 && $d['version_number'] === 1 && $d['status'] === PolicyVersion::STATUS_DRAFT),
+                ['%d', '%d', '%s', '%s', '%s', '%s']
+            );
+        $this->db->insert_id = 9;
+
+        self::assertSame(9, $this->repo->insert(new PolicyVersion(4, 1, '<p>x</p>')));
+    }
+
+    public function testUpdateStatusWithPublishedAt(): void
+    {
+        $this->db->shouldReceive('update')
+            ->once()
+            ->with(
+                'wp_us_policy_versions',
+                ['status' => PolicyVersion::STATUS_PUBLISHED, 'published_at' => '2026-06-01 12:00:00'],
+                ['id' => 9],
+                ['%s', '%s'],
+                ['%d']
+            )
+            ->andReturn(1);
+
+        self::assertTrue($this->repo->updateStatus(9, PolicyVersion::STATUS_PUBLISHED, '2026-06-01 12:00:00'));
+    }
+
+    public function testUpdateBody(): void
+    {
+        $this->db->shouldReceive('update')
+            ->once()
+            ->with('wp_us_policy_versions', ['body' => '<p>new</p>'], ['id' => 9], ['%s'], ['%d'])
+            ->andReturn(1);
+
+        self::assertTrue($this->repo->updateBody(9, '<p>new</p>'));
+    }
+
+    public function testMaxVersionNumberReturnsZeroWhenNone(): void
+    {
+        $this->db->shouldReceive('prepare')->andReturn('SELECT ...');
+        $this->db->shouldReceive('get_var')->andReturn(null);
+
+        self::assertSame(0, $this->repo->maxVersionNumber(4));
+    }
+
+    public function testMaxVersionNumberCastsResult(): void
+    {
+        $this->db->shouldReceive('prepare')->andReturn('SELECT ...');
+        $this->db->shouldReceive('get_var')->andReturn('3');
+
+        self::assertSame(3, $this->repo->maxVersionNumber(4));
+    }
+
+    public function testFindByPolicyMapsRows(): void
+    {
+        $this->db->shouldReceive('prepare')->andReturn('SELECT ...');
+        $this->db->shouldReceive('get_results')->andReturn([
+            (object) [
+                'id'             => '9',
+                'policy_id'      => '4',
+                'version_number' => '1',
+                'body'           => null,
+                'status'         => PolicyVersion::STATUS_DRAFT,
+                'published_at'   => null,
+            ],
+        ]);
+
+        $versions = $this->repo->findByPolicy(4);
+
+        self::assertCount(1, $versions);
+        self::assertInstanceOf(PolicyVersion::class, $versions[0]);
+    }
+}