✨🧑‍💻 - Complete the verified household administration workspace after the profile model foundation #21

# Household administration integration continuation

- Status: Draft
- Date: 2026-11-02
- Catalog capability ID: household-identity (companion)
- Last verified: not applicable to proposed integration; baseline verified below
- Owners: Domus maintainers (review assignment pending)
- Scope: Complete the retained household administration workspace on the actually merged schema8 base, with schema9, private preferences, current authority and both deployments.
- Related issues/PRs: https://github.com/vypdev/domus/issues/21 ; https://github.com/vypdev/domus/pull/22 ; https://github.com/vypdev/domus/issues/23
- Required review gates: product UX, architecture, testing, documentation, security/operations
- Open decisions blocking readiness: None; execution and acceptance evidence remain required.

This integration companion preserves `specs/household-administration.md` and `specs/household-identity.md` verbatim. All eight HADM requirements, all 72 original administration cases and all owning identity/delivery requirements remain mandatory. The additional integration inventory below does not replace or consume those journeys, and overlapping refinements are not counted as independent additions to the 72-case product denominator. Specification publication is not implementation acceptance.

## 1. Executive summary

Verified participants can understand household membership and manage only their permitted data. Administrators review participation and configure existing access policy; each participant controls their own private preferences. HA account identity remains canonical, with verified name when available and an optional inert alias. Existing safeguards, current source checks and explicit user decisions apply in native Ingress and standalone, with English and Spanish presentation.

Verified entry -> current household view -> explicit revision-bound action -> original receipt -> refreshed current state. A lost response retains its original request; a historical receipt does not prove its effects remain present.

## 2. Problem, current behavior, and evidence

The verified development base is 4b71969d3b3f6df5f28d617ab0da4e86c9be5884, the actual PR22 merge. Its tree8953c48ef7f8501b88244ab513c9f3e80fcac7b9 equals reviewed ed7cd14190d750846833cf1bb822988b628560da. The application actually has schema8, identity/task APIs, entry UI, pure member presentation/preferences, fixed recurrence execution and relative storage/creation. It lacks this administration workspace and profile persistence. Unfinished recurrence remains in issue23.

Baseline evidence: 4,031 backend executions, 137 authored modules, 100% supported statement/branch coverage globally and per module; current product CI and both actual image architectures pass. These measurements establish the baseline only. Owner Edge.5 remains a separate schema7 package; no update is performed by this document. The selected development source contains the owning specifications even though bootstrap master has none.

The original administration owner has 57,838 UTF-8 bytes, blob f315a00d9efbb7da8a9ea44de8a9df2d088e100a and SHA256333791e5664212473dd8874be9751c00c8ee7644cf9f861f11a3876dd97321f3. Its existing cases and decisions are retained rather than reproduced. Prospective integration is not an as-built reconstruction, and library/provider feasibility is not claimed merely from the specification.

## 3. Actors, surfaces, and terminology

The participant edits their own alias/preferences within current grants. A current household administrator manages participation, allowed settings/profiles/mapping and public aliases, while never reading or editing another person's private preferences. The operator uses existing installation recovery and compatible restoration. A technical receipt proves original processing, not present effects or authority. Provider names, aliases and avatars are inert display data, never identity, HTML, commands or new grants.

## 4. Goals, non-goals, and fixed invariants

| Requirement | Behavior |
|---|---|
| HADI-01 | Integrate public presentation and alias behavior while preserving the original HADM-01 identity distinction and HADM-03 current-authority contracts. |
| HADI-02 | Integrate bounded honest HA metadata/directory reads and permission-aware roster/detail queries, preserving HADM-01 and HADM-02. |
| HADI-03 | Integrate current-authorized revisioned alias, household/member/profile/mapping commands and original-result disclosure without weakening HADM-03 or HADM-05. |
| HADI-04 | Persist and expose only owner-authorized locale and routine-summary preferences, preserving HADM-04 and all privacy rules. |
| HADI-05 | Add actual schema9 migration/restore compatibility from the verified schema8 chain, preserving HADM-06 and genuine original evidence. |
| HADI-06 | Add the separate closed administration recovery journal and current-context command/query boundaries, preserving HADM-05. |
| HADI-07 | Complete accessible English/Spanish administration in both deployments and the existing catalog/browser workflow, preserving HADM-07. |
| HADI-08 | Maintain tests first, full supported per-module/global coverage, Clean Architecture and truthful documentation/quality evidence, preserving HADM-08 and all 72 original cases. |

These integration requirements trace existing product obligations, not a reduced replacement contract. No gateway, Copilot resource/configuration/credential, production promotion, person-based authentication, arbitrary external image source or notification delivery is added. No automatic mutation/retry, key replacement, stale-dialog rebase or private administrator override is allowed.

## 5. Current versus proposed product journey

Current entry establishes identity and setup/join state but has no full administration screen. The workspace will show masked current roster, pending review, permitted household/access forms and owner-private preferences. Each change is an explicit current-authorized action. Pending membership remains pending until an administrator acts. Alias/name collisions cannot merge canonical HA users. When source metadata is unavailable, show an honest neutral fallback instead of fabricated empty facts.

## 6. Functional behavior and state model

Retain every original state/transition and bound. Mutations require fresh proof, current local/source authorization, expected aggregate revision, CSRF, Origin/context and the persisted original key/payload. Recheck mutable local grants inside the writer after any external preparation. Original recovery GETs retain their existing current-context and original-action disclosure contract; do not impose mutation-only requirements on them.

Keep pending, active, suspended and archived membership behavior, inherited permission provenance, protected permissions and last-effective-administrator safeguards. A participant and current administrator may edit a public alias; only its owner may read/write locale and routine-summary preference. Alias/pref revisions never confer identity or permission. Existing commands remain the authority for household/member/profile/mapping changes.

Saving routine-summary preference is storage only: delivery stays explicitly unavailable until its actual owning consumer exists. Cancel before send may discard a draft; after send it cannot negate an effect. On lost response preserve uncertainty and recover the same operation, with no replacement or automatic resubmission. After restore, report original historical processing separately from absent current effects.

## 7. User-facing configuration

Keep original defaults: nullable alias; nullable locale following browser language with English fallback; strict routine-summary boolean true. Alias is null or trimmed 1..80 Unicode code points, rejects Cc before trimming and preserves literal text without HTML/Unicode normalization. Locale is null, en or es. Household name/timezone and member/profile/mapping limits, including at most256 ordinary decisions and verified directory results, remain unchanged.

The administration journal is separate namespace/version1, at most8 records and65,536 bytes total, one-hour retention. It stores original key/payload/context/lifecycle facts without CSRF, token, cookie or raw provider state. No delivery address/channel, arbitrary settings object or image URL becomes configurable. Unknown/boolean-alias/numeric encodings fail safely without silently changing the original request.

## 8. Clean Architecture design

Pure domain values and identity policies remain independent of provider, HTTP, browser and SQLite. Application commands/queries use semantic ports and shared atomic command infrastructure. Adapters own bounded HA data translation, strict persistence and browser journal codecs. Composition owns deployment credentials and actual runtime wiring; entrypoints adapt closed DTOs/current context without selecting a principal or duplicating business decisions. Presentation renders states and inert strings without inferring authority.

Use independent public presentation and private preference projections with explicit revisions. Their storage representation may be selected during implementation, but must retain scoped identity, honest legacy defaults, atomic migration and safe corrupt-record refusal. Current identity rows/permissions and all task/recurrence/history facts stay authoritative. Shared permission and original-action checks must remain explicit for each new operation; an unknown action cannot acquire generic recovery authority.

## 9. UI/UX and content contract

Both deployments expose the same current roster, pending review, public profile/alias, permitted access/settings and own preferences. Show status, effect and next human action before collapsed technical details. Keep unavailable source, denied, stale, uncertain, historical-absent and saved states distinct. Preserve original accessible labels, keyboard/focus recovery, screen-reader status, responsive reflow and light/dark contrast.

English and Spanish use owner-private explicit locale first, otherwise browser base language, then English. No participant text becomes executable markup, mention, URL or command. Source name/avatar absence is honest; arbitrary remote images and uploads are excluded. Routine preference explains unavailable delivery. No routine application message or notification is emitted by this workspace.

## 10. Failure, recovery, and cleanup

Stale revision or changed permission/source blocks new effects and preserves the draft for refresh and a new human decision. An uncertain request retains its original journal record for protected lookup/replay with the same key. No automatic mutation, rebase or replacement is allowed. Expiry/logout handling preserves committed server facts and avoids deleting unrelated host storage.

Migration or late-write failure rolls back data, defaults, version, receipt/audit/outbox together. Restoring historical state preserves later processed originals and never recreates their missing effects or delivery. Keep compatible complete application/database/generation rollback and explicit operator recovery. Clean owned terminal test/build trees only after retaining necessary failures, exact source/runtime evidence and current rollback; preserve genuine source inputs and pending authored integration.

## 11. Security, permissions, and privacy

All queries and mutations recheck current context and relevant authority. Explicit own-scoped preference checks precede administrator/profile grants, including original receipts, audit UI, events and roster. Store no private preference contents in shared audit/outbox/logging. A protected owner-only result may disclose only to the current original authorized owner. Labels, browser state, alias/name/avatar and request keys cannot grant access.

Provider lookup is bounded and source-verified; a denied/unavailable/malformed source is not an empty verified directory. Existing HA revocation checks, protected role constraints, current mapping proofs and last-administrator recovery remain. Browser recovery is an untrusted closed record with exact bounds; no credentials or command principal is accepted from it. Preserve both entry and administration schemas and their separate scopes.

## 12. Observability and operational UX

Use sanitized outcome/correlation/operation identifiers and aggregate revisions, with no private preferences or credentials. Report user impact, cause, action and retained state. Distinguish metadata unavailability from failed migration/contract checks. CI evidence names actual source, runtime, suite and limits. Green tooling or a published SDD does not prove browser/provider/deployment support or full product delivery.

## 13. Compatibility, migration, rollout, and rollback

Actual schema8 is merged at the stated base; this continuation owns9 next. Preserve supported1..8 source inputs and original fixtures, IDs, HA links, roles/status/mappings/setup provenance, tasks/materials/recurrence, current/retained originals and generation fences. Add nullable legacy presentation and explicit owner-private defaults without inventing HA names. All new fields/records validate on normal use and independent checkpoint inspection.

A genuine schema8 input from ed7 was captured before9 DDL using actual fixed execution and relative creation, with all137 source modules byte-verified: raw SHA256badd63184fa40380462ab3fe54cd957b63a967d1beafb4b73fc6c2475df8340b; complete logical dump SHA256041615f0253c0537ac6c713e10a8984fb5043b1f6df29a6a2c7193824ebc6ed5. Keep original header pragmas and matching installation identity. Never relabel a new fixture as old or claim upgrade by changing a version marker.

Both actual image architectures and persistent runtimes require real upgrade/refusal/restore and compatible rollback evidence. Owner Edge.5/schema7 remains a separate immutable control. No HA update, image promotion, release/tag, extra port or deployment is authorized by publication. Remaining recurrence issue23 must use the next actually merged schema after9 for later DDL.

## 14. Testing strategy and numeric budget

All72 original administration cases and owning identity/delivery cases remain required. The eight integration refinements below are separately specified observable checks, not a replacement inventory or a claim of80 independent product journeys. Counts are requirements, never executed results. First-party supported coverage stays100% globally and per module, with strict typing and import/cycle/privacy negatives from the first implemented change.

{{SDD_CASE_BUDGET}}

| Case ID | Area | Requirements | Scenario |
|---|---|---|---|
| household-admin-integration-C01 | Domain/configuration/pure planning | HADI-01 | Two canonical HA members with the same label and an explicit alias remain distinct, with pure defaults and literal bounded alias validation. |
| household-admin-integration-C02 | Adapters/provider contracts | HADI-02 | A bounded verified directory lookup distinguishes source failure from confirmed omission and never fabricates name/avatar or selector facts. |
| household-admin-integration-C03 | State/application/idempotency/races | HADI-03 | Independent writers or permission loss during external preparation produce one authorized revision/original result and no partial alias/access effect. |
| household-admin-integration-C04 | Application use cases | HADI-04 | Owner preference change and protected original recovery remain denied to another participant or administrator, with no private shared audit/event leakage. |
| household-admin-integration-C05 | Workflows/permissions/schemas/setup | HADI-05 | Genuine schema8 state migrates atomically to9 and a failing addition preserves source/defaults/version and recurrence/original evidence. |
| household-admin-integration-C06 | Security/abuse | HADI-06 | Corrupt, stale, cross-context or wrong-namespace administration journal input cannot replace a key, disclose another owner or widen the entry contract. |
| household-admin-integration-C07 | Presentation/localization/accessibility/sanitization | HADI-07 | Real Python/SQLite English and Spanish browser journeys render permitted roster/forms and private preferences with keyboard, responsive and inert-text states. |
| household-admin-integration-C08 | Integration/end-to-end/compatibility/migration | HADI-08 | Both actual current-source images and owned runtimes preserve schema9 upgrade/refusal/restoration and exact original results with full supported coverage. |

## 15. Documentation and discoverability

| Path | Change |
|---|---|
| specs/household-administration-integration.md | create |
| specs/household-administration.md | reference |
| specs/household-identity.md | reference |
| specs/delivery-quality.md | reference |
| specs/catalog.json | update |
| specs/CATALOG.md | update |
| backend/src/domus/domain/member_profiles.py | reference |
| backend/src/domus/application/ports.py | update |
| backend/src/domus/application/identity_ports.py | update |
| backend/src/domus/application/member_profile_ports.py | create |
| backend/src/domus/application/member_profile_commands.py | create |
| backend/src/domus/application/household_administration_queries.py | create |
| backend/src/domus/infrastructure/sqlite.py | update |
| backend/src/domus/infrastructure/sqlite_identity.py | update |
| backend/src/domus/infrastructure/sqlite_member_profiles.py | create |
| backend/src/domus/infrastructure/sqlite_member_profile_schema.py | create |
| backend/src/domus/infrastructure/sqlite_snapshots.py | update |
| backend/src/domus/infrastructure/ha_member_profiles.py | create |
| backend/src/domus/entrypoints/administration_http.py | create |
| backend/src/domus/entrypoints/administration_dto.py | create |
| backend/src/domus/composition/household_administration.py | create |
| frontend/src/domain/administration.ts | create |
| frontend/src/application/administration-controller.ts | create |
| frontend/src/adapters/administration-http.ts | create |
| frontend/src/adapters/administration-journal.ts | create |
| frontend/src/presentation/domus-administration.ts | create |
| frontend/src/presentation/messages.ts | update |
| tests/backend/test_sqlite_member_profiles.py | create |
| tests/backend/test_member_profile_commands.py | create |
| tests/backend/test_household_administration_queries.py | create |
| tests/backend/test_ha_member_profiles.py | create |
| tests/backend/test_administration_http.py | create |
| tests/fixtures/sqlite/v8.sql | create |
| tests/fixtures/schema8-app/Dockerfile | create |
| tests/containers/test_administration_image.py | create |
| .github/workflows/ci_check.yml | update |
| docs/household-administration.md | create |
| docs/household-administration-operations.md | create |
| docs/household-administration-migration.md | create |
| docs/architecture-household-administration.md | update |
| docs/evidence/household-administration.json | update |

These are proposed actual integration paths at the selected immutable base. Declare further actual paths before committing them. Reference paths are existing sources, not created deliverables. User/setup/operator/contributor docs must match real commands, bounds, states, provider support and migration evidence; validate links/examples and never turn proposed behavior into passing evidence.

## 16. Acceptance

All original acceptance statements remain mandatory. Require the full current-authorized household workspace and privacy in both deployments, actual schema9 compatibility from the selected schema8 chain, separate original-request recovery, honest unavailable metadata/delivery and all original72 journeys. Prove source/runtime/browser/provider/HA claims at their actual scope. No green subset, pure model or publication alone completes this continuation or the full product.

## 17. Requirements traceability

{{SDD_REQUIREMENT_CASES}}

Integration requirements preserve original HADM-01 through HADM-08 by reference. The original document retains every full case row and reciprocal mapping; this companion neither copies its inventory nor changes its denominator. Additional layered checks may refine those journeys but cannot be represented as independent accepted product cases merely by execution count.

## 18. Implementation sequence

Verify the Action-published base/SDD/ref. Begin tests for actual profile/default persistence and genuine8 migration to9, then current-authorized alias/private preference commands and protected queries/recovery. Add verified metadata adapters, closed native/standalone HTTP and safe browser journal. Complete EN/ES screens, Storybook, real SQLite Playwright and both actual images/HA evidence. Keep all 72 journeys and existing owners in scope throughout; merge only verified work without unresolved Bugbot findings, preserving unfinished scope explicitly if the owner requests a checkpoint.

## 19. Definition of Done

All retained scope, cases, source/privacy/recovery and migration contracts are implemented and actually verified, with 100% supported global/per-module coverage, types, architecture, package/browser/image checks and truthful user/operator docs. No unresolved finding or unspecified owner decision remains. Actual deployment acceptance is separate from source publication. The Action owns remote admission and lifecycle; do not create replacement refs or modify Copilot/gateway to pass a gate.

## 20. References and decisions

Owning sources are `specs/household-administration.md`, `specs/household-identity.md` and `specs/delivery-quality.md`. Existing optional alias editing, private preferences, actual schema8 then9 ordering and no-delivery claims remain unchanged. The new companion is a bounded recovery after two terminal update-size failures and a closed requirement-mapping failure, not permission to narrow scope, relax the original SDK or claim implementation. Report real Copilot defects upstream and continue authorized work through its normal branch/SDD workflow.