From 1dbd3dbf637ea9bfcd4b003c71050a03fd210b1a Mon Sep 17 00:00:00 2001
From: Ruben van der Linde <rubenvdlinde@gmail.com>
Date: Sat, 5 Sep 2026 14:35:06 +0200
Subject: [PATCH] feat(time): the billing time entry is a satellite, not a
 third timeEntry
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Three apps declared a `timeEntry`. A schema slug is global per organisation and
`SchemaMapper::find()` matches `LOWER(slug)`, so whichever row was reached first
answered for all three: humaniq's HR booking, planninq's project booking, and
this app's billing/WIP record.

humaniq is the agreed owner of the hours, and this app's record is not a second
copy of them. It is client, lead, billing category, approval state, WIP sync
status and invoice batch — the BILLING side of a booking. So it is named for
what it is: `billingTimeEntry`, carrying a `timeEntry` property that names the
humaniq booking it bills.

That reference is a plain uuid and not a `$ref`. humaniq's register is a
different register, and ADR-062 rule 7 gives a cross-register target no `$ref`.

The app-config key `timeEntry_schema` deliberately does NOT move — it is live
persisted state, and the same split already applies to
`klantLoyaltyAccount_schema` two lines below it in the same map.

`RenameTimeEntrySchemaSlug` renames the row before the import, modelled on
`RenameLoyaltyAccountSchemaSlug`, which exists for exactly this. Without it the
descriptor change renames nothing: OpenRegister matches by (application, slug)
and its not-found branch CREATES a second schema, orphaning every existing
billing line silently while the app reads an empty collection.

The seedData references move with the schema, in both fragments and the mock
register. A rename that reaches the schema and not its seed data imports rows
against a slug nothing declares — seven references, and missing one is invisible
until an import runs.

WHAT THIS DOES NOT DO YET, and it is deliberate. `hours`, `date`, `user` and
`description` stay here rather than moving onto the humaniq booking, because
`BillingCategoryWidget` sums `hours` per `billingCategory` and moving them would
make that widget read across two apps. The fleet already has the pattern — a
`requiredApp` widget, which gate-55 supports and which HIDES rather than
rendering empty when the backing app is absent, and which this app already uses
to read planninq's `project`. Applying it here is the next change, and it is
what makes the hours live once.

The collision is cleared either way, which is what this change is for.

2,855 tests green (4 new). phpcs, phpmd, psalm and phpstan clean, and all 75
applicable hydra gates pass.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 appinfo/info.xml                              |   9 +
 lib/Repair/RenameTimeEntrySchemaSlug.php      | 209 ++++++++++++++++++
 lib/Service/SchemaMapService.php              |   7 +-
 lib/Service/SettingsLoadService.php           |   2 +-
 lib/Service/WipSyncNotifier.php               |   2 +-
 lib/Settings/pipelinq_mock_register.json      |   6 +-
 lib/Settings/register.d/90-time-wip.json      |  16 +-
 .../register.d/91-time-billing-handoff.json   |  19 +-
 .../proposal.md                               |  46 ++++
 .../specs/time-entry-core/spec.md             |  61 +++++
 .../tasks.md                                  |  38 ++++
 .../Repair/RenameTimeEntrySchemaSlugTest.php  | 150 +++++++++++++
 12 files changed, 546 insertions(+), 19 deletions(-)
 create mode 100644 lib/Repair/RenameTimeEntrySchemaSlug.php
 create mode 100644 openspec/changes/the-billing-time-entry-is-a-satellite/proposal.md
 create mode 100644 openspec/changes/the-billing-time-entry-is-a-satellite/specs/time-entry-core/spec.md
 create mode 100644 openspec/changes/the-billing-time-entry-is-a-satellite/tasks.md
 create mode 100644 tests/Unit/Repair/RenameTimeEntrySchemaSlugTest.php

diff --git a/appinfo/info.xml b/appinfo/info.xml
index eb1eeba6e..40e50c341 100644
--- a/appinfo/info.xml
+++ b/appinfo/info.xml
@@ -151,6 +151,15 @@ Vrij en open source onder de EUPL-1.2-licentie.
                 updates the schema in place and keeps its id, and its shard table.
             -->
             <step>OCA\Pipelinq\Repair\RenameLoyaltyAccountSchemaSlug</step>
+            <!--
+                Same reason, one slug over. `timeEntry` is global per organisation
+                and three apps declared one — humaniq's HR booking, planninq's
+                project booking and this app's billing/WIP record — so
+                SchemaMapper::find() answered whichever it reached first. humaniq
+                owns the hours; this record is the BILLING side of one, and keeps
+                a `timeEntry` reference to the booking it bills.
+            -->
+            <step>OCA\Pipelinq\Repair\RenameTimeEntrySchemaSlug</step>
             <step>OCA\Pipelinq\Repair\InitializeSettings</step>
             <!--
                 After InitializeSettings imports the register: the schema edit
diff --git a/lib/Repair/RenameTimeEntrySchemaSlug.php b/lib/Repair/RenameTimeEntrySchemaSlug.php
new file mode 100644
index 000000000..d6a89522f
--- /dev/null
+++ b/lib/Repair/RenameTimeEntrySchemaSlug.php
@@ -0,0 +1,209 @@
+<?php
+
+/**
+ * Pipelinq RenameTimeEntrySchemaSlug repair step.
+ *
+ * Moves the time-entry schema's slug from `timeEntry` to `billingTimeEntry`
+ * IN PLACE, before InitializeSettings imports the register.
+ *
+ * WHY IT MOVES AT ALL. A schema slug is global per organisation, and three apps
+ * declared a `timeEntry`: humaniq's HR booking, planninq's project booking, and
+ * this app's billing/WIP record. `SchemaMapper::find()` matches `LOWER(slug)`,
+ * so whichever row it reached first answered for all three. humaniq is the
+ * agreed owner of the hours; this app's record is the BILLING side of one —
+ * client, lead, billing category, approval, WIP sync, invoice batch — and keeps
+ * a `timeEntry` reference to the humaniq booking it bills.
+ *
+ * OpenRegister's import matches an existing schema by (application, slug):
+ * ImportHandler calls `findByApplicationAndSlug()` and creates a NEW schema when that
+ * misses. A slug rename in the shipped register fragment therefore does not rename
+ * anything — it CREATES a second schema and silently orphans the first, together with
+ * every object already written against it. The old schema keeps its shard table and its
+ * rows; the app resolves the new id and reads an empty collection. Nothing errors.
+ *
+ * That is why this step exists and why it must run FIRST. Renaming the row before the
+ * import means the import finds the schema it was always going to find, keeps its id,
+ * and updates it in place — so the shard table, and the objects in it, stay attached.
+ *
+ * The app-config KEY is a separate concern and deliberately does not move; see
+ * {@see \OCA\Pipelinq\Service\SettingsLoadService::SCHEMA_CONFIG_KEYS}.
+ *
+ * Idempotent: a no-op once the slug is already namespaced, and a no-op on an install that
+ * never had the schema. Refuses when both slugs exist, because picking one would decide
+ * which set of objects to abandon — a choice this step must not make silently.
+ *
+ * @category Repair
+ * @package  OCA\Pipelinq\Repair
+ *
+ * @author    Conduction <info@conduction.nl>
+ * @copyright 2026 Conduction B.V.
+ * @license   EUPL-1.2 https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12
+ *
+ * SPDX-FileCopyrightText: 2026 Conduction B.V. <info@conduction.nl>
+ * SPDX-License-Identifier: EUPL-1.2
+ *
+ * @version GIT: <git_id>
+ *
+ * @link https://pipelinq.nl
+ */
+
+declare(strict_types=1);
+
+namespace OCA\Pipelinq\Repair;
+
+use OCP\DB\Exception;
+use OCP\IDBConnection;
+use OCP\Migration\IOutput;
+use OCP\Migration\IRepairStep;
+use Psr\Log\LoggerInterface;
+
+/**
+ * Renames the time-entry schema slug in place, ahead of the register import.
+ *
+ * @spec exclude No canonical spec covers the fleet-wide slug collision
+ *  migration. Pointing this at an existing spec would report conformance to a
+ *  requirement that says nothing about it.
+ */
+class RenameTimeEntrySchemaSlug implements IRepairStep {
+	/**
+	 * The slug this step migrates away from.
+	 *
+	 * @var string
+	 */
+	private const OLD_SLUG = 'timeEntry';
+
+	/**
+	 * The namespaced slug the register fragment now declares.
+	 *
+	 * @var string
+	 */
+	private const NEW_SLUG = 'billingTimeEntry';
+
+	/**
+	 * The owning application, as stored on the schema row.
+	 *
+	 * @var string
+	 */
+	private const APPLICATION = 'pipelinq';
+
+	/**
+	 * Constructor.
+	 *
+	 * @param IDBConnection $db Database connection.
+	 * @param LoggerInterface $logger Logger.
+	 */
+	public function __construct(
+		private readonly IDBConnection $db,
+		private readonly LoggerInterface $logger,
+	) {
+	}//end __construct()
+
+	/**
+	 * Human-readable step name.
+	 *
+	 * @return string
+	 *
+	 * @spec exclude No canonical spec covers the fleet-wide slug collision
+	 *  migration. Pointing this at an existing spec would report conformance to a
+	 *  requirement that says nothing about it.
+	 */
+	public function getName(): string {
+		return 'Namespace the pipelinq time-entry schema slug';
+	}//end getName()
+
+	/**
+	 * Rename the slug, unless doing so would be ambiguous.
+	 *
+	 * @param IOutput $output Repair output.
+	 *
+	 * @return void
+	 *
+	 * @spec exclude No canonical spec covers the fleet-wide slug collision
+	 *  migration. Pointing this at an existing spec would report conformance to a
+	 *  requirement that says nothing about it.
+	 */
+	public function run(IOutput $output): void {
+		$old = $this->schemaIds(slug: self::OLD_SLUG);
+		$new = $this->schemaIds(slug: self::NEW_SLUG);
+
+		if ($old === null || $new === null) {
+			$output->info('RenameTimeEntrySchemaSlug: schema table unreadable; leaving the slug alone.');
+			return;
+		}
+
+		if ($old === []) {
+			$output->info('RenameTimeEntrySchemaSlug: no time-entry schema on this install; nothing to do.');
+			return;
+		}
+
+		if ($new !== []) {
+			// Both slugs present: each may own objects, and renaming would collide
+			// with the English row. Abandoning either set of objects is not a call
+			// a repair step gets to make without being asked.
+			$this->logger->warning(
+				'RenameTimeEntrySchemaSlug: both slugs exist; refusing to merge them.',
+				['old' => $old, 'new' => $new]
+			);
+			$output->warning(
+				'RenameTimeEntrySchemaSlug: both `' . self::OLD_SLUG . '` and `' . self::NEW_SLUG
+				. '` exist; refusing to merge them. Resolve by hand.'
+			);
+			return;
+		}
+
+		if (count($old) > 1) {
+			$this->logger->warning(
+				'RenameTimeEntrySchemaSlug: duplicate time-entry slugs; refusing to guess.',
+				['ids' => $old]
+			);
+			$output->warning('RenameTimeEntrySchemaSlug: duplicate `' . self::OLD_SLUG . '` schemas; refusing to guess.');
+			return;
+		}
+
+		try {
+			$this->db->executeStatement(
+				'UPDATE `*PREFIX*openregister_schemas` SET slug = ? WHERE id = ?',
+				[self::NEW_SLUG, $old[0]]
+			);
+		} catch (Exception $e) {
+			// A failure here is safe: the import then creates a new schema rather
+			// than updating this one, which is the pre-existing behaviour. Loud,
+			// because the objects on the old schema stop being reachable.
+			$this->logger->error(
+				'RenameTimeEntrySchemaSlug: slug rename failed; the import will create a second schema.',
+				['id' => $old[0], 'exception' => $e->getMessage()]
+			);
+			$output->warning('RenameTimeEntrySchemaSlug: slug rename failed; see the log.');
+			return;
+		}
+
+		$output->info(
+			'RenameTimeEntrySchemaSlug: schema ' . $old[0] . ' renamed `'
+			. self::OLD_SLUG . '` -> `' . self::NEW_SLUG . '`; its objects stay attached.'
+		);
+	}//end run()
+
+	/**
+	 * Ids of this application's schemas carrying the given slug.
+	 *
+	 * @param string $slug The schema slug to look for.
+	 *
+	 * @return array<int, mixed>|null The ids, or null when the table cannot be read.
+	 */
+	private function schemaIds(string $slug): ?array {
+		try {
+			$rows = $this->db->executeQuery(
+				'SELECT id FROM `*PREFIX*openregister_schemas` WHERE slug = ? AND application = ?',
+				[$slug, self::APPLICATION]
+			)->fetchAll(\PDO::FETCH_COLUMN);
+
+			return array_values((array)$rows);
+		} catch (Exception $e) {
+			$this->logger->warning(
+				'RenameTimeEntrySchemaSlug: could not read the schema table; skipping.',
+				['exception' => $e->getMessage()]
+			);
+			return null;
+		}
+	}//end schemaIds()
+}//end class
diff --git a/lib/Service/SchemaMapService.php b/lib/Service/SchemaMapService.php
index 30feb3343..d32466974 100644
--- a/lib/Service/SchemaMapService.php
+++ b/lib/Service/SchemaMapService.php
@@ -48,7 +48,12 @@ class SchemaMapService {
 		'pipeline_schema' => 'pipeline',
 		'skill_schema' => 'skill',
 		'agentProfile_schema' => 'agentProfile',
-		'timeEntry_schema' => 'timeEntry',
+		// The entity type follows the renamed slug; the app-config KEY deliberately
+		// does not, matching `klantLoyaltyAccount_schema` below. `timeEntry` was
+		// global per organisation and three apps declared one — humaniq's HR
+		// booking, planninq's project booking and this app's billing/WIP record —
+		// so `SchemaMapper::find()` answered whichever it reached first.
+		'timeEntry_schema' => 'billingTimeEntry',
 		'task_schema' => 'task',
 		'posTransaction_schema' => 'posTransaction',
 		// POS staff PIN + role permissions (pos-staff-pin-permissions).
diff --git a/lib/Service/SettingsLoadService.php b/lib/Service/SettingsLoadService.php
index 21d0e686f..9b4680915 100644
--- a/lib/Service/SettingsLoadService.php
+++ b/lib/Service/SettingsLoadService.php
@@ -58,7 +58,7 @@ class SettingsLoadService {
 		'skill',
 		'agentProfile',
 		// Time & WIP tracking (time-wip).
-		'timeEntry',
+		'billingTimeEntry',
 		'posTransaction',
 		'posTransactionLine',
 		// POS split-tender schemas (pos-split-tender). Without these two slugs
diff --git a/lib/Service/WipSyncNotifier.php b/lib/Service/WipSyncNotifier.php
index 6460c0a21..6d62774d1 100644
--- a/lib/Service/WipSyncNotifier.php
+++ b/lib/Service/WipSyncNotifier.php
@@ -72,7 +72,7 @@ public function notifyFailure(string $title, string $uuid): void {
 				parameters: [
 					'title' => $title,
 				],
-				objectType: 'timeEntry',
+				objectType: 'billingTimeEntry',
 				objectId: $uuid
 			);
 		}
diff --git a/lib/Settings/pipelinq_mock_register.json b/lib/Settings/pipelinq_mock_register.json
index 4698110d7..a53b57f6f 100644
--- a/lib/Settings/pipelinq_mock_register.json
+++ b/lib/Settings/pipelinq_mock_register.json
@@ -6408,7 +6408,7 @@
       {
         "@self": {
           "register": "pipelinq",
-          "schema": "timeEntry",
+          "schema": "billingTimeEntry",
           "slug": "timeentry-voorbeeld-title-1-1"
         },
         "title": "Voorbeeld Title 1",
@@ -6432,7 +6432,7 @@
       {
         "@self": {
           "register": "pipelinq",
-          "schema": "timeEntry",
+          "schema": "billingTimeEntry",
           "slug": "timeentry-voorbeeld-title-2-2"
         },
         "title": "Voorbeeld Title 2",
@@ -6456,7 +6456,7 @@
       {
         "@self": {
           "register": "pipelinq",
-          "schema": "timeEntry",
+          "schema": "billingTimeEntry",
           "slug": "timeentry-voorbeeld-title-3-3"
         },
         "title": "Voorbeeld Title 3",
diff --git a/lib/Settings/register.d/90-time-wip.json b/lib/Settings/register.d/90-time-wip.json
index 979ab5014..124c46e27 100644
--- a/lib/Settings/register.d/90-time-wip.json
+++ b/lib/Settings/register.d/90-time-wip.json
@@ -3,13 +3,13 @@
     "registers": {
       "pipelinq": {
         "schemas": [
-          "timeEntry"
+          "billingTimeEntry"
         ]
       }
     },
     "schemas": {
-      "timeEntry": {
-        "slug": "timeEntry",
+      "billingTimeEntry": {
+        "slug": "billingTimeEntry",
         "title": "Time Entry",
         "icon": "ClockOutline",
         "version": "1.2.0",
@@ -123,7 +123,7 @@
       {
         "@self": {
           "register": "pipelinq",
-          "schema": "timeEntry",
+          "schema": "billingTimeEntry",
           "slug": "time-entry-wip-synced-1"
         },
         "title": "Adviesgesprek intake De Vries BV",
@@ -140,7 +140,7 @@
       {
         "@self": {
           "register": "pipelinq",
-          "schema": "timeEntry",
+          "schema": "billingTimeEntry",
           "slug": "time-entry-wip-synced-2"
         },
         "title": "Technische implementatie OpenRegister module",
@@ -157,7 +157,7 @@
       {
         "@self": {
           "register": "pipelinq",
-          "schema": "timeEntry",
+          "schema": "billingTimeEntry",
           "slug": "time-entry-wip-synced-3"
         },
         "title": "Onderzoek algoritmisch routeren vergunningaanvragen",
@@ -174,7 +174,7 @@
       {
         "@self": {
           "register": "pipelinq",
-          "schema": "timeEntry",
+          "schema": "billingTimeEntry",
           "slug": "time-entry-wip-pending-1"
         },
         "title": "Projectopstartgesprek subsidieportaal GroenNet",
@@ -191,7 +191,7 @@
       {
         "@self": {
           "register": "pipelinq",
-          "schema": "timeEntry",
+          "schema": "billingTimeEntry",
           "slug": "time-entry-wip-failed-1"
         },
         "title": "ZZP-advies supply chain optimalisatie",
diff --git a/lib/Settings/register.d/91-time-billing-handoff.json b/lib/Settings/register.d/91-time-billing-handoff.json
index 00061da33..db64db6e4 100644
--- a/lib/Settings/register.d/91-time-billing-handoff.json
+++ b/lib/Settings/register.d/91-time-billing-handoff.json
@@ -1,8 +1,17 @@
 {
   "components": {
     "schemas": {
-      "timeEntry": {
+      "billingTimeEntry": {
         "properties": {
+          "timeEntry": {
+            "type": "string",
+            "format": "uuid",
+            "title": "Urenboeking",
+            "title:en": "Time entry",
+            "description": "De humaniq `TimeEntry` die deze regel factureert. Een platte uuid en geen `$ref`: humaniq's register is een ander register, en ADR-062 regel 7 geeft een doel buiten dit register geen `$ref`.",
+            "description:en": "The humaniq `TimeEntry` this line bills. A plain uuid and not a `$ref`: humaniq's register is a different register, and ADR-062 rule 7 gives a cross-register target no `$ref`.",
+            "facetable": true
+          },
           "billingSyncStatus": {
             "type": "string",
             "enum": [
@@ -83,7 +92,7 @@
       {
         "@self": {
           "register": "pipelinq",
-          "schema": "timeEntry",
+          "schema": "billingTimeEntry",
           "slug": "time-entry-billing-demo-muni-1",
           "id": "84354c2c-5009-4a67-baac-1ccd11a8ec95"
         },
@@ -100,7 +109,7 @@
       {
         "@self": {
           "register": "pipelinq",
-          "schema": "timeEntry",
+          "schema": "billingTimeEntry",
           "slug": "time-entry-billing-demo-muni-2",
           "id": "8cefcadf-f17e-47cf-a898-48c287200615"
         },
@@ -117,7 +126,7 @@
       {
         "@self": {
           "register": "pipelinq",
-          "schema": "timeEntry",
+          "schema": "billingTimeEntry",
           "slug": "time-entry-billing-demo-consult-1",
           "id": "5ebe90c9-3dea-4832-ba47-a9c6992f51ea"
         },
@@ -137,7 +146,7 @@
       {
         "@self": {
           "register": "pipelinq",
-          "schema": "timeEntry",
+          "schema": "billingTimeEntry",
           "slug": "time-entry-billing-demo-travel-1",
           "id": "8b34a794-7ca1-411a-909a-f902d5360ae6"
         },
diff --git a/openspec/changes/the-billing-time-entry-is-a-satellite/proposal.md b/openspec/changes/the-billing-time-entry-is-a-satellite/proposal.md
new file mode 100644
index 000000000..8dc7a8a75
--- /dev/null
+++ b/openspec/changes/the-billing-time-entry-is-a-satellite/proposal.md
@@ -0,0 +1,46 @@
+# The billing time entry is a satellite
+
+## Why
+
+Three apps declared a `timeEntry`. A schema slug is global per organisation and
+`SchemaMapper::find()` matches `LOWER(slug)`, so whichever row was reached first
+answered for all three.
+
+| | shape | required |
+| --- | --- | --- |
+| humaniq `TimeEntry` | a clocked interval, or since humaniq#323 a day booking | `date` or clock times |
+| planninq `timeEntry` | a duration booked to a project task | `task`, `user`, `duration`, `date` |
+| this app's `timeEntry` | the BILLING record of time worked | `title`, `hours`, `date` |
+
+humaniq is the agreed owner of the hours. This app's record is not a second copy
+of them: it is client, lead, billing category, approval state, WIP sync status
+and invoice batch — the billing side of a booking.
+
+## What changes
+
+`timeEntry` becomes `billingTimeEntry`, and gains a `timeEntry` property naming
+the humaniq booking it bills. A plain uuid, not a `$ref`: humaniq's register is
+a different register and ADR-062 rule 7 gives a cross-register target no `$ref`.
+
+The app-config key `timeEntry_schema` does not move. It is live persisted state,
+and the same split already applies to `klantLoyaltyAccount_schema` two lines
+below it in the same map.
+
+`RenameTimeEntrySchemaSlug` renames the row before the import, modelled on
+`RenameLoyaltyAccountSchemaSlug` which exists for exactly this. Without it the
+descriptor change renames nothing: OpenRegister's import creates a second schema
+and orphans every existing billing line, silently.
+
+## What this does NOT do yet
+
+**The hours still live in both places.** This app's `hours`, `date`, `user` and
+`description` stay on `billingTimeEntry` rather than moving to the humaniq
+booking, because `BillingCategoryWidget` sums `hours` per `billingCategory` and
+moving them would make that widget read across two apps.
+
+The fleet already has the pattern for that — a `requiredApp` widget, which
+gate-55 supports and which HIDES rather than rendering empty when the backing
+app is absent; pipelinq itself reads planninq's `project` that way. Applying it
+here is the next change, and it is what makes the hours live once.
+
+The collision is cleared either way, which is what this change is for.
diff --git a/openspec/changes/the-billing-time-entry-is-a-satellite/specs/time-entry-core/spec.md b/openspec/changes/the-billing-time-entry-is-a-satellite/specs/time-entry-core/spec.md
new file mode 100644
index 000000000..2022aafe4
--- /dev/null
+++ b/openspec/changes/the-billing-time-entry-is-a-satellite/specs/time-entry-core/spec.md
@@ -0,0 +1,61 @@
+# Time entry core
+
+## ADDED Requirements
+
+### Requirement: The billing time entry is named for what it is (REQ-TEC-030)
+
+The schema SHALL be `billingTimeEntry`, not `timeEntry`.
+
+A schema slug is global per organisation and `SchemaMapper::find()` matches
+`LOWER(slug)`, so three apps declaring a `timeEntry` meant whichever row was
+reached first answered for all three: humaniq's HR booking, planninq's project
+booking and this app's billing/WIP record.
+
+humaniq owns the hours. This record is the BILLING side of one — client, lead,
+billing category, approval, WIP sync, invoice batch — and SHALL carry a
+`timeEntry` reference to the humaniq booking it bills.
+
+That reference SHALL be a plain uuid string and SHALL NOT be a `$ref`.
+humaniq's register is a different register, and ADR-062 rule 7 gives a
+cross-register target no `$ref`.
+
+The app-config KEY `timeEntry_schema` SHALL NOT move. It is live persisted
+state, and the same split already applies to `klantLoyaltyAccount_schema`.
+
+#### Scenario: The register declares the namespaced slug
+
+- **WHEN** the register fragments are read
+- **THEN** the schema key and its `slug` are both `billingTimeEntry`, and no
+  `timeEntry` schema is declared.
+
+#### Scenario: The billing line names the booking it bills
+
+- **WHEN** the merged `billingTimeEntry` is inspected
+- **THEN** it carries a `timeEntry` property of type string, format uuid, with
+  no `$ref`.
+
+### Requirement: The rename SHALL be migrated on an existing install (REQ-TEC-031)
+
+A repair step SHALL rename the schema row's slug in place, before
+`InitializeSettings` imports the register.
+
+OpenRegister matches an existing schema by `(application, slug)` and CREATES a
+new one when that misses, so renaming the slug in the shipped fragment alone
+renames nothing: it orphans the old schema and every object already written
+against it, silently, and the app reads an empty collection.
+
+It SHALL be idempotent, and SHALL refuse rather than guess when both slugs
+exist or the old slug is duplicated — either choice would decide which set of
+objects to abandon.
+
+#### Scenario: An existing install is renamed in place
+
+- **GIVEN** a schema row with slug `timeEntry` under application `pipelinq`
+- **WHEN** the repair step runs
+- **THEN** that row's slug is `billingTimeEntry` and its objects stay attached.
+
+#### Scenario: Both slugs present is refused
+
+- **GIVEN** rows carrying both slugs
+- **WHEN** the repair step runs
+- **THEN** no row is written and the refusal is logged.
diff --git a/openspec/changes/the-billing-time-entry-is-a-satellite/tasks.md b/openspec/changes/the-billing-time-entry-is-a-satellite/tasks.md
new file mode 100644
index 000000000..32a338101
--- /dev/null
+++ b/openspec/changes/the-billing-time-entry-is-a-satellite/tasks.md
@@ -0,0 +1,38 @@
+# Tasks
+
+## 1. The schema
+
+- [x] 1.1 `timeEntry` -> `billingTimeEntry`, key AND `slug`, in both fragments
+      and in the register's schema list.
+- [x] 1.2 Every seedData `"schema"` reference moves with it, in the fragments
+      and the mock register. A rename that reaches the schema and not its seed
+      data imports rows against a slug nothing declares.
+- [x] 1.3 A `timeEntry` property naming the humaniq booking: plain uuid, no
+      `$ref`, per ADR-062 rule 7.
+- [x] 1.4 The app-config key `timeEntry_schema` deliberately does not move.
+
+## 2. The code sites
+
+- [x] 2.1 `SchemaMapService::SCHEMA_MAPPING`, `SettingsLoadService` and
+      `WipSyncNotifier`'s `objectType`.
+
+## 3. The migration
+
+- [x] 3.1 `RenameTimeEntrySchemaSlug`, modelled on the loyalty-account step,
+      registered BEFORE `InitializeSettings`.
+- [x] 3.2 Idempotent; refuses when both slugs exist or the old one is
+      duplicated.
+
+## 4. Verification
+
+- [x] 4.1 Rename, no-op, both-slugs and duplicate cases.
+- [x] 4.2 2,855 tests green.
+
+## 5. Next
+
+- [ ] 5.1 Move `hours`, `date`, `user` and `description` onto humaniq's
+      `TimeEntry` so they live once, and make `BillingCategoryWidget` a
+      `requiredApp: humaniq` widget that joins the two — the same pattern this
+      app already uses to read planninq's `project`.
+- [ ] 5.2 Migrate existing rows: one humaniq `TimeEntry` per billing line, and
+      the line's `timeEntry` pointed at it.
diff --git a/tests/Unit/Repair/RenameTimeEntrySchemaSlugTest.php b/tests/Unit/Repair/RenameTimeEntrySchemaSlugTest.php
new file mode 100644
index 000000000..7eb7ee17c
--- /dev/null
+++ b/tests/Unit/Repair/RenameTimeEntrySchemaSlugTest.php
@@ -0,0 +1,150 @@
+<?php
+
+/**
+ * Unit tests for RenameTimeEntrySchemaSlug.
+ *
+ * @category Test
+ * @package  OCA\Pipelinq\Tests\Unit\Repair
+ *
+ * @author    Conduction <info@conduction.nl>
+ * @copyright 2026 Conduction B.V.
+ * @license   EUPL-1.2 https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12
+ *
+ * @version GIT: <git_id>
+ *
+ * @link https://pipelinq.nl
+ */
+
+declare(strict_types=1);
+
+namespace OCA\Pipelinq\Tests\Unit\Repair;
+
+use OCA\Pipelinq\Repair\RenameTimeEntrySchemaSlug;
+use OCP\DB\IResult;
+use OCP\IDBConnection;
+use OCP\Migration\IOutput;
+use PHPUnit\Framework\TestCase;
+use Psr\Log\LoggerInterface;
+
+/**
+ * Guards the time-entry schema slug migration.
+ *
+ * The step exists because OpenRegister matches a schema by (application, slug) and
+ * CREATES a new one when that misses — so a slug rename in the shipped register
+ * fragment orphans the old schema and every object on it, without erroring. These
+ * tests pin the one case that must write and the two that must refuse.
+ */
+final class RenameTimeEntrySchemaSlugTest extends TestCase {
+	/**
+	 * Mocked database connection.
+	 *
+	 * @var IDBConnection
+	 */
+	private $db;
+
+	/**
+	 * The step under test.
+	 *
+	 * @var RenameTimeEntrySchemaSlug
+	 */
+	private RenameTimeEntrySchemaSlug $step;
+
+	/**
+	 * Build the step with mocked collaborators.
+	 *
+	 * @return void
+	 */
+	protected function setUp(): void {
+		parent::setUp();
+		$this->db = $this->createMock(IDBConnection::class);
+		$this->step = new RenameTimeEntrySchemaSlug($this->db, $this->createMock(LoggerInterface::class));
+	}//end setUp()
+
+	/**
+	 * Queue the two slug lookups the step performs, in order.
+	 *
+	 * @param array<int, mixed> $old Ids returned for the old slug.
+	 * @param array<int, mixed> $new Ids returned for the namespaced slug.
+	 *
+	 * @return void
+	 */
+	private function queueLookups(array $old, array $new): void {
+		$oldResult = $this->createMock(IResult::class);
+		$oldResult->method('fetchAll')->willReturn($old);
+		$newResult = $this->createMock(IResult::class);
+		$newResult->method('fetchAll')->willReturn($new);
+		$this->db->method('executeQuery')->willReturnOnConsecutiveCalls($oldResult, $newResult);
+	}//end queueLookups()
+
+	/**
+	 * The old slug alone is renamed in place, keeping the schema id.
+	 *
+	 * Keeping the id is the whole point: the shard table is named after it, so a new
+	 * schema would leave every existing billing line behind a slug nothing reads.
+	 *
+	 * @return void
+	 */
+	public function testRenamesTheOldSlugInPlace(): void {
+		$this->queueLookups(old: [495], new: []);
+
+		$statements = [];
+		$this->db->method('executeStatement')->willReturnCallback(
+			function (string $sql, array $params = []) use (&$statements): int {
+				$statements[] = [$sql, $params];
+				return 1;
+			}
+		);
+
+		$this->step->run($this->createMock(IOutput::class));
+
+		$this->assertCount(1, $statements, 'exactly one row may be rewritten');
+		$this->assertStringContainsString('openregister_schemas', $statements[0][0]);
+		$this->assertStringContainsString('SET slug', $statements[0][0]);
+		$this->assertSame(['billingTimeEntry', 495], $statements[0][1]);
+	}//end testRenamesTheOldSlugInPlace()
+
+	/**
+	 * An install already on the namespaced slug is left alone.
+	 *
+	 * @return void
+	 */
+	public function testIsANoOpWhenTheOldSlugIsAbsent(): void {
+		$this->queueLookups(old: [], new: [495]);
+		$this->db->expects($this->never())->method('executeStatement');
+
+		$this->step->run($this->createMock(IOutput::class));
+	}//end testIsANoOpWhenTheOldSlugIsAbsent()
+
+	/**
+	 * Both slugs present is a refusal, not a merge.
+	 *
+	 * Each schema may own objects. Renaming one onto the other would decide which set
+	 * to abandon, so the step declines and says so rather than picking silently.
+	 *
+	 * @return void
+	 */
+	public function testRefusesWhenBothSlugsExist(): void {
+		$this->queueLookups(old: [495], new: [512]);
+		$this->db->expects($this->never())->method('executeStatement');
+
+		$output = $this->createMock(IOutput::class);
+		$output->expects($this->once())->method('warning');
+
+		$this->step->run($output);
+	}//end testRefusesWhenBothSlugsExist()
+
+	/**
+	 * Duplicate old slugs are a refusal too — the step must not guess.
+	 *
+	 * @return void
+	 */
+	public function testRefusesWhenTheOldSlugIsDuplicated(): void {
+		$this->queueLookups(old: [495, 496], new: []);
+		$this->db->expects($this->never())->method('executeStatement');
+
+		$output = $this->createMock(IOutput::class);
+		$output->expects($this->once())->method('warning');
+
+		$this->step->run($output);
+	}//end testRefusesWhenTheOldSlugIsDuplicated()
+}//end class