Skip to content

refactor(architecture): ObjectServiceInterface and its receiving chain take the published values (X00 c) - #10985

Merged
rubenvdlinde merged 6 commits into
mainfrom
cloud/mod-X00-published-signatures
Nov 21, 2026
Merged

rubenvdlinde merged 6 commits into
mainfrom
cloud/mod-X00-published-signatures

Conversation

@rubenvdlinde

@rubenvdlinde rubenvdlinde commented Nov 21, 2026 •

Copy link
Copy Markdown
Contributor

Package X00, PR c of 3: the published interface and its receiving chain name the published values

Wave 5, round 1, task 7.2. Stacked on #10977 (PR b), which is stacked on #10976 (PR a). This branch contains their commits plus two merges of main. Review only this PR's own commits: e1fd7634 and 8364371a. Land #10976 and #10977 first. PR a and b are unchanged: re-checked, nothing in them is wrong (see "PR b's nested defaults" below).

What changed (7 files)

  • lib/Contract/ObjectServiceInterface.php drops its eight use OCA\OpenRegister\Kernel\Contracts\Value\... imports. Every class its signatures name now resolves inside OCA\OpenRegister\Contract (ObjectSaveOptions, BulkSaveOptions, ObjectFindOptions, ObjectDeletion, ObjectPatch, LockRequest, UnlockRequest, ObjectValidationVerdict). For parameters that is a widening, because the old names are subclasses. validateObject()'s published return type is the parent; the implementation keeps returning the old subclass, which satisfies both.
    • The two defaults keep the deprecated names: saveObject(... $options = new \OCA\OpenRegister\Kernel\Contracts\Value\ObjectSaveOptions()), and the same for saveObjects() with BulkSaveOptions. Why: a generated mock (createMock(ObjectServiceInterface::class)) fills an omitted argument with the interface's default. Built under the published name, that default reached fleet callbacks typed with the old name as a Contract\ObjectSaveOptions and threw a TypeError (found by the fleet run: shillinq AccrualBookingTest, 4 failures). With the old-name defaults, every omitted argument and every mock passes exactly the value it passed before. They move to the published names with the fleet in task 7.3. The docblock says so.
  • lib/Service/ObjectService.php: the public signatures of saveObject, find, findSilent, deleteObject, saveObjects, lockObject, unlockObject and patchObject take the published parents (imported as Published<Name>; construction sites and defaults keep the old names). It must, or ObjectService would be narrower than the interface it implements.
  • The receiving chain (package step 4). vendor/bin/phpstan analyse lib was re-run until it reported no Contract\X given / expects Kernel\...\X pair. That took five rounds. Exactly these parameters were widened to the published type, and only these:
    • ObjectService::saveBulkWithinScope(), ObjectService::patchWithinScope();
    • LockHandler::lock(), unlock(), logRequest(), acquire(), acquireAdvisory(), lockLogged(), lockResolved(), lockStoredObject(), logLocked(), unlockLogged(), unlockResolved(), assertMayUnlock(), releaseStoredLock();
    • AdvisoryLockStore::acquire(), payload(), logAcquired().
      find/findSilent/saveObject/deleteObject needed nothing further: their options are only read. No instanceof on the old names exists in lib/. ObjectOperationsInterface (Kernel, internal) keeps the old names; ObjectService satisfies it contravariantly.
  • The deprecated old names are final class X extends \OCA\OpenRegister\Contract\X {} with @deprecated, from refactor(architecture): publish the five values the object values name in lib/Contract (X00 a) #10976 and refactor(architecture): publish the eight values ObjectServiceInterface names in lib/Contract (X00 b) #10977. There is no class_alias (the only class_alias in lib/ is the pre-existing AppInfo/ClassAliasMap).
  • Tests:
    • new tests/Unit/Contract/PublishedSignaturesTest.php. It checks five things. (1) Every openregister class the contract's signatures name lives in OCA\OpenRegister\Contract. (2) The contract and ObjectService take each published value. (3) The old names still fit. (4) The defaults are the old names, and a mock passes the old name to a callback typed with it. (5) The lock chain takes the published values, and a lock built only from published classes is taken and released through the real LockHandler and AdvisoryLockStore; both names take the same lock.
    • ObjectServiceUpdateVersusPatchTest: the signature assertion now expects the published ObjectPatch, on the contract and on the implementation. It adds testAPatchBuiltUnderThePublishedNameMergesTheSame, which sends the patch through the real patchObject() → patchWithinScope() path.
    • ValidationHandlerBySchemaGoldenTest: the closure that mirrors ObjectService::saveObject()'s signature follows it.

Exposed lines per area (measure()['exposed_loc'])

Area main b85c154e this branch diff
Kernel 8,464 8,455 −9
Core 57,319 57,324 +5
Notifications 1,760 1,760 0
Search 1,344 1,344 0
Compliance 14,300 14,300 0
Files 1,263 1,263 0
Integrations 17,733 17,733 0
Processes 27,040 27,040 0
Configuration 874 874 0
Platform 61 61 0
Total 130,158 of 462,131 130,154 of 462,189 −4

(a + b + c against main.) Expected by the package: about +65 Kernel for the 13 stubs. Measured −9 Kernel, because the moved code is named mostly from Kernel itself, plus +5 Core for the Published* imports in ObjectService.

References against the order

38 on main b85c154e, 38 on this branch.

Newly exposed files / new Kernel files

modularity_check.py --check reports only lib/Contract/ files, nothing else:

  • 13 new Kernel files: lib/Contract/{BulkBatchDefaults,BulkSaveOptions,LockRequest,LockRunStep,ObjectDeletion,ObjectFindOptions,ObjectFindTarget,ObjectPatch,ObjectSaveOptions,ObjectValidationVerdict,SaveActor,SavePolicy,UnlockRequest}.php, the published contract decided in task 7.2.
  • 8 newly exposed files: lib/Contract/{BulkSaveOptions,LockRequest,ObjectDeletion,ObjectFindOptions,ObjectFindTarget,ObjectPatch,ObjectSaveOptions,UnlockRequest}.php, named by ObjectService, LockHandler and AdvisoryLockStore (Core) on the widened parameters. They are values on the published contract's signatures.

Gate 67 and the ConductionNL/.github companion PR — NOT OPENED, needs a hand

Gate 67 on main today: FAIL. Checked with .github@main's check_openregister_contract_parity.py against main's lib/Contract: ObjectFileReaderInterface.php is not shipped, and ObjectServiceInterface.php differs.

I prepared the companion change: branch cloud/mod-X00-published-contract-values from .github main b1db70f. With it, gate 67 passes: checked 19 file(s), all byte-identical. test_shipped_contracts_documented.py passes (4 tests) and test_gate67_contract_parity_scope.sh passes ("all cases behaved"). I could not push it. This session cannot attach a repository whose name starts with a dot: git push gets 403, and the API refuses the repository. To open it:

git clone https://github.com/ConductionNL/.github && cd .github && git switch -c cloud/mod-X00-published-contract-values
for f in BulkBatchDefaults BulkSaveOptions LockRequest LockRunStep ObjectDeletion ObjectFileReaderInterface ObjectFindOptions ObjectFindTarget ObjectPatch ObjectSaveOptions ObjectServiceInterface ObjectValidationVerdict SaveActor SavePolicy UnlockRequest; do
  git -C ../openregister show origin/cloud/mod-X00-published-signatures:lib/Contract/$f.php > hydra-gates/contracts/$f.php
done
# then apply the README change below, commit, open the PR against main

ObjectFileReaderInterface.php is included on purpose (it is in lib/Contract/ on main and missing there), byte-identical. The README change (the test requires every shipped file in the table, the bootstrap guard and the Psalm stubs):

hydra-gates/README.md diff
@@ -192,6 +192,20 @@
 | `EmailLinkReaderInterface.php` | interface | reads the Nextcloud Mail messages linked to an object |
+| `ObjectFileReaderInterface.php` | interface | reads the files attached to an object |
+| `ObjectSaveOptions.php` | class | where and how `saveObject()` stores an object |
+| `BulkSaveOptions.php` | class | where and how `saveObjects()` stores a batch |
+| `ObjectFindOptions.php` | class | register, schema, extend, files, render and audit of a read |
+| `ObjectDeletion.php` | class | the object `deleteObject()` removes, and how |
+| `ObjectPatch.php` | class | the partial data `patchObject()` merges |
+| `LockRequest.php` | class | the lock `lockObject()` takes |
+| `UnlockRequest.php` | class | the lock `unlockObject()` releases |
+| `ObjectValidationVerdict.php` | class | the answer of `validateObject()` |
+| `ObjectFindTarget.php` | class | the register and schema scope the values above carry |
+| `SaveActor.php` | class | who a save acts as |
+| `SavePolicy.php` | class | events, validation and insert-only choices of a save |
+| `BulkBatchDefaults.php` | class | the batch defaults of a bulk save |
+| `LockRunStep.php` | class | the flow run step that takes a lock |
@@ -208,6 +222,20 @@ (after "first shipped in v1.19.0, so an openregister lock on v1.18.0 still fails gate 67 locally.")
+
+The thirteen value classes (`ObjectSaveOptions` to `LockRunStep` above) are the
+values `ObjectServiceInterface` names in its signatures, published by
+openregister's task 7.2 so the contract is self-contained. openregister keeps
+their old names, `OCA\OpenRegister\Kernel\Contracts\Value\<Name>`, as
+deprecated subclasses, so values built under the old name are still accepted.
+A test double that `implements ObjectServiceInterface` (or extends
+openregister's `ObjectService`) must type those parameters with the published
+name or wider; one typed with only the old Kernel name is narrower and fatals at
+class load. Typing it `ObjectSaveOptions|PublishedObjectSaveOptions` (old name
+or published name) loads against both the old and the new contract, because PHP
+matches a union member by name without loading the other class.
+`ObjectFileReaderInterface.php` was in openregister's `lib/Contract/` but not
+here, which kept gate 67 red until it shipped.
@@ -226,7 +254,7 @@ (bootstrap guard)
-foreach (['ObjectEntityInterface', 'ObjectServiceInterface', 'RegisterSlugResolution', 'RegisterSlugResolverInterface', 'EmailLinkReaderInterface'] as $contract) {
+foreach (['ObjectEntityInterface', 'ObjectServiceInterface', 'RegisterSlugResolution', 'RegisterSlugResolverInterface', 'EmailLinkReaderInterface', 'ObjectFileReaderInterface', 'ObjectFindTarget', 'SaveActor', 'SavePolicy', 'BulkBatchDefaults', 'LockRunStep', 'ObjectSaveOptions', 'BulkSaveOptions', 'LockRequest', 'UnlockRequest', 'ObjectFindOptions', 'ObjectDeletion', 'ObjectPatch', 'ObjectValidationVerdict'] as $contract) {
@@ -277,6 +305,20 @@ (Psalm stubs, after EmailLinkReaderInterface.php)
+    <file name="vendor/conduction/hydra-gates/hydra-gates/contracts/ObjectFileReaderInterface.php" />
+    <file name="vendor/conduction/hydra-gates/hydra-gates/contracts/ObjectFindTarget.php" />
+    <file name="vendor/conduction/hydra-gates/hydra-gates/contracts/SaveActor.php" />
+    <file name="vendor/conduction/hydra-gates/hydra-gates/contracts/SavePolicy.php" />
+    <file name="vendor/conduction/hydra-gates/hydra-gates/contracts/BulkBatchDefaults.php" />
+    <file name="vendor/conduction/hydra-gates/hydra-gates/contracts/LockRunStep.php" />
+    <file name="vendor/conduction/hydra-gates/hydra-gates/contracts/ObjectSaveOptions.php" />
+    <file name="vendor/conduction/hydra-gates/hydra-gates/contracts/BulkSaveOptions.php" />
+    <file name="vendor/conduction/hydra-gates/hydra-gates/contracts/LockRequest.php" />
+    <file name="vendor/conduction/hydra-gates/hydra-gates/contracts/UnlockRequest.php" />
+    <file name="vendor/conduction/hydra-gates/hydra-gates/contracts/ObjectFindOptions.php" />
+    <file name="vendor/conduction/hydra-gates/hydra-gates/contracts/ObjectDeletion.php" />
+    <file name="vendor/conduction/hydra-gates/hydra-gates/contracts/ObjectPatch.php" />
+    <file name="vendor/conduction/hydra-gates/hydra-gates/contracts/ObjectValidationVerdict.php" />

This PR is not mergeable before that .github PR.

Fleet check (package section "Fleet check")

All 19 apps from tools/sig/fleet_checkout.sh were checked out in full (tests included) from development: opencatalogi, integriq, filinq, thematiq, launchpad, stackiq, larpinq, dossiq, pipelinq, shillinq, learniq, portaliq, decidiq, buildiq, keepiq, hermiq, humaniq, versioniq, planninq.

  • What breaks. It is not only implements ObjectServiceInterface. In a run against the new openregister, a test class that extends OCA\OpenRegister\Service\ObjectService and overrides one of the eight methods with an old-typed parameter is narrower than the widened ObjectService and fatals. I parsed every PHP class (named and anonymous) and built the inheritance closure from ObjectServiceInterface and ObjectService. Overrides with a Kernel-typed value parameter exist in 7 apps (166 parameters in 78 files). The other 12 have none: dossiq's and planninq's in-memory registers are duck-typed and implement nothing; the stub interface copies in buildiq, decidiq, dossiq, hermiq, integriq, learniq and portaliq are only loaded when the real interface is absent.
  • The fix in each app types those parameters OldName|PublishedOldName. PHP matches a union member by name without loading the other class, so the doubles load against both today's openregister and this one. Checked first in an isolated PHP script; the old-typed double fatals.
  • Each app's own test run, three runs on its current development tip, PHP 8.3. (1) Unchanged. (2) The branch. (3) The branch against the new contract: this PR's lib/Contract and the deprecated Kernel values preloaded through an ini auto_prepend_file, and the app's ObjectService stub temporarily typed like this ObjectService. Unchanged development against the new contract fatals at class load in all 7; with the fix, each run matches its unchanged development run:
App PR files / params development branch branch vs new contract
ConductionNL/shillinq#3218 14 / 57 13,484 OK same same
ConductionNL/stackiq#2104 1 / 1 4,384, 2 failures (pre-existing) same same
ConductionNL/pipelinq#3996 14 / 34 9,445 OK same same
ConductionNL/filinq#2233 6 / 16 8,445 OK same same
ConductionNL/hermiq#1898 35 / 47 6,695, 177 E / 28 F (pre-existing) same list same list
ConductionNL/integriq#3765 7 / 10 10,736, 7 failing (pre-existing) same list 6 of those 7
ConductionNL/opencatalogi#2836 1 / 1 6,998, 68 E / 99 F (pre-existing) same list 59 E / 73 F, see that PR

The app PRs are safe against the current openregister and must land before this PR.

What ran

  • php -l on the 4 changed lib files: clean. vendor/bin/phpcs on them: the only error is a 158-character line at ObjectService.php:3643, which is not this change; 6 pre-existing @spec warnings.
  • vendor/bin/phpstan analyse --no-progress lib, compared with the same run on origin/main after merging: identical lists (54 on both). Before the merge: 38 on both, with the 4 + 3 + 4 + 3 + 1 receiving-chain findings fixed round by round.
  • vendor/bin/psalm --no-cache on the changed lib files: no errors.
  • python3 tools/sig/modularity_check.py --check: only the deliberate lib/Contract/ files above; no new reference against the order.
  • tools/sig/deptrac.sh areas --check: no new violating pair (only "gone" entries).
  • vendor/bin/phpunit -c phpunit.xml --no-coverage tests/Unit/Architecture: OK (2371 tests), after the last merge.
  • tests/Unit/Contract, the LockHandler*/AdvisoryLockStore* tests, ObjectServiceUpdateVersusPatchTest and ValidationHandlerBySchemaGoldenTest: OK (214 tests), after the last merge.
  • Every *Test.php that names LockHandler, AdvisoryLockStore, ObjectServiceInterface, Service\ObjectService or one of the eight old names (660 files): 9,288 tests. The only failures are 4 errors in AnonymousEnvelopeReadPathsTest, identical on PR b without this change, plus the one golden test updated here.
  • All of tests/Unit once, in 16 chunks, at e1fd7634 before the defaults commit: 61,019 tests outside Architecture. The only failures are the known AnonymousEnvelopeReadPathsTest (4) and ReservedColumnNamesTest (5). The latter downloads MariaDB's lex.h from raw.githubusercontent.com, which answered 404 here.

Order

  1. The 7 app PRs (any order): shillinq#3218, stackiq#2104, pipelinq#3996, filinq#2233, hermiq#1898, integriq#3765, opencatalogi#2836.
  2. The ConductionNL/.github companion PR (to be opened as above).
  3. refactor(architecture): publish the five values the object values name in lib/Contract (X00 a) #10976 (a) → refactor(architecture): publish the eight values ObjectServiceInterface names in lib/Contract (X00 b) #10977 (b) → this PR (c).

Written with Claude Code (claude-opus-5-5)

…n take the published values

The published ObjectServiceInterface now names the value classes in
lib/Contract instead of the deprecated Kernel\Contracts\Value names, so a
consuming app needs nothing beyond the published contract. ObjectService's
public signatures take the same published parents, and every parameter
phpstan found receiving one of them is widened to it: saveBulkWithinScope()
and patchWithinScope() in ObjectService, the lock and unlock path in
LockHandler and AdvisoryLockStore. The old names extend the published ones,
so every existing caller keeps working; construction sites and return types
keep the old names.

Assisted-by: ClaudeCode:claude-opus-5-5
Assisted-by: ClaudeCode:claude-opus-5-5
…uilding the deprecated values

A generated mock of ObjectServiceInterface fills an omitted argument with the
interface's own default. Built under the published name, that default
reached fleet test callbacks typed with the old Kernel\Contracts\Value names
as a Contract\ObjectSaveOptions and failed with a TypeError (shillinq
AccrualBookingTest, run against the new contract). saveObject() and
saveObjects() now default to the deprecated subclasses, so an omitted
argument passes exactly the value it passed before; the parameter types stay
the published classes. A test pins both the defaults and the mock behaviour.

Assisted-by: ClaudeCode:claude-opus-5-5
Assisted-by: ClaudeCode:claude-opus-5-5
@rubenvdlinde
rubenvdlinde merged commit e158c36 into main Nov 21, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant