feat(promo-codes): add SummitPromoCodeMemberReservation entity (data layer)

Schema + data layer for the per-member QuantityPerAccount counter that
will fix the TOCTOU race smarcet flagged in PR #525 (and reproduced in
PR #530). This commit is intentionally NOT wired into the order-reserve
saga yet — the table sits unused until the follow-up commit that
modifies PreProcessReservationTask.

- Entity SummitPromoCodeMemberReservation (SilverstripeBaseModel) with
  unique (PromoCodeID, MemberID) and ManyToOne FKs cascading on delete.
- ISummitPromoCodeMemberReservationRepository + Doctrine impl. Readers
  from the reservation path rely on the outer row lock already held on
  the parent promo code (getByValueExclusiveLock) for serialization,
  so the repo does not take its own PESSIMISTIC_WRITE.
- Two migrations, split so CREATE TABLE commits before the backfill
  INSERT runs (Builder defers schema diff to end-of-migration, so
  INSERT-in-same-migration hits "table doesn't exist"):
    Version20260415191521 — create table via Builder/Table API.
    Version20260415191522 — backfill from existing committed tickets
                            (ON DUPLICATE KEY UPDATE for idempotency).
- RepositoriesProvider binding.
- Verified: down/up round-trip on docker MySQL; php -l clean.

Author: caseylocker

app/Models/Foundation/Summit/Registration/PromoCodes/SummitPromoCodeMemberReservation.php

@@ -0,0 +1,106 @@
+<?php namespace models\summit;
+/**
+ * Copyright 2026 OpenStack Foundation
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ * http://www.apache.org/licenses/LICENSE-2.0
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ **/
+
+use Doctrine\ORM\Mapping as ORM;
+use InvalidArgumentException;
+use models\main\Member;
+use models\utils\SilverstripeBaseModel;
+
+/**
+ * Durable per-member usage counter for a single promo code.
+ *
+ * Written atomically inside the exclusive row lock held on the parent
+ * SummitRegistrationPromoCode (via getByValueExclusiveLock) so that
+ * concurrent order reservations serialize their QuantityPerAccount
+ * check-and-increment.
+ *
+ * @package models\summit
+ */
+#[ORM\Table(name: 'SummitPromoCodeMemberReservation')]
+#[ORM\UniqueConstraint(name: 'UQ_PromoCode_Member', columns: ['PromoCodeID', 'MemberID'])]
+#[ORM\Entity(repositoryClass: \App\Repositories\Summit\DoctrineSummitPromoCodeMemberReservationRepository::class)]
+class SummitPromoCodeMemberReservation extends SilverstripeBaseModel
+{
+    /**
+     * @var int
+     */
+    #[ORM\Column(name: 'QtyUsed', type: 'integer', nullable: false)]
+    private $qty_used;
+
+    /**
+     * @var SummitRegistrationPromoCode
+     */
+    #[ORM\ManyToOne(targetEntity: \models\summit\SummitRegistrationPromoCode::class)]
+    #[ORM\JoinColumn(name: 'PromoCodeID', referencedColumnName: 'ID', nullable: false, onDelete: 'CASCADE')]
+    private $promo_code;
+
+    /**
+     * @var Member
+     */
+    #[ORM\ManyToOne(targetEntity: \models\main\Member::class)]
+    #[ORM\JoinColumn(name: 'MemberID', referencedColumnName: 'ID', nullable: false, onDelete: 'CASCADE')]
+    private $member;
+
+    public function __construct(SummitRegistrationPromoCode $promo_code, Member $member, int $qty_used = 0)
+    {
+        parent::__construct();
+        if ($qty_used < 0) {
+            throw new InvalidArgumentException('qty_used must be non-negative');
+        }
+        $this->promo_code = $promo_code;
+        $this->member = $member;
+        $this->qty_used = $qty_used;
+    }
+
+    public function getQtyUsed(): int
+    {
+        return (int)$this->qty_used;
+    }
+
+    public function getPromoCode(): SummitRegistrationPromoCode
+    {
+        return $this->promo_code;
+    }
+
+    public function getMember(): Member
+    {
+        return $this->member;
+    }
+
+    /**
+     * Atomically raise qty_used by $by.
+     *
+     * @throws InvalidArgumentException when $by is negative.
+     */
+    public function increment(int $by): void
+    {
+        if ($by < 0) {
+            throw new InvalidArgumentException('increment amount must be non-negative');
+        }
+        $this->qty_used += $by;
+    }
+
+    /**
+     * Lower qty_used by $by, clamping at zero. Used by saga undo paths.
+     *
+     * @throws InvalidArgumentException when $by is negative.
+     */
+    public function decrement(int $by): void
+    {
+        if ($by < 0) {
+            throw new InvalidArgumentException('decrement amount must be non-negative');
+        }
+        $this->qty_used = max(0, $this->qty_used - $by);
+    }
+}

app/Models/Foundation/Summit/Repositories/ISummitPromoCodeMemberReservationRepository.php

@@ -0,0 +1,41 @@
+<?php namespace models\summit;
+/**
+ * Copyright 2026 OpenStack Foundation
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ * http://www.apache.org/licenses/LICENSE-2.0
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ **/
+
+use models\main\Member;
+use models\utils\IBaseRepository;
+
+/**
+ * Interface ISummitPromoCodeMemberReservationRepository
+ * @package models\summit
+ */
+interface ISummitPromoCodeMemberReservationRepository extends IBaseRepository
+{
+    /**
+     * Look up the per-member reservation row for a given promo code.
+     *
+     * Callers invoking this from the reservation path must already hold an
+     * exclusive row lock on the parent SummitRegistrationPromoCode (via
+     * ISummitRegistrationPromoCodeRepository::getByValueExclusiveLock). That
+     * outer lock is what serializes concurrent access to this row — no
+     * separate PESSIMISTIC_WRITE is taken here.
+     *
+     * @param SummitRegistrationPromoCode $code
+     * @param Member $member
+     * @return SummitPromoCodeMemberReservation|null
+     */
+    public function getByPromoCodeAndMember(
+        SummitRegistrationPromoCode $code,
+        Member $member
+    ): ?SummitPromoCodeMemberReservation;
+}

app/Repositories/RepositoriesProvider.php

@@ -133,6 +133,7 @@
 use models\summit\ISummitProposedScheduleEventRepository;
 use models\summit\ISummitProposedScheduleLockRepository;
 use models\summit\ISummitProposedScheduleRepository;
+use models\summit\ISummitPromoCodeMemberReservationRepository;
 use models\summit\ISummitRegistrationPromoCodeRepository;
 use models\summit\ISummitTicketTypeRepository;
 use models\summit\PaymentGatewayProfile;
@@ -176,6 +177,7 @@
 use models\summit\SummitRefundPolicyType;
 use models\summit\SummitRefundRequest;
 use models\summit\SummitRegistrationInvitation;
+use models\summit\SummitPromoCodeMemberReservation;
 use models\summit\SummitRegistrationPromoCode;
 use models\summit\SummitRoomReservation;
 use models\summit\SummitScheduleConfig;
@@ -424,6 +426,13 @@ function () {
             }
         );
 
+        App::singleton(
+            ISummitPromoCodeMemberReservationRepository::class,
+            function () {
+                return EntityManager::getRepository(SummitPromoCodeMemberReservation::class);
+            }
+        );
+
         App::singleton(
             ISpeakersSummitRegistrationPromoCodeRepository::class,
             function () {

app/Repositories/Summit/DoctrineSummitPromoCodeMemberReservationRepository.php

@@ -0,0 +1,47 @@
+<?php namespace App\Repositories\Summit;
+/**
+ * Copyright 2026 OpenStack Foundation
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ * http://www.apache.org/licenses/LICENSE-2.0
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ **/
+
+use App\Repositories\SilverStripeDoctrineRepository;
+use models\main\Member;
+use models\summit\ISummitPromoCodeMemberReservationRepository;
+use models\summit\SummitPromoCodeMemberReservation;
+use models\summit\SummitRegistrationPromoCode;
+
+/**
+ * Class DoctrineSummitPromoCodeMemberReservationRepository
+ * @package App\Repositories\Summit
+ */
+final class DoctrineSummitPromoCodeMemberReservationRepository
+    extends SilverStripeDoctrineRepository
+    implements ISummitPromoCodeMemberReservationRepository
+{
+    protected function getBaseEntity()
+    {
+        return SummitPromoCodeMemberReservation::class;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getByPromoCodeAndMember(
+        SummitRegistrationPromoCode $code,
+        Member $member
+    ): ?SummitPromoCodeMemberReservation
+    {
+        return $this->findOneBy([
+            'promo_code' => $code,
+            'member'     => $member,
+        ]);
+    }
+}

database/migrations/model/Version20260415191521.php

@@ -0,0 +1,86 @@
+<?php namespace Database\Migrations\Model;
+/**
+ * Copyright 2026 OpenStack Foundation
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ * http://www.apache.org/licenses/LICENSE-2.0
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ **/
+
+use Doctrine\Migrations\AbstractMigration;
+use Doctrine\DBAL\Schema\Schema as Schema;
+use LaravelDoctrine\Migrations\Schema\Builder;
+use LaravelDoctrine\Migrations\Schema\Table;
+
+/**
+ * Class Version20260415191521
+ * @package Database\Migrations\Model
+ *
+ * Creates the SummitPromoCodeMemberReservation table used to atomically
+ * track per-member QuantityPerAccount usage for domain-authorized promo
+ * codes. Fixes the TOCTOU race documented in smarcet's PR #530. A
+ * companion migration (Version20260415191522) backfills the table from
+ * existing committed tickets — it runs after this one so the CREATE
+ * TABLE has fully committed before the INSERT executes.
+ */
+final class Version20260415191521 extends AbstractMigration
+{
+    private const TableName = 'SummitPromoCodeMemberReservation';
+
+    public function getDescription(): string
+    {
+        return 'Create SummitPromoCodeMemberReservation counter table.';
+    }
+
+    public function up(Schema $schema): void
+    {
+        $builder = new Builder($schema);
+
+        if (!$builder->hasTable(self::TableName)) {
+            $builder->create(self::TableName, function (Table $table) {
+                $table->integer('ID', true, false);
+                $table->primary('ID');
+
+                $table->timestamp('Created')->setNotnull(true);
+                $table->timestamp('LastEdited')->setNotnull(true);
+
+                $table->integer('QtyUsed')->setNotnull(true)->setDefault(0);
+
+                $table->integer('PromoCodeID', false, false)->setNotnull(true);
+                $table->index('PromoCodeID', 'PromoCodeID');
+                $table->foreign(
+                    'SummitRegistrationPromoCode',
+                    'PromoCodeID',
+                    'ID',
+                    ['onDelete' => 'CASCADE'],
+                    'FK_PromoCodeMemberReservation_PromoCode'
+                );
+
+                $table->integer('MemberID', false, false)->setNotnull(true);
+                $table->index('MemberID', 'MemberID');
+                $table->foreign(
+                    'Member',
+                    'MemberID',
+                    'ID',
+                    ['onDelete' => 'CASCADE'],
+                    'FK_PromoCodeMemberReservation_Member'
+                );
+
+                $table->unique(['PromoCodeID', 'MemberID'], 'UQ_PromoCode_Member');
+            });
+        }
+    }
+
+    public function down(Schema $schema): void
+    {
+        $builder = new Builder($schema);
+        if ($builder->hasTable(self::TableName)) {
+            $builder->dropIfExists(self::TableName);
+        }
+    }
+}

database/migrations/model/Version20260415191522.php

@@ -0,0 +1,71 @@
+<?php namespace Database\Migrations\Model;
+/**
+ * Copyright 2026 OpenStack Foundation
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ * http://www.apache.org/licenses/LICENSE-2.0
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ **/
+
+use Doctrine\Migrations\AbstractMigration;
+use Doctrine\DBAL\Schema\Schema as Schema;
+use LaravelDoctrine\Migrations\Schema\Builder;
+
+/**
+ * Class Version20260415191522
+ * @package Database\Migrations\Model
+ *
+ * Backfills SummitPromoCodeMemberReservation from existing committed tickets
+ * so the per-member QuantityPerAccount counter starts consistent with
+ * history. Must run AFTER Version20260415191521, which creates the table.
+ *
+ * Deployment note: orders in flight during the backfill window may be
+ * miscounted by at most their own qty — prefer a quiet window.
+ */
+final class Version20260415191522 extends AbstractMigration
+{
+    public function getDescription(): string
+    {
+        return 'Backfill SummitPromoCodeMemberReservation from existing committed tickets.';
+    }
+
+    public function up(Schema $schema): void
+    {
+        $builder = new Builder($schema);
+        if (!$builder->hasTable('SummitPromoCodeMemberReservation')) {
+            // Upstream migration didn't run — skip rather than crash.
+            return;
+        }
+
+        $this->addSql(<<<SQL
+INSERT INTO SummitPromoCodeMemberReservation (PromoCodeID, MemberID, QtyUsed, Created, LastEdited)
+SELECT t.PromoCodeID,
+       o.OwnerID,
+       COUNT(*) AS qty,
+       NOW(),
+       NOW()
+FROM SummitAttendeeTicket t
+INNER JOIN SummitOrder o ON o.ID = t.OrderID
+WHERE t.PromoCodeID IS NOT NULL
+  AND o.OwnerID IS NOT NULL
+  AND o.Status IN ('Reserved', 'Paid', 'Confirmed')
+  AND t.Status != 'Cancelled'
+GROUP BY t.PromoCodeID, o.OwnerID
+ON DUPLICATE KEY UPDATE QtyUsed = VALUES(QtyUsed), LastEdited = NOW()
+SQL
+        );
+    }
+
+    public function down(Schema $schema): void
+    {
+        $builder = new Builder($schema);
+        if ($builder->hasTable('SummitPromoCodeMemberReservation')) {
+            $this->addSql('TRUNCATE TABLE SummitPromoCodeMemberReservation');
+        }
+    }
+}