Add batch Subject-ID minting and client-supplied create IDs (#1101)

Fixes #1100

Importing many interlinked Subjects needs their IDs known before the Subjects
exist, so relation statements can be wired client-side and the Subjects created
in any order. Two additions cover this:

- POST /neowiki/v0/subject-ids mints a batch of fresh, distinct, format-valid
  Subject IDs. Body `count` (1-1000). Stateless: no reservation and no graph
  dependency. Access model matches the validate endpoint (no write access, no
  CSRF, no page authorization). A small application-layer SubjectIdMinter holds
  the dedupe/regenerate loop; the handler enforces the count range.
- The create endpoints accept an optional `id`. When present it is format-checked
  at the request boundary (400) and rejected when already in use (409), both
  against the page's own Subjects and, best-effort, the graph's subject->page
  index. When absent the server mints as before, and the default create path
  gains no new graph dependency.

Also closes a duplicate-guard gap that client-supplied IDs make reachable: the
page-local create guards now consider every Subject on the page (main and
children), not just the sibling collection.

Global Subject-ID uniqueness stays best-effort: the subject->page index lags slot
writes and ID entropy carries the rest, the same posture already used for
client-supplied relation IDs.

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: JeroenDeDauw

docs/api/rest-api.md

@@ -53,6 +53,7 @@ Read, change, and validate Subjects. New Subjects are created on a page — see
 | `DELETE /neowiki/v0/subject/{subjectId}` | Delete a Subject. |
 | `POST /neowiki/v0/subject/validate` | Check whether a new Subject is valid, without saving it. |
 | `POST /neowiki/v0/subject/{subjectId}/validate` | Check whether a change to a Subject is valid, without saving it. |
+| `POST /neowiki/v0/subject-ids` | Mint a batch of unused Subject IDs to assign on create, e.g. to wire relations across an interlinked import. Body `count` (1–1000). |
 | `GET /neowiki/v0/subject-labels` | Find Subjects of a Schema by label; returns `id`/`label` pairs. |
 
 ### Pages and Subjects

docs/api/subject-format.md

@@ -200,6 +200,23 @@ Returns the same statement format as storage, with additional fields:
 - Passing `?expand=relations` also embeds the Subjects targeted by this Subject's relation values; see
   [REST API](rest-api.md#the-expand-parameter) for the response shape.
 
+### Creating Subjects
+
+`POST /rest.php/neowiki/v0/page/{pageId}/mainSubject`
+`POST /rest.php/neowiki/v0/page/{pageId}/childSubjects`
+
+Create a Subject on a page from a [Subject object](#subject-object) (`label`, `schema`, `statements`),
+with an optional `comment` edit summary.
+
+The Subject ID is normally minted server-side. To set it yourself — for example to wire relations across
+a batch before the target Subjects exist — pass an optional `id`:
+
+| Field | Required | Notes |
+|---|---|---|
+| `id` | No | Subject ID to assign. Must be well-formed (`400` otherwise) and unused (`409` otherwise). Omit to have the server mint one. Pre-mint a batch of IDs with `POST /neowiki/v0/subject-ids`. |
+
+After creation the ID is immutable; the replace endpoint below ignores it.
+
 ### Writing Subjects
 
 `PUT /rest.php/neowiki/v0/subject/{subjectId}`

extension.json

@@ -289,6 +289,11 @@
 			"method": [ "GET" ],
 			"factory": "ProfessionalWiki\\NeoWiki\\NeoWikiExtension::newGetSchemaSummariesApi"
 		},
+		{
+			"path": "/neowiki/v0/subject-ids",
+			"method": [ "POST" ],
+			"factory": "ProfessionalWiki\\NeoWiki\\NeoWikiExtension::newMintSubjectIdsApi"
+		},
 		{
 			"path": "/neowiki/v0/subject/validate",
 			"method": [ "POST" ],

src/Application/Actions/CreateSubject/CreateSubjectAction.php

@@ -5,6 +5,7 @@
 namespace ProfessionalWiki\NeoWiki\Application\Actions\CreateSubject;
 
 use InvalidArgumentException;
+use ProfessionalWiki\NeoWiki\Application\PageIdentifiersLookup;
 use ProfessionalWiki\NeoWiki\Application\SchemaLookup;
 use ProfessionalWiki\NeoWiki\Application\SelectStatementResolver;
 use ProfessionalWiki\NeoWiki\Application\StatementListBuilder;
@@ -14,6 +15,7 @@
 use ProfessionalWiki\NeoWiki\Domain\Page\PageId;
 use ProfessionalWiki\NeoWiki\Domain\Schema\SchemaName;
 use ProfessionalWiki\NeoWiki\Domain\Subject\Subject;
+use ProfessionalWiki\NeoWiki\Domain\Subject\SubjectId;
 use ProfessionalWiki\NeoWiki\Domain\Subject\SubjectLabel;
 use ProfessionalWiki\NeoWiki\Domain\Validation\Violation;
 use ProfessionalWiki\NeoWiki\Infrastructure\IdGenerator;
@@ -30,6 +32,7 @@ public function __construct(
 		private SchemaLookup $schemaLookup,
 		private SelectStatementResolver $selectStatementResolver,
 		private ProposedSubjectValidator $proposedSubjectValidator,
+		private PageIdentifiersLookup $pageIdentifiersLookup,
 		private bool $validationEnforced,
 	) {
 	}
@@ -47,6 +50,11 @@ public function createSubject( CreateSubjectRequest $request ): void {
 
 		$subject = $this->buildSubject( $request );
 
+		if ( $request->id !== null && $this->subjectIdIsInUse( $subject->id ) ) {
+			$this->presenter->presentSubjectAlreadyExists();
+			return;
+		}
+
 		$pageSubjects = $this->subjectRepository->getSubjectsByPageId( $pageId );
 
 		try {
@@ -84,17 +92,36 @@ private function blockingViolations( array $violations ): array {
 
 	private function buildSubject( CreateSubjectRequest $request ): Subject {
 		$schemaName = new SchemaName( $request->schemaName );
+		$label = new SubjectLabel( $request->label );
+		$statements = $this->statementListBuilder->build(
+			$this->resolveSelectValues( $schemaName, $request->statements )
+		);
 
-		return Subject::createNew(
-			idGenerator: $this->idGenerator,
-			label: new SubjectLabel( $request->label ),
+		if ( $request->id === null ) {
+			return Subject::createNew(
+				idGenerator: $this->idGenerator,
+				label: $label,
+				schemaName: $schemaName,
+				statements: $statements,
+			);
+		}
+
+		return new Subject(
+			id: new SubjectId( $request->id ),
+			label: $label,
 			schemaName: $schemaName,
-			statements: $this->statementListBuilder->build(
-				$this->resolveSelectValues( $schemaName, $request->statements )
-			)
+			statements: $statements,
 		);
 	}
 
+	/**
+	 * Best-effort global uniqueness check: the subject -> page index lags slot writes, so this can
+	 * miss a very recently created Subject; ID entropy carries the rest (same posture as relation IDs).
+	 */
+	private function subjectIdIsInUse( SubjectId $id ): bool {
+		return $this->pageIdentifiersLookup->getPageIdOfSubject( $id ) !== null;
+	}
+
 	/**
 	 * @param array<string, mixed> $statements
 	 *

src/Application/Actions/CreateSubject/CreateSubjectRequest.php

@@ -20,6 +20,11 @@ public function __construct(
 		public array $statements,
 
 		public ?string $comment = null,
+
+		/**
+		 * Client-supplied Subject ID. Must be well-formed and unused; when null the server mints one.
+		 */
+		public ?string $id = null,
 	) {
 	}
 

src/Application/SubjectIdMinter.php

@@ -0,0 +1,35 @@
+<?php
+
+declare( strict_types = 1 );
+
+namespace ProfessionalWiki\NeoWiki\Application;
+
+use ProfessionalWiki\NeoWiki\Domain\Subject\SubjectId;
+use ProfessionalWiki\NeoWiki\Infrastructure\IdGenerator;
+
+/**
+ * Mints batches of fresh, mutually distinct Subject IDs for client-side wiring of interlinked
+ * imports. Generation stays server-owned so the ID scheme can evolve without breaking importers.
+ */
+readonly class SubjectIdMinter {
+
+	public function __construct(
+		private IdGenerator $idGenerator,
+	) {
+	}
+
+	/**
+	 * @return list<SubjectId> exactly $count distinct ids
+	 */
+	public function mint( int $count ): array {
+		$ids = [];
+
+		while ( count( $ids ) < $count ) {
+			$id = SubjectId::createNew( $this->idGenerator );
+			$ids[$id->text] = $id;
+		}
+
+		return array_values( $ids );
+	}
+
+}

src/Domain/Page/PageSubjects.php

@@ -91,17 +91,25 @@ public function createMainSubject( Subject $subject ): void {
 			throw new RuntimeException( 'Main subject already exists' );
 		}
 
+		if ( $this->childSubjects->hasSubject( $subject->id ) ) {
+			throw new RuntimeException( 'Subject already exists' );
+		}
+
 		$this->mainSubject = $subject;
 	}
 
 	public function createChildSubject( Subject $subject ): void {
-		if ( $this->childSubjects->hasSubject( $subject->id ) ) {
-			throw new RuntimeException( 'Child subject already exists' );
+		if ( $this->hasSubjectWithId( $subject->id ) ) {
+			throw new RuntimeException( 'Subject already exists' );
 		}
 
 		$this->childSubjects->addOrUpdateSubject( $subject );
 	}
 
+	private function hasSubjectWithId( SubjectId $id ): bool {
+		return $this->isMainSubject( $id ) || $this->childSubjects->hasSubject( $id );
+	}
+
 	/**
 	 * Atomically set the main subject and child subject ordering. The set of
 	 * ids in $mainId (if non-null) and $childIds must match exactly the set of

src/EntryPoints/REST/CreateSubjectApi.php

@@ -7,6 +7,7 @@
 use MediaWiki\Rest\Response;
 use MediaWiki\Rest\SimpleHandler;
 use ProfessionalWiki\NeoWiki\Application\Actions\CreateSubject\CreateSubjectRequest;
+use ProfessionalWiki\NeoWiki\Domain\Subject\SubjectId;
 use ProfessionalWiki\NeoWiki\NeoWikiExtension;
 use ProfessionalWiki\NeoWiki\Presentation\CsrfValidator;
 use ProfessionalWiki\NeoWiki\Presentation\RestCreateSubjectPresenter;
@@ -25,6 +26,15 @@ public function run( int $pageId ): Response {
 
 		$body = $this->getValidatedBody();
 
+		$id = $body['id'] ?? null;
+
+		if ( $id !== null && !SubjectId::isValid( $id ) ) {
+			return $this->getResponseFactory()->createHttpError( 400, [
+				'status' => 'error',
+				'message' => "Subject ID has the wrong format: '$id'",
+			] );
+		}
+
 		$presenter = new RestCreateSubjectPresenter();
 
 		try {
@@ -36,6 +46,7 @@ public function run( int $pageId ): Response {
 					schemaName: $body['schema'],
 					statements: $body['statements'],
 					comment: $body['comment'] ?? null,
+					id: $id,
 				)
 			);
 		} catch ( \InvalidArgumentException $e ) {
@@ -92,6 +103,14 @@ public function getBodyParamSettings(): array {
 				ParamValidator::PARAM_REQUIRED => false,
 				self::PARAM_DESCRIPTION => 'Optional edit summary.',
 			],
+			'id' => [
+				self::PARAM_SOURCE => 'body',
+				ParamValidator::PARAM_TYPE => 'string',
+				ParamValidator::PARAM_REQUIRED => false,
+				self::PARAM_DESCRIPTION => 'Optional Subject ID to assign. Must be a well-formed, unused '
+					. 'Subject ID (malformed is rejected with 400, in-use with 409). When omitted, the server '
+					. 'mints one. Pre-mint IDs with POST /neowiki/v0/subject-ids to wire relations across a batch.',
+			],
 		];
 	}
 

src/EntryPoints/REST/MintSubjectIdsApi.php

@@ -0,0 +1,61 @@
+<?php
+
+declare( strict_types = 1 );
+
+namespace ProfessionalWiki\NeoWiki\EntryPoints\REST;
+
+use MediaWiki\Rest\Response;
+use MediaWiki\Rest\SimpleHandler;
+use ProfessionalWiki\NeoWiki\Application\SubjectIdMinter;
+use ProfessionalWiki\NeoWiki\Domain\Subject\SubjectId;
+use Wikimedia\ParamValidator\ParamValidator;
+
+/**
+ * Mints a batch of unused Subject IDs so an importer can wire relations between interlinked Subjects
+ * before creating them. Stateless: no reservation, no graph dependency. See docs/api/subject-format.md.
+ */
+class MintSubjectIdsApi extends SimpleHandler {
+
+	private const int MIN_COUNT = 1;
+	private const int MAX_COUNT = 1000;
+
+	public function __construct(
+		private readonly SubjectIdMinter $subjectIdMinter,
+	) {
+	}
+
+	public function run(): Response {
+		$count = $this->getValidatedBody()['count'];
+
+		if ( $count < self::MIN_COUNT || $count > self::MAX_COUNT ) {
+			return $this->getResponseFactory()->createHttpError( 400, [
+				'status' => 'error',
+				'message' => 'count must be between ' . self::MIN_COUNT . ' and ' . self::MAX_COUNT . '.',
+			] );
+		}
+
+		return $this->getResponseFactory()->createJson( [
+			'subjectIds' => array_map(
+				static fn ( SubjectId $id ): string => $id->text,
+				$this->subjectIdMinter->mint( $count )
+			),
+		] );
+	}
+
+	public function getBodyParamSettings(): array {
+		return [
+			'count' => [
+				self::PARAM_SOURCE => 'body',
+				ParamValidator::PARAM_TYPE => 'integer',
+				ParamValidator::PARAM_REQUIRED => true,
+				self::PARAM_DESCRIPTION => 'Number of Subject IDs to mint, between '
+					. self::MIN_COUNT . ' and ' . self::MAX_COUNT . ' inclusive.',
+			],
+		];
+	}
+
+	public function needsWriteAccess(): bool {
+		return false;
+	}
+
+}

src/NeoWikiExtension.php

@@ -60,6 +60,7 @@
 use ProfessionalWiki\NeoWiki\Application\PageReadAuthorizer;
 use ProfessionalWiki\NeoWiki\Application\SubjectWriteAuthorizer;
 use ProfessionalWiki\NeoWiki\Application\SubjectPageRebuilder;
+use ProfessionalWiki\NeoWiki\Application\SubjectIdMinter;
 use ProfessionalWiki\NeoWiki\Application\SubjectRepository;
 use ProfessionalWiki\NeoWiki\Application\MappingLookup;
 use ProfessionalWiki\NeoWiki\Application\Rdf\OntologyMappingProjector;
@@ -93,6 +94,7 @@
 use ProfessionalWiki\NeoWiki\EntryPoints\REST\GetSchemaSummariesApi;
 use ProfessionalWiki\NeoWiki\EntryPoints\REST\GetSubjectApi;
 use ProfessionalWiki\NeoWiki\EntryPoints\REST\GetSubjectLabelsApi;
+use ProfessionalWiki\NeoWiki\EntryPoints\REST\MintSubjectIdsApi;
 use ProfessionalWiki\NeoWiki\GraphDatabasePlugins\Neo4j\EntryPoints\REST\CypherQueryApi;
 use ProfessionalWiki\NeoWiki\GraphDatabasePlugins\Neo4j\EntryPoints\REST\Neo4jRouteRegistration;
 use ProfessionalWiki\NeoWiki\EntryPoints\REST\ReplaceSubjectApi;
@@ -812,10 +814,15 @@ public function newCreateSubjectAction( CreateSubjectPresenter $presenter, Autho
 			schemaLookup: $this->getSchemaLookup(),
 			selectStatementResolver: $this->getSelectStatementResolver(),
 			proposedSubjectValidator: $this->getProposedSubjectValidator(),
+			pageIdentifiersLookup: $this->getPageIdentifiersLookup(),
 			validationEnforced: $this->isValidationEnforced(),
 		);
 	}
 
+	public function newSubjectIdMinter(): SubjectIdMinter {
+		return new SubjectIdMinter( $this->getIdGenerator() );
+	}
+
 	public function getSelectStatementResolver(): SelectStatementResolver {
 		return new SelectStatementResolver( new SelectValueResolver() );
 	}
@@ -1090,6 +1097,12 @@ public static function newValidateSubjectApi(): ValidateSubjectApi {
 		);
 	}
 
+	public static function newMintSubjectIdsApi(): MintSubjectIdsApi {
+		return new MintSubjectIdsApi(
+			subjectIdMinter: self::getInstance()->newSubjectIdMinter(),
+		);
+	}
+
 	public static function newValidateSubjectUpdateApi(): ValidateSubjectUpdateApi {
 		return new ValidateSubjectUpdateApi();
 	}