retrofit: annotate openbuilt Bucket 1 (142 methods / 71 REQs)

.git-blame-ignore-revs

@@ -0,0 +1,2 @@
+# Retrofit annotation commit (opsx-annotate, 2026-05-24)
+770ffed41a22f3a45e00e98a8484ca72330eefc9

lib/BackgroundJob/CleanupExpiredExports.php

@@ -17,6 +17,8 @@
  *
  * @link https://conduction.nl
  *
+ * @spec openspec/changes/retrofit-2026-05-24-annotate-openbuilt/tasks.md#task-36
+ *
  * @SPDX-License-Identifier: EUPL-1.2
  * @SPDX-FileCopyrightText:  2026 Conduction B.V. <info@conduction.nl>
  */
@@ -60,6 +62,8 @@ public function __construct(
      * @return void
      *
      * @SuppressWarnings(PHPMD.UnusedFormalParameter)
+     *
+     * @spec openspec/changes/retrofit-2026-05-24-annotate-openbuilt/tasks.md#task-36
      */
     protected function run($argument): void
     {

lib/BackgroundJob/RunExportJob.php

@@ -18,6 +18,9 @@
  *
  * @link https://conduction.nl
  *
+ * @spec openspec/changes/retrofit-2026-05-24-annotate-openbuilt/tasks.md#task-33
+ * @spec openspec/changes/retrofit-2026-05-24-annotate-openbuilt/tasks.md#task-34
+ *
  * @SPDX-License-Identifier: EUPL-1.2
  * @SPDX-FileCopyrightText:  2026 Conduction B.V. <info@conduction.nl>
  */
@@ -68,6 +71,8 @@ public function __construct(
      *                        ['jobUuid' => string].
      *
      * @return void
+     *
+     * @spec openspec/changes/retrofit-2026-05-24-annotate-openbuilt/tasks.md#task-33
      */
     protected function run($argument): void
     {
@@ -126,6 +131,8 @@ private function extractJobUuid($argument): string
      * @param string $jobUuid Job UUID.
      *
      * @return void
+     *
+     * @spec openspec/changes/retrofit-2026-05-24-annotate-openbuilt/tasks.md#task-33
      */
     private function executePipeline(string $jobUuid): void
     {
@@ -161,6 +168,8 @@ private function executePipeline(string $jobUuid): void
      * @param string $zipPath Path to the generated ZIP.
      *
      * @return array{repoUrl?:string,pullRequestUrl?:string}|null
+     *
+     * @spec openspec/changes/retrofit-2026-05-24-annotate-openbuilt/tasks.md#task-34
      */
     private function maybePush(string $jobUuid, string $zipPath): ?array
     {

lib/Controller/ApplicationCreationController.php

@@ -25,6 +25,10 @@
  * @version GIT: <git-id>
  *
  * @link https://conduction.nl
+ *
+ * @spec openspec/changes/retrofit-2026-05-24-annotate-openbuilt/tasks.md#task-8
+ * @spec openspec/changes/retrofit-2026-05-24-annotate-openbuilt/tasks.md#task-12
+ * @spec openspec/changes/retrofit-2026-05-24-annotate-openbuilt/tasks.md#task-15
  */
 
 declare(strict_types=1);
@@ -78,6 +82,10 @@ public function __construct(
      * Returns 401 when the caller is not authenticated.
      *
      * @return JSONResponse
+     *
+     * @spec openspec/changes/retrofit-2026-05-24-annotate-openbuilt/tasks.md#task-8
+     * @spec openspec/changes/retrofit-2026-05-24-annotate-openbuilt/tasks.md#task-12
+     * @spec openspec/changes/retrofit-2026-05-24-annotate-openbuilt/tasks.md#task-15
      */
     #[NoAdminRequired]
     public function wizard(): JSONResponse

lib/Controller/ApplicationInsightsController.php

@@ -28,6 +28,10 @@
  * @version GIT: <git-id>
  *
  * @link https://conduction.nl
+ *
+ * @spec openspec/changes/retrofit-2026-05-24-annotate-openbuilt/tasks.md#task-16
+ * @spec openspec/changes/retrofit-2026-05-24-annotate-openbuilt/tasks.md#task-17
+ * @spec openspec/changes/retrofit-2026-05-24-annotate-openbuilt/tasks.md#task-21
  */
 
 declare(strict_types=1);
@@ -81,6 +85,10 @@ public function __construct(
      * @param string $versionUuid ApplicationVersion UUID (path param).
      *
      * @return JSONResponse
+     *
+     * @spec openspec/changes/retrofit-2026-05-24-annotate-openbuilt/tasks.md#task-16
+     * @spec openspec/changes/retrofit-2026-05-24-annotate-openbuilt/tasks.md#task-17
+     * @spec openspec/changes/retrofit-2026-05-24-annotate-openbuilt/tasks.md#task-21
      */
     #[NoAdminRequired]
     public function getInsights(string $appUuid, string $versionUuid): JSONResponse

lib/Controller/ApplicationVersionsController.php

@@ -33,6 +33,10 @@
  * @version GIT: <git-id>
  *
  * @link https://conduction.nl
+ *
+ * @spec openspec/changes/retrofit-2026-05-24-annotate-openbuilt/tasks.md#task-24
+ * @spec openspec/changes/retrofit-2026-05-24-annotate-openbuilt/tasks.md#task-25
+ * @spec openspec/changes/retrofit-2026-05-24-annotate-openbuilt/tasks.md#task-47
  */
 
 declare(strict_types=1);
@@ -112,6 +116,8 @@ public function __construct(
      * @param string $slug Parent Application slug
      *
      * @return JSONResponse Versions array on 200, error envelope on miss
+     *
+     * @spec openspec/changes/retrofit-2026-05-24-annotate-openbuilt/tasks.md#task-24
      */
     #[NoAdminRequired]
     public function index(string $slug): JSONResponse
@@ -184,6 +190,8 @@ public function index(string $slug): JSONResponse
      * @param string $versionSlug ApplicationVersion slug
      *
      * @return JSONResponse The version on 200, error envelope on miss
+     *
+     * @spec openspec/changes/retrofit-2026-05-24-annotate-openbuilt/tasks.md#task-24
      */
     #[NoAdminRequired]
     public function show(string $slug, string $versionSlug): JSONResponse
@@ -207,6 +215,8 @@ public function show(string $slug, string $versionSlug): JSONResponse
      * @param string $slug Parent Application slug
      *
      * @return JSONResponse 201 with the created version, or error envelope
+     *
+     * @spec openspec/changes/retrofit-2026-05-24-annotate-openbuilt/tasks.md#task-24
      */
     #[NoAdminRequired]
     public function create(string $slug): JSONResponse
@@ -272,6 +282,8 @@ public function create(string $slug): JSONResponse
      * @param string $versionSlug ApplicationVersion slug
      *
      * @return JSONResponse 200 with the updated version, or error envelope
+     *
+     * @spec openspec/changes/retrofit-2026-05-24-annotate-openbuilt/tasks.md#task-24
      */
     #[NoAdminRequired]
     public function update(string $slug, string $versionSlug): JSONResponse
@@ -347,6 +359,8 @@ public function update(string $slug, string $versionSlug): JSONResponse
      * @param string $versionSlug ApplicationVersion slug
      *
      * @return JSONResponse 204 on success, error envelope otherwise
+     *
+     * @spec openspec/changes/retrofit-2026-05-24-annotate-openbuilt/tasks.md#task-25
      */
     #[NoAdminRequired]
     public function destroy(string $slug, string $versionSlug): JSONResponse
@@ -439,6 +453,8 @@ private function loadApplication(string $slug): ?array
      * @param string $versionSlug ApplicationVersion slug
      *
      * @return array<string,mixed>|null Version record or null on miss
+     *
+     * @spec openspec/changes/retrofit-2026-05-24-annotate-openbuilt/tasks.md#task-24
      */
     private function findVersionForApplication(string $slug, string $versionSlug): ?array
     {
@@ -486,6 +502,8 @@ private function findVersionForApplication(string $slug, string $versionSlug): ?
      * @param array<int,string> $roles List of role names (`owners`, `editors`, `viewers`)
      *
      * @return JSONResponse|null Null on allow, 401/403/404 envelope on deny
+     *
+     * @spec openspec/changes/retrofit-2026-05-24-annotate-openbuilt/tasks.md#task-47
      */
     private function requireRole(string $slug, array $roles): ?JSONResponse
     {

lib/Controller/ApplicationsController.php

@@ -29,6 +29,19 @@
  * @version GIT: <git-id>
  *
  * @link https://conduction.nl
+ *
+ * @spec openspec/changes/retrofit-2026-05-24-annotate-openbuilt/tasks.md#task-45
+ * @spec openspec/changes/retrofit-2026-05-24-annotate-openbuilt/tasks.md#task-46
+ * @spec openspec/changes/retrofit-2026-05-24-annotate-openbuilt/tasks.md#task-47
+ * @spec openspec/changes/retrofit-2026-05-24-annotate-openbuilt/tasks.md#task-48
+ * @spec openspec/changes/retrofit-2026-05-24-annotate-openbuilt/tasks.md#task-49
+ * @spec openspec/changes/retrofit-2026-05-24-annotate-openbuilt/tasks.md#task-50
+ * @spec openspec/changes/retrofit-2026-05-24-annotate-openbuilt/tasks.md#task-51
+ * @spec openspec/changes/retrofit-2026-05-24-annotate-openbuilt/tasks.md#task-55
+ * @spec openspec/changes/retrofit-2026-05-24-annotate-openbuilt/tasks.md#task-56
+ * @spec openspec/changes/retrofit-2026-05-24-annotate-openbuilt/tasks.md#task-58
+ * @spec openspec/changes/retrofit-2026-05-24-annotate-openbuilt/tasks.md#task-69
+ * @spec openspec/changes/retrofit-2026-05-24-annotate-openbuilt/tasks.md#task-70
  */
 
 declare(strict_types=1);
@@ -136,6 +149,9 @@ public function __construct(
      * @param string $slug The virtual-app slug from the URL
      *
      * @return JSONResponse The manifest blob, or a 404 envelope when not found
+     *
+     * @spec openspec/changes/retrofit-2026-05-24-annotate-openbuilt/tasks.md#task-50
+     * @spec openspec/changes/retrofit-2026-05-24-annotate-openbuilt/tasks.md#task-51
      */
     #[NoAdminRequired]
     #[NoCSRFRequired]
@@ -229,6 +245,9 @@ public function getManifest(string $slug): JSONResponse
      * @param string $versionSlug The version slug from `?_version=`.
      *
      * @return JSONResponse 200 with manifest, or 404 when not found / not authorised.
+     *
+     * @spec openspec/changes/retrofit-2026-05-24-annotate-openbuilt/tasks.md#task-69
+     * @spec openspec/changes/retrofit-2026-05-24-annotate-openbuilt/tasks.md#task-70
      */
     private function resolveVersionedManifestResponse(string $slug, string $versionSlug): JSONResponse
     {
@@ -271,6 +290,8 @@ private function resolveVersionedManifestResponse(string $slug, string $versionS
      * standard multitenancy (RegisterMapper::find + ObjectService::searchObjects),
      * and the resolveVersionBlob() check on `applicationUuid` rejects snapshots
      * that do not belong to this Application. Mirrors getManifest()'s pattern.
+     *
+     * @spec openspec/changes/retrofit-2026-05-24-annotate-openbuilt/tasks.md#task-58
      */
     #[NoAdminRequired]
     #[NoCSRFRequired]
@@ -368,6 +389,8 @@ public function diffVersions(string $slug, string $from, string $to): JSONRespon
      * @param string               $applicationUuid Parent Application UUID for scoping.
      *
      * @return array<string, mixed>|null Blob or null if the version is missing.
+     *
+     * @spec openspec/changes/retrofit-2026-05-24-annotate-openbuilt/tasks.md#task-58
      */
     private function resolveVersionBlob(string $token, array $application, string $applicationUuid): ?array
     {
@@ -414,6 +437,8 @@ private function resolveVersionBlob(string $token, array $application, string $a
      * @param string $slug The virtual-app slug from the URL
      *
      * @return JSONResponse|array{0: ObjectEntity|array<string, mixed>, 1: array<string, mixed>, 2: string}
+     *
+     * @spec openspec/changes/retrofit-2026-05-24-annotate-openbuilt/tasks.md#task-50
      */
     private function resolveApplicationBySlug(string $slug): JSONResponse|array
     {
@@ -493,6 +518,10 @@ private function resolveApplicationBySlug(string $slug): JSONResponse|array
      * `permissions` — no OR envelope, no pagination metadata.
      *
      * @return JSONResponse The filtered Application list
+     *
+     * @spec openspec/changes/retrofit-2026-05-24-annotate-openbuilt/tasks.md#task-46
+     * @spec openspec/changes/retrofit-2026-05-24-annotate-openbuilt/tasks.md#task-47
+     * @spec openspec/changes/retrofit-2026-05-24-annotate-openbuilt/tasks.md#task-48
      */
     #[NoAdminRequired]
     #[NoCSRFRequired]
@@ -573,6 +602,8 @@ public function listMine(): JSONResponse
      * @param bool          $isAdmin    Whether the caller is in the Nextcloud admin group.
      *
      * @return array{0: array<array<string,mixed>>, 1: bool} [filtered list, adminBypassUsed].
+     *
+     * @spec openspec/changes/retrofit-2026-05-24-annotate-openbuilt/tasks.md#task-48
      */
     private function filterApplicationsByRole(
         array $results,
@@ -627,6 +658,9 @@ private function filterApplicationsByRole(
      * @param string               $slug             The slug used in the audit envelope
      *
      * @return JSONResponse|null Null on allow, 403 JSONResponse on deny
+     *
+     * @spec openspec/changes/retrofit-2026-05-24-annotate-openbuilt/tasks.md#task-45
+     * @spec openspec/changes/retrofit-2026-05-24-annotate-openbuilt/tasks.md#task-47
      */
     private function requirePermission(
         ?ObjectEntity $application,
@@ -686,6 +720,8 @@ private function requirePermission(
      * @param string            $actor       The bypassing user's UID
      *
      * @return void
+     *
+     * @spec openspec/changes/retrofit-2026-05-24-annotate-openbuilt/tasks.md#task-49
      */
     private function recordAdminBypass(?ObjectEntity $application, string $slug, string $actor): void
     {
@@ -774,6 +810,8 @@ private function getUserGroupIds(IUser $user): array
      *   Two deduplicated lists; `users` are UID values the caller's UID
      *   should be compared against; `groups` are GID values the caller's
      *   group memberships should be intersected with.
+     *
+     * @spec openspec/changes/retrofit-2026-05-24-annotate-openbuilt/tasks.md#task-47
      */
     private function collectAuthorisedGroups(array $application): array
     {
@@ -854,6 +892,9 @@ private function classifyPrincipal(mixed $principal, array &$userSet, array &$gr
      * @param string $templateSlug The source template slug
      *
      * @return JSONResponse The new application's uuid + slug, or an error envelope
+     *
+     * @spec openspec/changes/retrofit-2026-05-24-annotate-openbuilt/tasks.md#task-55
+     * @spec openspec/changes/retrofit-2026-05-24-annotate-openbuilt/tasks.md#task-56
      */
     #[NoAdminRequired]
     public function createFromTemplate(string $templateSlug): JSONResponse
@@ -1000,6 +1041,8 @@ private function resolveSharedContext(): ?array
      * @param array<string,string> $rewriteMap Source-slug → prefixed-slug map
      *
      * @return array<string,mixed>
+     *
+     * @spec openspec/changes/retrofit-2026-05-24-annotate-openbuilt/tasks.md#task-56
      */
     private function buildClonedManifest(array $template, array $rewriteMap): array
     {
@@ -1026,6 +1069,8 @@ private function buildClonedManifest(array $template, array $rewriteMap): array
      * @param array<string,string>           $rewriteMap Source-slug → prefixed-slug map
      *
      * @return array{register:\OCA\OpenRegister\Db\Register,schemaIds:array<int,int>}|array{error:array<string,mixed>,status:int}
+     *
+     * @spec openspec/changes/retrofit-2026-05-24-annotate-openbuilt/tasks.md#task-56
      */
     private function provisionPerAppArtifacts(
         string $newSlug,
@@ -1066,6 +1111,8 @@ private function provisionPerAppArtifacts(
      * @param array{register:int,templateSchema:int,applicationSchema:int} $ctx          Shared context
      *
      * @return array{uuid:string|null}|array{error:array<string,mixed>,status:int}
+     *
+     * @spec openspec/changes/retrofit-2026-05-24-annotate-openbuilt/tasks.md#task-55
      */
     private function persistApplication(
         string $name,
@@ -1141,6 +1188,8 @@ private function validateCloneRequest(array $body): array
      * @param array<string,mixed> $template The template record
      *
      * @return array<int,array<string,mixed>>
+     *
+     * @spec openspec/changes/retrofit-2026-05-24-annotate-openbuilt/tasks.md#task-56
      */
     private function extractCompanionSchemas(array $template): array
     {
@@ -1164,6 +1213,8 @@ private function extractCompanionSchemas(array $template): array
      * @param string                         $newSlug    The new app slug used as prefix
      *
      * @return array<string,string>
+     *
+     * @spec openspec/changes/retrofit-2026-05-24-annotate-openbuilt/tasks.md#task-56
      */
     private function buildRewriteMap(array $companions, string $newSlug): array
     {
@@ -1186,6 +1237,8 @@ private function buildRewriteMap(array $companions, string $newSlug): array
      * @param string $ownerUid The Nextcloud UID of the owner
      *
      * @return \OCA\OpenRegister\Db\Register
+     *
+     * @spec openspec/changes/retrofit-2026-05-24-annotate-openbuilt/tasks.md#task-56
      */
     private function provisionPerAppRegister(string $newSlug, string $ownerUid): \OCA\OpenRegister\Db\Register
     {
@@ -1299,6 +1352,8 @@ private function extractRegisterOwner(mixed $register): string
      * @param \OCA\OpenRegister\Db\Register  $perAppRegister The target per-app register
      *
      * @return array<int,int> List of created schema IDs
+     *
+     * @spec openspec/changes/retrofit-2026-05-24-annotate-openbuilt/tasks.md#task-56
      */
     private function cloneCompanionSchemas(
         array $companions,
@@ -1340,6 +1395,8 @@ private function cloneCompanionSchemas(
      * @param array<string,string> $map  Map of source-slug => prefixed-slug
      *
      * @return mixed The rewritten node
+     *
+     * @spec openspec/changes/retrofit-2026-05-24-annotate-openbuilt/tasks.md#task-56
      */
     private function rewriteSchemaRefs(mixed $node, array $map): mixed
     {