net-kingdom/docs/service-group-provenance.md

Durable service group creation provenance

This source change narrows the existing authenticated identity-provisioner /v1/groups/ensure and /v1/groups/revoke endpoints. It introduces no new principal, credential, policy decision, or rollback authorization. An endpoint's service token and a journal receipt do not establish an accepted case, caller session, owner assent, or permission to use a protected execution lane.

Request and receipt migration

Ensure keeps groups, members, idempotency_key and correlation_id. The original correlation is now part of its immutable binding: the original idempotency key with a different correlation or group/member request is refused. The response adds ensure_idempotency_key, ensure_correlation_id, created_groups (name and exact directory id) and created_memberships (name, directory id and username). The owner journal independently retains the complete prestate and expected postimage. Response inventories are advisory; caller-supplied inventories are rejected and never authorize undo.

Revoke retains the original group/member request, its own idempotency_key and correlation_id, and optional boolean delete_if_empty. It additionally requires ensure_idempotency_key and ensure_correlation_id from the original ensure. Legacy revoke requests fail before directory access. No old deployment inventory is imported as proof of creation: pre-upgrade groups and memberships cannot be rolled back automatically without independent owner reconciliation.

An ensure replay returns its original receipt and never recreates subsequently removed state. Reusing its key after rollback is refused. Revoke replays return its original outcome; changing deletion options after completion is refused. There are at most 16 groups, 256 requested membership entries, 4096 retained preexisting members per operation, and 256 journal records by default. Records have no timeout or automatic eviction. Capacity exhaustion stops new operations.

Storage policy and local fixture configuration

The implemented SQLite backend is for local development and disposable tests. It is not an admitted production storage design. Accepted ADR-0015 section3 requires production relational storage through CloudNative PG and rapp-postgres using database-per-consumer; it explicitly rejects per-workload SQLite-on-a-PVC as a production pattern. The rail-kubernetes wave-1 contract also does not supply a generic persistent-storage contract. This source does not authorize adding a SQLite PVC to identity-provisioner.

Production group operations remain unadmitted and must stay disabled until the existing owner paths admit a CNPG-backed implementation of the same journal semantics, credentials, storage/backup/restore and writer-isolation contracts, or an explicit governed exception to ADR-0015 identifies the exact scope, limits, duration, recovery and risk owner. No such backend, exception or native assent is supplied here. railiance-platform owns shared database/custody governance; rapp-postgres owns the package consumer provisioning surface. The identity-provisioner runtime package/operating assignment must also be explicitly settled rather than inferred from User Engine's dependency on it.

For local/disposable tests only, GROUP_PROVENANCE_DB selects an absolute, non-symlink SQLite path in a private test directory owned by the process UID, with mode0700 for the directory and mode0600 for the database. The local fixture explicitly initializes a genuinely new empty store with GroupProvenance(absolute_path, initialize=True); initialization refuses an existing file. Ordinary opening never recreates a missing store. The completed disposable fixture uses private container tmpfs and preserves the file across separate Python processes; that proves process-restart semantics, not production durability. /tmp, emptyDir, tmpfs and an image layer do not satisfy native retention or recovery duties.

With no configuration, ordinary directory readiness reports service_groups: disabled and group endpoints refuse work. Missing/untrusted or unavailable configured local storage prevents startup or returns a fixed group_provenance dependency failure without path/database diagnostics. service_groups: available checks capability only: the implementation does not infer or enforce production admission, policy exceptions, accepted cases or writer isolation from a filesystem path.

The existing reference Deployment remains one Recreate replica at UID/GID10001 with readOnlyRootFilesystem: true, no provenance volume and an older immutable image. Image rebuild, native owner review and credential delivery remain separate acts. Preserve its nonroot/read-only boundaries. Native retention and recovery must preserve original idempotency bindings, prestate, confirmed creations and unresolved intents; losing a journal never authorizes replacement initialization and replay. No arbitrary JSON import, receipt expiry or automatic uncertainty clearing is introduced. Owner reconciliation needs independent evidence.

PostgreSQL source seam (not native admission)

PostgresGroupProvenance implements the same reserve/get/claim-revoke/save/check journal contract. It is injection-only: the ordinary HTTP server has no PostgreSQL environment switch and remains without a group store unless the existing local SQLite configuration is explicitly supplied. GROUP_POSTGRES_DSN or a caller JSON object cannot enable the PostgreSQL path. Production group operations remain unadmitted and disabled pending the owner callbacks and gates above; a backend constructor is not an access decision.

A trusted owner integration must provide an exact GroupJournalBinding with opaque authoritative tenant scope, directory instance, accepted case digest, source digest, represented principal and journal epoch. There is no guessed platform-root scope or request-derived tenant fallback. The owner also injects a renewable private connection-info callback using the existing rapp-postgres consumer/lease contract, and independently durable JournalContinuity callbacks. These callbacks retain/check/advance exact epoch+directory+head+commit digest outside the PostgreSQL state that might be restored. Neither callback authenticates a caller or grants a protected side effect. Their native custody, source binding, revocation and execution bounds still require independent admission. Only the disposable fixture supplies a test checkpoint implementation here.

The v1 migration under identity-provisioner/migrations/ creates tables within the existing consumer schema; it creates no database/schema/roles, inserts no epoch and clears no quarantine. Startup does not run migrations or initialize missing state. The owner must separately admit an epoch/checkpoint after independent continuity/recovery review; absent or quarantined state refuses. A restored database with an older head than the independently retained checkpoint also refuses rather than treating missing later intents as authority to replay.

PostgreSQL transactions lock the single journal metadata row, commit bounded receipts/intents and advance the head and exact transition digest with an exactly-one conditional update. The digest binds the prior marker, canonical body, context, request key and receipt version; the independent checkpoint must compare/CAS both content and sequence, never accept a counter-only callback. Divergent restored clones that commit different transitions at the same counter cannot both be accepted. Every receipt update also requires its exact context/key/request/version and increments its version. The active slot spans all contexts in the journal; it serializes cooperating producer operations, not external LDAP writers. SQL commit precedes independently durable checkpoint acknowledgment. A lost commit/acknowledgment, stale version, missing row or continuity mismatch refuses and poisons that backend object; exception handling cannot automatically rewrite its journal into success. Known request-binding mismatches remain domain refusals. Definite before-mutation refusal records can release the active slot while the original key remains terminal.

The container source includes a hash-pinned Linux amd64 CPython3.12 psycopg3 closure selected from User Engine's existing lockfile. No image build or package installation is part of this source proof; build/publication, artifact scanning and native runtime/dependency admission remain owner work. SQLite is still local/disposable only. The separate PostgreSQL fixture proposal uses a cached pinned PostgreSQL image and a cached pinned User Engine Python image, real SQL, separate-process reopen, concurrency, stale-CAS and actual pg_dump/pg_restore behind an independently retained test checkpoint. That fixture needs exact review before Docker execution and does not prove live CNPG HA, TLS/lease custody, tenant authority, external writer fencing, production retention or protected session/evidence integration.

Safety and remaining native acceptance

Before each directory mutation, durable intent is committed. A successful response and exact readback are required before recording a confirmed creation. A definite failure before any mutation attempt retains a refused record and releases the active fence; its original key still cannot retry. Transport loss, readback failure after an attempted mutation or a process exit leaves pending/uncertain state; it survives reopening and blocks new mutations instead of becoming retry success. Every database connection rechecks the private path and original device/inode; missing/replaced storage is refused. Every intent update must affect exactly one matching journal row before execution can continue. The journal records mutation intent and confirmed outcomes, not an atomic LDAP transaction or a complete audit emission guarantee.

Rollback validates every targeted group id and complete member postimage before its first destructive operation, and verifies each subsequent change. It removes only memberships confirmed newly added by that ensure. It deletes only groups confirmed newly created by that ensure, and only while empty. Preexisting groups, including empty groups, are never deleted. Existing members are never included in the removal inventory. Detected shared-member drift or group replacement refuses the operation before any destructive call and retains uncertainty.

LLDAP exposes no membership-generation token or conditional mutation/CAS here. Readback cannot detect a remove/re-add ABA sequence or close a read/write race with an external writer. Native rollback therefore still requires an owner-proven writer isolation/fencing contract or a provider-side versioned/CAS operation; these synthetic fixtures do not prove that boundary. A durable SQLite file is trusted local owner-held state, not a production storage admission, tamper-evident remote evidence or an authorization broker. Existing caller authentication is unchanged; case/source/principal binding, per-attempt protected session revocation, independently admitted evidence callbacks, native storage/backup recovery and native endpoint acceptance remain outstanding under NK-WP-0048-T14/T16. This source change alone does not finish those tasks.