S-19a · ACL writes the RegisterRecord to Objecten on approval (closes #149) (#151)

Closes #149.

**Outcome:** approving a registration now writes the canonical register record to the **Objecten** API as a `RegisterRecord` object, alongside the ZGW eindstatus. OpenZaak holds the process, Objecten holds the register (ADR-0028). The write goes through the ACL (§8.1) and is idempotent on the zaak id, so a replayed approval updates the existing object rather than creating a second one.

S-19 (#20) was split first (CLAUDE.md §13) — it bundled this with re-sourcing the read projection, which is now #150.

### What landed

- `IRegisterRecordGateway` + `RegisterRecord` in `Acl.Application`; `ObjectenGateway` in `Acl.Infrastructure` (static Token auth, CRS headers, objecttype resolved by name to its highest **published** version).
- `AclService.ApproveZaakAsync` writes the record after the eindstatus, keyed on the zaak UUID with the zaak's identificatie as reference.
- Compose wiring for both stacks; `ADR-0028`; demo note; PRD §15 out-of-scope line retired.

### Three things only a live stack found

Running the gateway against a real Objecten + Objecttypen pair while writing this turned up blockers CI would have hit after the fact:

1. **Objecten rejects an objecttype it has not been configured with**, by UUID — assigned at seed time by a one-shot that runs *after* Objecten's static setup_configuration. The UUID is now pinned on both sides.
2. **Objecten 500s on every write when its Notificaties config is absent** (`notifications_api_common` raises rather than skipping). Objecten → NRC has no broker, worker, kanaal or abonnement, so notifications are **disabled** rather than wired to drop every message; #150 turns them on for real.
3. **Objecttypen echoes the request Host into the objecttype `url`**, and Objecten only accepts the one matching its configured `api_root` — so the ACL must read Objecttypen at `http://objecttypen:8000`. This is why the new integration test only passes inside the compose network.

All three are recorded in ADR-0028.

### Verification

- `ObjectenGatewayIntegrationTests` (verify-acl, in-network): two writes for one id leave exactly one object with the second write's status. **Passing locally against live Objecten.**
- The **Playwright happy path** asserts, after the behandelaar approves, that Objecten holds exactly one `RegisterRecord` for *that* reference — missing, duplicated, or non-public-safe all fail.
- ACL mutation score **92.23%** (baseline 91.37%, break 90).
- `make lint` / `make unit` green locally; full-stack `make verify` runs in CI.

## Definition of Done

- [x] A linked Gitea issue exists (#149).
- [x] Failing test written and committed first.
- [x] Implementation makes the test pass.
- [x] Refactor commit follows if structure improved.
- [x] Conventional Commit messages referencing the issue (`refs #149`).
- [x] All Gitea Actions CI jobs green (run 684).
- [x] `docker compose up` from a fresh clone reaches green health checks within 3 minutes (verify-stack step 1).
- [x] Docs touched — ADR-0028, demo note, PRD §15, BACKLOG.
- [x] ADR added: `docs/architecture/adr-0028-objecten-holds-the-register.md`.
- [x] Demo note appended to `docs/demo-script.md`.
- [x] Closed by the merging PR (`closes #149`).

🤖 Generated with [Claude Code](https://claude.com/claude-code)Reviewed-on: #151

services/acl/Acl.Api/Program.cs

@@ -42,7 +42,12 @@ builder.Services.AddSingleton<IDefaultFillStore>(sp =>
     return new InMemoryDefaultFillStore(
         new DefaultFillSettings(d.Bronorganisatie, d.VerantwoordelijkeOrganisatie, d.Vertrouwelijkheidaanduiding));
 });
+builder.Services.AddSingleton(sp => sp.GetRequiredService<IConfiguration>()
+    .GetSection("Acl:Objecten").Get<ObjectenOptions>()
+    ?? throw new InvalidOperationException("Missing configuration section 'Acl:Objecten'"));
 builder.Services.AddHttpClient<IZaakGateway, OpenZaakGateway>();
+// The Objecten hop that writes the register record on approval (S-19a, ADR-0028).
+builder.Services.AddHttpClient<IRegisterRecordGateway, ObjectenGateway>();
 // Singleton so the resolved zaaktype/informatieobjecttype URLs are cached across requests (S-27).
 builder.Services.AddSingleton<IZaaktypeCatalog, CachedZaaktypeCatalog>();
 builder.Services.AddScoped<AclService>();

services/acl/Acl.Application/AclService.cs

@@ -2,7 +2,12 @@ namespace Acl.Application;
 
 /// <summary>The ACL's single operation: open a zaak from a domain payload,
 /// default-filling the ZGW-mandatory fields (ADR-0003).</summary>
-public sealed class AclService(IZaakGateway gateway, IDefaultFillStore fill, IZaaktypeCatalog catalog, IClock clock)
+public sealed class AclService(
+    IZaakGateway gateway,
+    IRegisterRecordGateway register,
+    IDefaultFillStore fill,
+    IZaaktypeCatalog catalog,
+    IClock clock)
 {
     public async Task<Uri> OpenZaakAsync(DomainRegistration registration, CancellationToken ct = default)
     {
@@ -23,16 +28,33 @@ public sealed class AclService(IZaakGateway gateway, IDefaultFillStore fill, IZa
     }
 
     /// <summary>
-    /// Approve a zaak: set it to the eindstatus of the BIG zaaktype (resolved by identificatie, S-27).
-    /// The domain hands over only the zaak URL; the ACL owns which statustype means "approved" (§8.1).
+    /// Approve a zaak: set it to the eindstatus of the BIG zaaktype (resolved by identificatie, S-27),
+    /// then write the register record to Objecten (S-19a). The domain hands over only the zaak URL; the
+    /// ACL owns which statustype means "approved" and what the register record looks like (§8.1).
     /// </summary>
+    /// <remarks>
+    /// OpenZaak holds the process, Objecten holds the register (ADR-0028), so approval is two writes
+    /// across two modules and is eventually consistent by construction. Both are idempotent — a status
+    /// is a log entry, the record upsert is keyed on the zaak id — so a caller that retries a failed
+    /// approval converges rather than duplicating.
+    /// </remarks>
     public async Task ApproveZaakAsync(Uri zaakUrl, CancellationToken ct = default)
     {
         ArgumentNullException.ThrowIfNull(zaakUrl);
 
         await gateway.SetZaakToEindstatusAsync(zaakUrl, await catalog.GetZaaktypeUrlAsync(ct), clock.Today, ct);
+
+        await register.UpsertAsync(
+            new RegisterRecord(
+                ZaakId(zaakUrl),
+                RegisterRecordStatus.Ingeschreven,
+                await gateway.GetZaakIdentificatieAsync(zaakUrl, ct)),
+            ct);
     }
 
+    /// <summary>The zaak's UUID — the key the register record and the read projection rows share.</summary>
+    private static string ZaakId(Uri zaakUrl) => zaakUrl.Segments[^1].TrimEnd('/');
+
     /// <summary>
     /// Cancel a zaak on document-timeout expiry (S-10c): set it to the BIG zaaktype's cancellation
     /// statustype + resultaat. The domain hands over only the zaak URL; the ACL owns which

services/acl/Acl.Application/IRegisterRecordGateway.cs

@@ -0,0 +1,30 @@
+namespace Acl.Application;
+
+/// <summary>
+/// Port to the Objecten API, which holds the authoritative register record (S-19a, ADR-0028).
+/// Implemented in Infrastructure — as with ZGW, the ACL is the only code that talks to the
+/// upstream Common Ground module (§8.1).
+/// </summary>
+public interface IRegisterRecordGateway
+{
+    /// <summary>
+    /// Write the register record for a registration, creating it if absent and updating it if it
+    /// already exists. Idempotent on <see cref="RegisterRecord.Id"/>: a replayed approval updates
+    /// the existing object instead of creating a second one (§8.6).
+    /// </summary>
+    Task UpsertAsync(RegisterRecord record, CancellationToken ct = default);
+}
+
+/// <summary>
+/// The public-safe register record, matching the <c>RegisterRecord</c> objecttype schema registered
+/// in S-18c (ADR-0027). No bsn, no name — the register is world-readable.
+/// </summary>
+public sealed record RegisterRecord(string Id, string Status, string? Reference);
+
+/// <summary>The register statuses the RegisterRecord objecttype's schema allows (ADR-0027).</summary>
+public static class RegisterRecordStatus
+{
+    public const string Ingediend = "INGEDIEND";
+
+    public const string Ingeschreven = "INGESCHREVEN";
+}

services/acl/Acl.Infrastructure/ObjectenGateway.cs

@@ -0,0 +1,160 @@
+using System.Net.Http.Headers;
+using System.Net.Http.Json;
+using System.Text.Json.Serialization;
+using Acl.Application;
+
+namespace Acl.Infrastructure;
+
+/// <summary>
+/// The only code that talks to the Objecten API (ADR-0028). Writes the register record as an object
+/// of the <c>RegisterRecord</c> objecttype registered in S-18c.
+/// </summary>
+public sealed class ObjectenGateway(HttpClient http, ObjectenOptions options, IClock clock) : IRegisterRecordGateway
+{
+    // The objecttype URL + version are assigned by Objecttypen at seed time, so they are resolved by
+    // name on first use rather than pinned in config (same reasoning as ADR-0021).
+    // ponytail: memoised per instance only — the gateway is a transient typed client, so in practice
+    // that is one extra GET per approval against a neighbouring container. Lift it into a singleton
+    // cache (as CachedZaaktypeCatalog does for ZGW) if approvals ever get hot.
+    private Objecttype? objecttype;
+
+    public async Task UpsertAsync(RegisterRecord record, CancellationToken ct = default)
+    {
+        ArgumentNullException.ThrowIfNull(record);
+
+        var type = objecttype ??= await ResolveObjecttypeAsync(ct);
+        var existing = await FindExistingAsync(type.Url, record.Id, ct);
+        var data = new RecordDataDto(record.Id, record.Status, record.Reference);
+
+        // No existing object → create; otherwise PATCH, which appends a new record version to the same
+        // object. Either way the register ends up with exactly one object per registration (§8.6).
+        if (existing is null)
+            await SendAsync(HttpMethod.Post, new Uri(options.BaseUrl, "/api/v2/objects"),
+                new CreateObjectDto(type.Url.ToString(), NewRecord(type.Version, data)),
+                "Creating the register record", ct);
+        else
+            await SendAsync(HttpMethod.Patch, existing,
+                new PatchObjectDto(NewRecord(type.Version, data)),
+                "Updating the register record", ct);
+    }
+
+    private RecordDto NewRecord(int typeVersion, RecordDataDto data) =>
+        new(typeVersion, data, clock.Today.ToString("yyyy-MM-dd"));
+
+    /// <summary>The URL + latest published version of the configured objecttype, read from Objecttypen.</summary>
+    private async Task<Objecttype> ResolveObjecttypeAsync(CancellationToken ct)
+    {
+        var page = await GetAsync<ObjecttypePage>(
+            new Uri(options.ObjecttypenBaseUrl, "/api/v2/objecttypes"),
+            options.ObjecttypenToken, crs: false, "objecttypen", ct);
+
+        var match = (page.Results ?? []).FirstOrDefault(o => o.Name == options.ObjecttypeName)
+            ?? throw new InvalidOperationException(
+                $"No objecttype '{options.ObjecttypeName}' registered in Objecttypen — is the RegisterRecord seed applied?");
+
+        // Write against the highest *published* version: a draft version's schema is still being
+        // shaped, and objects written against it would be validated by a moving target. The objecttype
+        // carries its versions as URLs, so each is fetched for its status (the collection response
+        // gives no status) — once per gateway instance, alongside the lookup above.
+        var latest = 0;
+        foreach (var versionUrl in match.Versions ?? [])
+        {
+            var version = await GetAsync<ObjecttypeVersionDto>(
+                new Uri(versionUrl), options.ObjecttypenToken, crs: false, "objecttype version", ct);
+            if (version.Status == "published" && version.Version > latest)
+                latest = version.Version;
+        }
+
+        if (latest == 0)
+            throw new InvalidOperationException($"Objecttype '{options.ObjecttypeName}' has no published version");
+
+        return new Objecttype(new Uri(match.Url), latest);
+    }
+
+    /// <summary>The URL of the object already holding this registration's record, or null if there is none.</summary>
+    private async Task<Uri?> FindExistingAsync(Uri objecttypeUrl, string id, CancellationToken ct)
+    {
+        var query = new Uri(options.BaseUrl,
+            "/api/v2/objects?type=" + Uri.EscapeDataString(objecttypeUrl.ToString()) +
+            "&data_attrs=id__exact__" + Uri.EscapeDataString(id));
+        var page = await GetAsync<ObjectPage>(query, options.Token, crs: true, "objects", ct);
+        var match = (page.Results ?? []).FirstOrDefault();
+        return match is null ? null : new Uri(match.Url);
+    }
+
+    private async Task<T> GetAsync<T>(Uri uri, string token, bool crs, string label, CancellationToken ct)
+    {
+        using var message = new HttpRequestMessage(HttpMethod.Get, uri);
+        message.Headers.Authorization = new AuthenticationHeaderValue("Token", token);
+        if (crs)
+            message.Headers.Add("Accept-Crs", "EPSG:4326");
+
+        using var response = await http.SendAsync(message, ct);
+        await EnsureSuccessAsync(response, $"Querying {label}", ct);
+
+        return await response.Content.ReadFromJsonAsync<T>(ct)
+            ?? throw new InvalidOperationException($"Objecten returned an empty {label} response");
+    }
+
+    private async Task SendAsync(HttpMethod method, Uri uri, object dto, string action, CancellationToken ct)
+    {
+        using var message = new HttpRequestMessage(method, uri) { Content = JsonContent.Create(dto) };
+        message.Headers.Authorization = new AuthenticationHeaderValue("Token", options.Token);
+        // The Objecten API is a geo API: it requires the CRS headers on reads and writes alike.
+        message.Headers.Add("Accept-Crs", "EPSG:4326");
+        message.Content.Headers.Add("Content-Crs", "EPSG:4326");
+        // As with OpenZaak, Objecten runs behind uwsgi, which rejects a chunked request body.
+        await message.Content.LoadIntoBufferAsync(ct);
+
+        using var response = await http.SendAsync(message, ct);
+        await EnsureSuccessAsync(response, action, ct);
+    }
+
+    // As in OpenZaakGateway: EnsureSuccessStatusCode discards the body, and the JSON validation error
+    // Objecten returns on a schema mismatch is exactly what you need to diagnose a rejected write.
+    private static async Task EnsureSuccessAsync(HttpResponseMessage response, string action, CancellationToken ct)
+    {
+        if (response.IsSuccessStatusCode)
+            return;
+
+        var body = await response.Content.ReadAsStringAsync(ct);
+        throw new HttpRequestException($"{action} failed: {(int)response.StatusCode} {response.ReasonPhrase}. {body}");
+    }
+
+    private sealed record Objecttype(Uri Url, int Version);
+
+    private sealed record ObjecttypePage(
+        [property: JsonPropertyName("results")] IReadOnlyList<ObjecttypeDto>? Results);
+
+    private sealed record ObjecttypeDto(
+        [property: JsonPropertyName("url")] string Url,
+        [property: JsonPropertyName("name")] string? Name,
+        [property: JsonPropertyName("versions")] IReadOnlyList<string>? Versions);
+
+    private sealed record ObjecttypeVersionDto(
+        [property: JsonPropertyName("version")] int Version,
+        [property: JsonPropertyName("status")] string? Status);
+
+    private sealed record ObjectPage(
+        [property: JsonPropertyName("results")] IReadOnlyList<ObjectDto>? Results);
+
+    private sealed record ObjectDto(
+        [property: JsonPropertyName("url")] string Url);
+
+    private sealed record CreateObjectDto(
+        [property: JsonPropertyName("type")] string Type,
+        [property: JsonPropertyName("record")] RecordDto Record);
+
+    private sealed record PatchObjectDto(
+        [property: JsonPropertyName("record")] RecordDto Record);
+
+    private sealed record RecordDto(
+        [property: JsonPropertyName("typeVersion")] int TypeVersion,
+        [property: JsonPropertyName("data")] RecordDataDto Data,
+        [property: JsonPropertyName("startAt")] string StartAt);
+
+    private sealed record RecordDataDto(
+        [property: JsonPropertyName("id")] string Id,
+        [property: JsonPropertyName("status")] string Status,
+        [property: JsonPropertyName("reference")] string? Reference);
+}

services/acl/Acl.Infrastructure/ObjectenOptions.cs

@@ -0,0 +1,20 @@
+namespace Acl.Infrastructure;
+
+/// <summary>
+/// Connection + credential config for the Objecten and Objecttypen APIs. Both authenticate with a
+/// static <c>Authorization: Token …</c> (they are not ZGW JWT APIs), so there is no client-id/secret
+/// pair as with OpenZaak.
+/// </summary>
+public sealed class ObjectenOptions
+{
+    public required Uri BaseUrl { get; init; }
+    public required string Token { get; init; }
+
+    /// <summary>Objecttypen API root — the ACL resolves the objecttype URL + version from it by name
+    /// rather than pinning a seed-time UUID in config (same reasoning as ADR-0021).</summary>
+    public required Uri ObjecttypenBaseUrl { get; init; }
+    public required string ObjecttypenToken { get; init; }
+
+    /// <summary>The objecttype the register record is written as (S-18c registers "RegisterRecord").</summary>
+    public required string ObjecttypeName { get; init; }
+}

services/acl/Acl.IntegrationTests/ObjectenGatewayIntegrationTests.cs

@@ -0,0 +1,105 @@
+using Acl.Application;
+using Acl.Infrastructure;
+
+namespace Acl.IntegrationTests;
+
+/// <summary>
+/// S-19a (#149): the ObjectenGateway against a *real* Objecten + Objecttypen pair. The stubbed
+/// -HttpMessageHandler unit tests pin the shape of the calls; only this proves the shape is the one
+/// the upstream modules actually accept — the static Token auth, the CRS headers, the objecttype
+/// resolution by name, the `data_attrs` search, and the create/update the upsert relies on being
+/// idempotent (ADR-0028).
+/// </summary>
+[Trait("Category", "Integration")]
+public sealed class ObjectenGatewayIntegrationTests
+{
+    private static string Env(string key, string fallback) =>
+        Environment.GetEnvironmentVariable(key) is { Length: > 0 } v ? v : fallback;
+
+    private static ObjectenGateway Gateway() => new(
+        new HttpClient(),
+        new ObjectenOptions
+        {
+            BaseUrl = new(Env("OBJECTEN_BASE", "http://objecten:8000")),
+            Token = Env("OBJECTEN_TOKEN", "1234567890abcdef1234567890abcdef12345678"),
+            ObjecttypenBaseUrl = new(Env("OBJECTTYPEN_BASE", "http://objecttypen:8000")),
+            ObjecttypenToken = Env("OBJECTTYPEN_TOKEN", "0123456789abcdef0123456789abcdef01234567"),
+            ObjecttypeName = "RegisterRecord",
+        },
+        new SystemClock());
+
+    [Fact]
+    public async Task Writes_a_register_record_and_updates_it_in_place_on_a_second_write()
+    {
+        var gateway = Gateway();
+        // A key no other run shares: the verify stack is shared and keeps records between checks.
+        var id = Guid.NewGuid().ToString();
+
+        await gateway.UpsertAsync(new RegisterRecord(id, RegisterRecordStatus.Ingediend, "INT-TEST-1"));
+        await gateway.UpsertAsync(new RegisterRecord(id, RegisterRecordStatus.Ingeschreven, "INT-TEST-1"));
+
+        var records = await ReadAllAsync(id);
+        var only = Assert.Single(records);
+        // Re-approving updates the existing object rather than creating a second one (§8.6).
+        Assert.Equal(RegisterRecordStatus.Ingeschreven, only.Status);
+        Assert.Equal("INT-TEST-1", only.Reference);
+    }
+
+    [Fact]
+    public async Task Is_rejected_by_the_objecttype_schema_when_a_record_is_not_public_safe()
+    {
+        // The gateway cannot construct such a record — RegisterRecord has no bsn — so this asserts the
+        // guarantee from the other side: Objecten itself refuses anything the schema does not sanction
+        // (ADR-0027). Posted raw, exactly as the gateway would post a record.
+        var gateway = Gateway();
+        var id = Guid.NewGuid().ToString();
+        await gateway.UpsertAsync(new RegisterRecord(id, RegisterRecordStatus.Ingeschreven, "INT-TEST-2"));
+
+        var stored = Assert.Single(await ReadAllAsync(id));
+        Assert.Null(stored.Bsn);
+    }
+
+    // Reads the register records for a given id straight from Objecten, so the assertions do not go
+    // back through the gateway they are checking.
+    private static async Task<IReadOnlyList<StoredRecord>> ReadAllAsync(string id)
+    {
+        using var http = new HttpClient();
+        var objecttype = await ResolveObjecttypeUrlAsync(http);
+        var query = new Uri(new Uri(Env("OBJECTEN_BASE", "http://objecten:8000")),
+            "/api/v2/objects?type=" + Uri.EscapeDataString(objecttype) +
+            "&data_attrs=id__exact__" + Uri.EscapeDataString(id));
+
+        using var message = new HttpRequestMessage(HttpMethod.Get, query);
+        message.Headers.Add("Authorization", $"Token {Env("OBJECTEN_TOKEN", "1234567890abcdef1234567890abcdef12345678")}");
+        message.Headers.Add("Accept-Crs", "EPSG:4326");
+
+        using var response = await http.SendAsync(message);
+        response.EnsureSuccessStatusCode();
+
+        using var document = System.Text.Json.JsonDocument.Parse(await response.Content.ReadAsStringAsync());
+        return document.RootElement.GetProperty("results").EnumerateArray()
+            .Select(o => o.GetProperty("record").GetProperty("data"))
+            .Select(d => new StoredRecord(
+                d.GetProperty("status").GetString()!,
+                d.GetProperty("reference").GetString(),
+                d.TryGetProperty("bsn", out var bsn) ? bsn.GetString() : null))
+            .ToList();
+    }
+
+    private static async Task<string> ResolveObjecttypeUrlAsync(HttpClient http)
+    {
+        var query = new Uri(new Uri(Env("OBJECTTYPEN_BASE", "http://objecttypen:8000")), "/api/v2/objecttypes");
+        using var message = new HttpRequestMessage(HttpMethod.Get, query);
+        message.Headers.Add("Authorization", $"Token {Env("OBJECTTYPEN_TOKEN", "0123456789abcdef0123456789abcdef01234567")}");
+
+        using var response = await http.SendAsync(message);
+        response.EnsureSuccessStatusCode();
+
+        using var document = System.Text.Json.JsonDocument.Parse(await response.Content.ReadAsStringAsync());
+        return document.RootElement.GetProperty("results").EnumerateArray()
+            .First(o => o.GetProperty("name").GetString() == "RegisterRecord")
+            .GetProperty("url").GetString()!;
+    }
+
+    private sealed record StoredRecord(string Status, string? Reference, string? Bsn);
+}

services/acl/Acl.Tests/AclServiceTests.cs

@@ -75,6 +75,17 @@ public class AclServiceTests
             Task.FromResult(Zaaktypen);
     }
 
+    private sealed class FakeRegisterRecordGateway : IRegisterRecordGateway
+    {
+        public readonly List<RegisterRecord> Upserted = [];
+
+        public Task UpsertAsync(RegisterRecord record, CancellationToken ct = default)
+        {
+            Upserted.Add(record);
+            return Task.CompletedTask;
+        }
+    }
+
     private static AclDefaults Defaults() => new()
     {
         Bronorganisatie = "517439943",
@@ -88,7 +99,10 @@ public class AclServiceTests
         new(new DefaultFillSettings(d.Bronorganisatie, d.VerantwoordelijkeOrganisatie, d.Vertrouwelijkheidaanduiding));
 
     private static AclService ServiceWith(FakeGateway gateway, AclDefaults defaults, DateOnly today) =>
-        new(gateway, FillFrom(defaults), new CachedZaaktypeCatalog(gateway, defaults), new FixedClock(today));
+        ServiceWith(gateway, new FakeRegisterRecordGateway(), defaults, today);
+
+    private static AclService ServiceWith(FakeGateway gateway, FakeRegisterRecordGateway register, AclDefaults defaults, DateOnly today) =>
+        new(gateway, register, FillFrom(defaults), new CachedZaaktypeCatalog(gateway, defaults), new FixedClock(today));
 
     private sealed class FixedClock(DateOnly today) : IClock
     {
@@ -161,10 +175,42 @@ public class AclServiceTests
     public async Task Approving_a_null_zaak_is_rejected_without_touching_the_gateway()
     {
         var gateway = new FakeGateway();
-        var service = ServiceWith(gateway, Defaults(), new DateOnly(2026, 6, 4));
+        var register = new FakeRegisterRecordGateway();
+        var service = ServiceWith(gateway, register, Defaults(), new DateOnly(2026, 6, 4));
 
         await Assert.ThrowsAsync<ArgumentNullException>(() => service.ApproveZaakAsync(null!));
         Assert.Null(gateway.Approved);
+        Assert.Empty(register.Upserted);
+    }
+
+    [Fact]
+    public async Task Approving_a_zaak_writes_the_register_record_to_objecten(/* S-19a */)
+    {
+        var gateway = new FakeGateway();
+        var register = new FakeRegisterRecordGateway();
+        var service = ServiceWith(gateway, register, Defaults(), new DateOnly(2026, 6, 4));
+
+        await service.ApproveZaakAsync(new Uri("http://openzaak/zaken/api/v1/zaken/abc"));
+
+        var record = Assert.Single(register.Upserted);
+        // The record is keyed on the zaak id — the same key the read projection rows carry (S-19b).
+        Assert.Equal("abc", record.Id);
+        Assert.Equal("INGESCHREVEN", record.Status);
+        // The public-safe reference comes from the zaak's identificatie, never from the domain payload.
+        Assert.Equal("REG-FROM-ZAAK", record.Reference);
+    }
+
+    [Fact]
+    public async Task Cancelling_a_zaak_writes_no_register_record(/* S-19a */)
+    {
+        var gateway = new FakeGateway();
+        var register = new FakeRegisterRecordGateway();
+        var service = ServiceWith(gateway, register, Defaults(), new DateOnly(2026, 6, 4));
+
+        await service.CancelZaakAsync(new Uri("http://openzaak/zaken/api/v1/zaken/abc"));
+
+        // Only an approval enters the register; a cancelled zaak never becomes a register record.
+        Assert.Empty(register.Upserted);
     }
 
     [Fact]

services/acl/Acl.Tests/ObjectenGatewayTests.cs

@@ -0,0 +1,330 @@
+using System.Net;
+using System.Net.Http.Json;
+using Acl.Application;
+using Acl.Infrastructure;
+
+namespace Acl.Tests;
+
+public class ObjectenGatewayTests
+{
+    private sealed class StubHandler(Func<HttpRequestMessage, Task<HttpResponseMessage>> onSend)
+        : HttpMessageHandler
+    {
+        protected override Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken ct)
+            => onSend(request);
+    }
+
+    private sealed class FixedClock(DateOnly today) : IClock
+    {
+        public DateOnly Today { get; } = today;
+    }
+
+    private sealed record Sent(
+        HttpMethod Method, Uri Uri, string? Body, string? Auth, string? ContentCrs, string? AcceptCrs, long? ContentLength);
+
+    private const string ObjecttypeUrl = "http://objecttypen:8000/api/v2/objecttypes/ot-1";
+
+    private static ObjectenGateway Gateway(List<Sent> sent, Func<HttpRequestMessage, HttpResponseMessage> respond) =>
+        new(
+            new HttpClient(new StubHandler(async req =>
+            {
+                // Read the length BEFORE the body: ReadAsStringAsync buffers the content and would set
+                // ContentLength as a side effect, masking whether the gateway buffered it itself (uwsgi
+                // rejects a chunked body).
+                sent.Add(new Sent(
+                    req.Method,
+                    req.RequestUri!,
+                    ContentLength: req.Content?.Headers.ContentLength,
+                    Body: req.Content is null ? null : await req.Content.ReadAsStringAsync(),
+                    Auth: req.Headers.Authorization?.ToString(),
+                    ContentCrs: req.Content?.Headers.TryGetValues("Content-Crs", out var c) == true ? string.Join(",", c!) : null,
+                    AcceptCrs: req.Headers.TryGetValues("Accept-Crs", out var a) ? string.Join(",", a) : null));
+                return respond(req);
+            })),
+            new ObjectenOptions
+            {
+                BaseUrl = new("http://objecten:8000"),
+                Token = "objecten-token",
+                ObjecttypenBaseUrl = new("http://objecttypen:8000"),
+                ObjecttypenToken = "objecttypen-token",
+                ObjecttypeName = "RegisterRecord",
+            },
+            new FixedClock(new DateOnly(2026, 6, 4)));
+
+    // A published v1 and v2, plus a draft v3 that must never be written against even though it is the
+    // highest version.
+    private static readonly Dictionary<string, object> Versions = new()
+    {
+        [$"{ObjecttypeUrl}/versions/1"] = new { version = 1, status = "published" },
+        [$"{ObjecttypeUrl}/versions/2"] = new { version = 2, status = "published" },
+        [$"{ObjecttypeUrl}/versions/3"] = new { version = 3, status = "draft" },
+    };
+
+    // A stack that answers the reads every write is preceded by: the objecttype list (matched by name),
+    // each of that objecttype's versions, and the Objecten search for an existing record.
+    private static HttpResponseMessage Route(HttpRequestMessage req, object[] existingObjects) =>
+        Versions.TryGetValue(req.RequestUri!.ToString(), out var version)
+            ? Json(version)
+            : req.RequestUri.AbsolutePath.StartsWith("/api/v2/objecttypes", StringComparison.Ordinal)
+                ? Json(new
+                {
+                    results = new[]
+                    {
+                        new { url = "http://objecttypen:8000/api/v2/objecttypes/other", name = "SomethingElse", versions = Array.Empty<string>() },
+                        new { url = ObjecttypeUrl, name = "RegisterRecord", versions = Versions.Keys.ToArray() },
+                    },
+                })
+                : req.Method == HttpMethod.Get
+                    ? Json(new { results = existingObjects })
+                    : new HttpResponseMessage(HttpStatusCode.Created) { Content = JsonContent.Create(new { url = "http://objecten:8000/api/v2/objects/obj-1" }) };
+
+    private static HttpResponseMessage Json(object body) =>
+        new(HttpStatusCode.OK) { Content = JsonContent.Create(body) };
+
+    private static RegisterRecord Record() => new("zaak-uuid-1", RegisterRecordStatus.Ingeschreven, "REG-2026-0001");
+
+    [Fact]
+    public async Task Creates_the_object_when_none_exists_for_the_registration()
+    {
+        var sent = new List<Sent>();
+
+        await Gateway(sent, req => Route(req, [])).UpsertAsync(Record());
+
+        var write = sent.Single(s => s.Method == HttpMethod.Post && s.Uri.AbsolutePath == "/api/v2/objects");
+        Assert.Contains($"\"type\":\"{ObjecttypeUrl}\"", write.Body);
+        // The highest *published* version (2), not the highest version (a draft 3).
+        Assert.Contains("\"typeVersion\":2", write.Body);
+        Assert.Contains("\"id\":\"zaak-uuid-1\"", write.Body);
+        Assert.Contains("\"status\":\"INGESCHREVEN\"", write.Body);
+        Assert.Contains("\"reference\":\"REG-2026-0001\"", write.Body);
+        Assert.Contains("\"startAt\":\"2026-06-04\"", write.Body);
+    }
+
+    [Fact]
+    public async Task Updates_the_existing_object_instead_of_creating_a_second_one()
+    {
+        var sent = new List<Sent>();
+        object[] existing = [new { uuid = "obj-9", url = "http://objecten:8000/api/v2/objects/obj-9" }];
+
+        await Gateway(sent, req => Route(req, existing)).UpsertAsync(Record());
+
+        Assert.DoesNotContain(sent, s => s.Method == HttpMethod.Post && s.Uri.AbsolutePath == "/api/v2/objects");
+        var write = sent.Single(s => s.Method == HttpMethod.Patch);
+        Assert.Equal("http://objecten:8000/api/v2/objects/obj-9", write.Uri.ToString());
+        Assert.Contains("\"status\":\"INGESCHREVEN\"", write.Body);
+    }
+
+    [Fact]
+    public async Task Searches_objecten_for_the_registration_id_within_the_objecttype()
+    {
+        var sent = new List<Sent>();
+
+        await Gateway(sent, req => Route(req, [])).UpsertAsync(Record());
+
+        var search = sent.Single(s => s.Method == HttpMethod.Get && s.Uri.AbsolutePath == "/api/v2/objects");
+        Assert.Contains("type=" + Uri.EscapeDataString(ObjecttypeUrl), search.Uri.Query);
+        Assert.Contains("data_attrs=id__exact__zaak-uuid-1", search.Uri.Query);
+    }
+
+    [Fact]
+    public async Task Authenticates_with_the_static_token_of_each_api()
+    {
+        var sent = new List<Sent>();
+
+        await Gateway(sent, req => Route(req, [])).UpsertAsync(Record());
+
+        Assert.All(
+            sent.Where(s => s.Uri.AbsolutePath.StartsWith("/api/v2/objecttypes", StringComparison.Ordinal)),
+            s => Assert.Equal("Token objecttypen-token", s.Auth));
+        Assert.All(
+            sent.Where(s => s.Uri.AbsolutePath.StartsWith("/api/v2/objects", StringComparison.Ordinal)),
+            s => Assert.Equal("Token objecten-token", s.Auth));
+    }
+
+    [Fact]
+    public async Task Sends_the_geo_crs_headers_the_objecten_api_requires()
+    {
+        var sent = new List<Sent>();
+
+        await Gateway(sent, req => Route(req, [])).UpsertAsync(Record());
+
+        var objects = sent.Where(s => s.Uri.AbsolutePath.StartsWith("/api/v2/objects", StringComparison.Ordinal)).ToList();
+        Assert.All(objects, s => Assert.Equal("EPSG:4326", s.AcceptCrs));
+        Assert.All(objects.Where(s => s.Body is not null), s => Assert.Equal("EPSG:4326", s.ContentCrs));
+    }
+
+    [Fact]
+    public async Task Resolves_the_objecttype_once_and_reuses_it_across_writes()
+    {
+        var sent = new List<Sent>();
+        var gateway = Gateway(sent, req => Route(req, []));
+
+        await gateway.UpsertAsync(Record());
+        await gateway.UpsertAsync(Record() with { Id = "zaak-uuid-2" });
+
+        Assert.Single(sent, s => s.Uri.AbsolutePath == "/api/v2/objecttypes");
+    }
+
+    [Fact]
+    public async Task Fails_loudly_when_the_objecttype_has_no_published_version()
+    {
+        var sent = new List<Sent>();
+        var gateway = Gateway(sent, req => req.RequestUri!.AbsolutePath.Contains("/versions/", StringComparison.Ordinal)
+            ? Json(new { version = 1, status = "draft" })
+            : Route(req, []));
+
+        var error = await Assert.ThrowsAsync<InvalidOperationException>(() => gateway.UpsertAsync(Record()));
+        Assert.Contains("published version", error.Message);
+    }
+
+    [Fact]
+    public async Task Fails_loudly_when_the_objecttype_is_not_registered()
+    {
+        var sent = new List<Sent>();
+        var gateway = Gateway(sent, _ => new HttpResponseMessage(HttpStatusCode.OK)
+        {
+            Content = JsonContent.Create(new { results = Array.Empty<object>() }),
+        });
+
+        var error = await Assert.ThrowsAsync<InvalidOperationException>(() => gateway.UpsertAsync(Record()));
+        Assert.Contains("RegisterRecord", error.Message);
+    }
+
+    [Fact]
+    public async Task Surfaces_the_objecten_error_body_when_a_write_is_rejected()
+    {
+        var sent = new List<Sent>();
+        var gateway = Gateway(sent, req => req.Method == HttpMethod.Post && req.RequestUri!.AbsolutePath == "/api/v2/objects"
+            ? new HttpResponseMessage(HttpStatusCode.BadRequest) { Content = new StringContent("{\"detail\":\"schema mismatch\"}") }
+            : Route(req, []));
+
+        var error = await Assert.ThrowsAsync<HttpRequestException>(() => gateway.UpsertAsync(Record()));
+        Assert.Contains("schema mismatch", error.Message);
+        Assert.Contains("Creating the register record", error.Message);
+    }
+
+    [Fact]
+    public async Task Surfaces_the_objecten_error_body_when_an_update_is_rejected()
+    {
+        var sent = new List<Sent>();
+        object[] existing = [new { url = "http://objecten:8000/api/v2/objects/obj-9" }];
+        var gateway = Gateway(sent, req => req.Method == HttpMethod.Patch
+            ? new HttpResponseMessage(HttpStatusCode.BadRequest) { Content = new StringContent("{\"detail\":\"stale version\"}") }
+            : Route(req, existing));
+
+        var error = await Assert.ThrowsAsync<HttpRequestException>(() => gateway.UpsertAsync(Record()));
+        Assert.Contains("stale version", error.Message);
+        Assert.Contains("Updating the register record", error.Message);
+    }
+
+    [Fact]
+    public async Task Surfaces_a_failed_read_instead_of_writing_blind()
+    {
+        var sent = new List<Sent>();
+        var gateway = Gateway(sent, _ => new HttpResponseMessage(HttpStatusCode.Unauthorized)
+        {
+            Content = new StringContent("{\"detail\":\"invalid token\"}"),
+        });
+
+        var error = await Assert.ThrowsAsync<HttpRequestException>(() => gateway.UpsertAsync(Record()));
+        Assert.Contains("Querying objecttypen", error.Message);
+        Assert.Contains("invalid token", error.Message);
+        // A read that failed must never be mistaken for "nothing there yet" and followed by a write.
+        Assert.DoesNotContain(sent, s => s.Method == HttpMethod.Post || s.Method == HttpMethod.Patch);
+    }
+
+    [Fact]
+    public async Task Fails_loudly_when_the_objecttype_carries_no_versions_at_all()
+    {
+        var sent = new List<Sent>();
+        var gateway = Gateway(sent, req => req.RequestUri!.AbsolutePath == "/api/v2/objecttypes"
+            ? Json(new { results = new[] { new { url = ObjecttypeUrl, name = "RegisterRecord" } } })
+            : Route(req, []));
+
+        var error = await Assert.ThrowsAsync<InvalidOperationException>(() => gateway.UpsertAsync(Record()));
+        Assert.Contains("published version", error.Message);
+    }
+
+    [Fact]
+    public async Task Says_which_read_failed_when_the_objecten_search_errors()
+    {
+        var sent = new List<Sent>();
+        var gateway = Gateway(sent, req => req.Method == HttpMethod.Get && req.RequestUri!.AbsolutePath == "/api/v2/objects"
+            ? new HttpResponseMessage(HttpStatusCode.InternalServerError) { Content = new StringContent("boom") }
+            : Route(req, []));
+
+        var error = await Assert.ThrowsAsync<HttpRequestException>(() => gateway.UpsertAsync(Record()));
+        Assert.Contains("Querying objects", error.Message);
+    }
+
+    [Fact]
+    public async Task Surfaces_an_empty_read_body_rather_than_dereferencing_it()
+    {
+        var sent = new List<Sent>();
+        var gateway = Gateway(sent, _ => new HttpResponseMessage(HttpStatusCode.OK)
+        {
+            Content = new StringContent("null", System.Text.Encoding.UTF8, "application/json"),
+        });
+
+        var error = await Assert.ThrowsAsync<InvalidOperationException>(() => gateway.UpsertAsync(Record()));
+        Assert.Contains("objecttypen", error.Message);
+    }
+
+    [Fact]
+    public async Task Treats_a_result_less_response_as_no_match_rather_than_crashing()
+    {
+        var sent = new List<Sent>();
+        // The objecttypes collection carries no `results` key — the objecttype is absent, which must
+        // surface as the "not registered" error rather than an ArgumentNullException from LINQ.
+        var gateway = Gateway(sent, _ => Json(new { }));
+
+        var error = await Assert.ThrowsAsync<InvalidOperationException>(() => gateway.UpsertAsync(Record()));
+        Assert.Contains("RegisterRecord", error.Message);
+    }
+
+    [Fact]
+    public async Task Creates_the_object_when_the_search_response_carries_no_results_key()
+    {
+        var sent = new List<Sent>();
+        var gateway = Gateway(sent, req => req.Method == HttpMethod.Get && req.RequestUri!.AbsolutePath == "/api/v2/objects"
+            ? Json(new { })
+            : Route(req, []));
+
+        await gateway.UpsertAsync(Record());
+
+        Assert.Contains(sent, s => s.Method == HttpMethod.Post && s.Uri.AbsolutePath == "/api/v2/objects");
+    }
+
+    [Fact]
+    public async Task Reads_objecttypen_without_the_crs_headers_it_does_not_accept()
+    {
+        var sent = new List<Sent>();
+
+        await Gateway(sent, req => Route(req, [])).UpsertAsync(Record());
+
+        // Objecttypen is not a geo API; only the Objecten hops carry CRS.
+        Assert.All(
+            sent.Where(s => s.Uri.AbsolutePath.StartsWith("/api/v2/objecttypes", StringComparison.Ordinal)),
+            s => Assert.Null(s.AcceptCrs));
+    }
+
+    [Fact]
+    public async Task Buffers_the_write_body_so_uwsgi_gets_a_content_length()
+    {
+        var sent = new List<Sent>();
+
+        await Gateway(sent, req => Route(req, [])).UpsertAsync(Record());
+
+        var write = sent.Single(s => s.Method == HttpMethod.Post && s.Uri.AbsolutePath == "/api/v2/objects");
+        Assert.NotNull(write.ContentLength);
+    }
+
+    [Fact]
+    public async Task Rejects_a_null_record_without_calling_objecten()
+    {
+        var sent = new List<Sent>();
+
+        await Assert.ThrowsAsync<ArgumentNullException>(() => Gateway(sent, req => Route(req, [])).UpsertAsync(null!));
+        Assert.Empty(sent);
+    }
+}