✨🧑‍💻 - Complete household administration APIs and workspace over verified schema9 profile storage #25

# Household administration workspace

- Status: Draft
- Date: 2026-11-02
- Catalog capability ID: household-identity (companion)
- Owners: Domus maintainers
- Scope: Complete the already specified administration application, protected API and workspace on actual merged schema9.
- Related issue: https://github.com/vypdev/domus/issues/25
- Open decisions blocking readiness: None; implementation and acceptance remain outstanding.

This companion retains all HADM-01..HADM-08 requirements and all 72 original household-admin cases in `specs/household-administration.md`, all identity/delivery requirements, and the eight HADI integration refinements in `specs/household-administration-integration.md`. They remain authoritative and unchanged. The eight refinements below are separately counted integration checks, not 80 independent product journeys. Publication and checkpoint closure are not implementation acceptance.

## 1. Executive summary

Complete the verified household administration workspace in native HA Ingress and standalone deployments. Participants manage their own public alias and private preferences; administrators manage permitted household, membership, existing profiles and mappings. Canonical HA identity, current authority, original operation evidence and honest source facts remain authoritative. The same accessible English/Spanish behavior is required in both deployments.

## 2. Problem, current behavior, and evidence

PR24 merged at `6d84d4815a8bbfe071979df6650d01e433dcc2db`, with a tree independently verified equal to reviewed head `4e59e04d956668c76f3c8d48e824059fd205d661`. Source schema is9. Separate public/private profile repositories, independent revisions, atomic member defaults, strict persistence and supported schema1..8 upgrades are implemented. New administration commands, protected profile HTTP, HA presentation metadata, the separate journal and complete workspace remain absent.

The storage checkpoint has 4,105 backend executions and 100% supported statement/branch coverage globally and per each of140 modules. Product CI41460987862 and both real CPU images passed; native41460987851 completed4/4 partitions with complete context and no open findings. This is baseline evidence, not acceptance of these proposed behaviors or the72 journeys. Source23-file specification inventory and existing catalogs are on the selected development commit; bootstrap master is not that source.

Existing architecture/owner documents and `docs/household-administration-migration.md` identify the actual immutable source8 input and compatibility evidence. Do not transcribe or invent evidence hashes. External provider feasibility is unknown until actual supported source behavior is verified. No owner HA update, current release or new DDL is implied.

## 3. Actors, surfaces, and terminology

| Actor | Goal | Surface |
|---|---|---|
| Verified participant | Review current identity/access; manage permitted own alias/preferences | Ingress or standalone workspace |
| Current household administrator | Review membership and manage permitted household/profile/mapping state | Current-authorized administration forms |
| Operator | Inspect original processing, restoration and compatible rollback | Existing owned-storage tools and documentation |

Canonical HA user ID establishes identity. Display name, alias and avatar are inert presentation. Locale and routine-summary choice are owner-private. An original receipt records original processing, not current grants or effects. Technical outbox delivery is not notification delivery.

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

| Requirement | Behavior |
|---|---|
| HADW-01 | Add currently authorized public alias commands/queries with independent revision and immutable original operation semantics. |
| HADW-02 | Add owner-only preference commands/queries and original-result disclosure, without shared private-value/fingerprint leakage or notification claims. |
| HADW-03 | Translate bounded verified HA presentation/directory facts, keeping denied, unavailable and confirmed absence distinct. |
| HADW-04 | Integrate existing household/member/profile/mapping use cases and last-administrator safeguards into explicit authorized forms. |
| HADW-05 | Add closed administration HTTP/journal/transport contracts, exact revisions and context/lifecycle fencing without widening entry recovery. |
| HADW-06 | Complete accessible responsive EN/ES administration, inert rendering and both deployment/browser journeys. |
| HADW-07 | Preserve actual schema9, original schema1..8 inputs, task/recurrence state, operation history, restoration and compatible runtime rollback. |
| HADW-08 | Complete retained-case traceability, tests-first Clean Architecture, full supported coverage, applicable CI/images and truthful documentation. |

Non-goals: no gateway or Copilot modification, arbitrary remote images/uploads, person-based authentication, notification delivery, new household policy or DDL, release/tag/HA rollout, or acceptance of recurrence/calendar issue23. No requirement or original case is removed. Current authority precedes every effect and disclosure, including replay. No automatic mutation retry, key replacement or stale-dialog rebase is allowed. Private preferences remain owner-only even for administrators.

## 5. Current versus proposed product journey

| Stage | Current | Proposed |
|---|---|---|
| Entry | Verified setup/join entry exists | Open current-authorized household workspace |
| Review | Partial identity APIs and stored profiles | Masked roster, honest metadata, own private preferences and permitted forms |
| Change | Integrated profile/preferences behavior absent | Explicit revision-bound action with current proof and original key/payload |
| Recover | Existing original-operation owners remain | Separate bounded administration journal and protected original result |

```mermaid
flowchart LR
    A[Verified entry] --> B[Current access and permitted facts]
    B --> C[Explicit revision-bound form]
    C --> D[Authorized atomic operation]
    D --> E[Original receipt and refreshed current state]
```

Text equivalent: verified entry -> current access/facts -> explicit form -> authorized atomic operation -> original receipt and current-state refresh.

## 6. Functional behavior and state model

1. Derive principal, installation, household and current context from the trusted existing session boundary.
2. Read permitted local state; obtain bounded provider facts outside SQLite locks and recheck mutable local grants afterward.
3. Expose public roster/presentation and only the current owner's private preferences. Distinct accounts with identical labels remain separate.
4. A human confirms a closed mutation. Check current proof, local grants, CSRF/Origin/context, exact expected revision and immutable original key/payload.
5. Commit effect, original result and safe audit/event facts atomically. Replay reauthorizes before disclosing an original result.
6. Refresh current state. A historical receipt after restore never recreates an absent effect or implies delivery.

| State | Meaning | Permitted transition/action |
|---|---|---|
| Current | Current context and permitted facts loaded | Edit permitted form or refresh |
| Draft | Human changes are unsaved | Explicit submit or cancel |
| Submitted | Original request sent; result not yet known | Await result or explicit recovery |
| Uncertain | Original outcome not confirmed | Look up same original request; no replacement/resend |
| Saved | Original operation processed | Refresh current state; distinguish historical absence |
| Blocked/unavailable | Current source, permission or revision insufficient | Retain safe draft, explain cause and refresh after human action |

Pending, active, suspended and archived membership retain existing owner-defined transitions. Ordinary activation defaults to restricted and requires explicit confirmation. Alias editing does not activate membership or change private state. A late response from a retired context cannot replace a newly verified view. Logout/BFCache dispose retired resources and hide private facts while preserving original recovery records and unrelated host storage.

## 7. User-facing configuration

| Input | Default | Bound and meaning |
|---|---|---|
| Alias | null; verified HA name if available | null or trimmed1..80 Unicode codepoints; valid UTF8; reject Cc before trimming; literal text; null alone clears |
| Locale | null | null/en/es; explicit owner choice wins, otherwise browser base then English |
| Routine summary | true | strict boolean; stored preference only, notification delivery unavailable |
| Administration journal | empty | separate namespace/version1;8 records;65536totalbytes;onehour; original immutable intent/context/lifecycle |
| Revisions | current aggregate revision | exact integer1..2^63-1; independent presentation/preferences; no unsafe numeric rounding |
| Roster/directory | actual permitted/source facts | at most256 members; incomplete/oversized source fails honestly |

Existing household name/timezone, ordinary profile/exception bounds and mapping inputs remain unchanged. No arbitrary settings object, credentials, delivery endpoint or remote image URL is added. Recommended alias/locale null with summaries true does not invent HA metadata or send messages. Example alternative: own Spanish locale, a literal alias and false summaries; identity/permissions are unchanged.

## 8. Clean Architecture design

| Boundary | Owns | Excludes |
|---|---|---|
| Domain | Pure values, bounds and presentation distinction | HTTP, HA SDK, SQLite, browser |
| Application | Commands/queries, current authority, original-action guards and semantic ports | Concrete transport/storage or DOM orchestration |
| Adapters/infrastructure | Strict provider/persistence/HTTP codecs and deployment wiring | Product permission decisions or browser-selected principal |
| Presentation | Accessible localized view models and inert rendering | Durable mutation or authorization policy |

Entrypoints -> application -> pure domain/ports; provider and SQLite adapters implement ports; view models feed UI. Reuse existing identity/member/policy/recovery use cases rather than duplicating them. Obtain provider proof outside writer locks and recheck local grants inside the writer. Current authority and original payload checks precede original result disclosure. Whitelist each new original action; unknown actions remain denied. Semantic private reads select the owner from current authority, never a request-supplied identity. A private original result may be owner-readable; shared audit/outbox/logs must omit private contents and inferable payload/result fingerprints.

Existing executable import/dependency checks must stay acyclic and inward. Add semantic DTO/journal/capability guards and exact revision transport checks. Storage ports do not authorize callers. No SQLite table or field addition is required by this continuation.

## 9. UI/UX and content contract

Show current status, established facts, next transition and human action before collapsed technical details. Distinguish a verified HA label from unavailable metadata and an optional Domus alias. Show masked linkage/permission provenance consistently. When directory facts are unavailable, remove unsupported target selectors and explain the remaining supported actions without fabricated options.

Representative states: current roster with no action required; pending member needing explicit administrator review; stale/denied save with no new effect and retained safe draft; uncertain original operation needing lookup; saved alias/preferences followed by refreshed current state; historical processed operation whose effect is absent. Preference success explicitly says saved with notification delivery unavailable, regardless of technical event acknowledgement.

Support English and Spanish, explicit owner locale and browser/English fallback. Preserve same-context unsaved drafts across language changes without saving them. Provide visible labels/focus, keyboard submission/error focus, status announcements, logical headings, readable360px reflow, light/dark contrast and reduced motion. User/provider text never becomes HTML, Markdown link, mention, command or URL. No arbitrary external image request is allowed. Both Ingress and standalone require real Python/SQLite browser journeys and the established Storybook workflow.

## 10. Failure, recovery, and cleanup

| Failure | Retained state | Recovery/action |
|---|---|---|
| Stale revision or lost authority | Current server state and safe local draft; no new effect | Explicit refresh and new human decision |
| Provider denied/unavailable/malformed | Actual roster identity and honest source status | Bounded read retry; never fabricated empty success |
| Lost/unreadable response | Exact original request/key/context | Protected lookup; no automatic mutation or replacement |
| Restore | Original processing proof and current-effect distinction | Inspect current state before requesting new work |
| Retired/logout context | Original bounded journal; no active private view | Reverify before rendering/recovering; do not delete unrelated storage |

Use impact -> cause -> action -> retained state. Expire only owned browser records under the closed journal policy. Retain authored inputs, original evidence, pending work and the current compatible rollback; clean only terminal owned build/test outputs.

## 11. Security, permissions, and privacy

Current HA proof and local grants govern writes and replays; current verified query context governs reads. Owner-only preference checks precede administrator/profile grants, including receipts, logs and projections. Public alias edits are restricted to the owner with applicable current permission or a current administrator. Last-effective-administrator/source checks remain existing authority. Exact numeric/DTO parsing rejects unsupported aliases/encodings before coercion. An operation ID, journal, display string, forwarded name or technical transport credential cannot select a principal, widen recovery or grant authority. Never persist credentials, CSRF, cookies or raw provider state in the administration journal.

## 12. Observability and operational UX

Expose saved/stale/denied/unavailable/uncertain/historical-absent states with actionable content. Sanitized operation/revision/context evidence supports diagnosis without private values or raw provider detail. Keep technical event dispatch distinct from notification delivery and original processing distinct from current effects. Record actual test/source/runtime and incomplete acceptance honestly. Unchanged tooling output or a merged checkpoint does not prove the72 journeys.

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

Use actual merged schema9. Preserve supported immutable schema1..8 inputs and existing task/recurrence definitions, source/cursors, original operations/history, restoration and generation fences. No relabeling, new schema number or fabricated migration chain is allowed. Existing both-CPU upgrade/refusal/current-runtime restore evidence remains a baseline; complete all applicable runtime and compatible full application/data/generation rollback acceptance without inferring broader guarantees from narrow tests. Owner Edge.5/schema7 and rollback remain unchanged. Release, tags, promotion and HA adoption are separate work; unfinished recurrence/calendar remains issue23 and any later real DDL uses the next genuinely merged schema.

## 14. Testing strategy and numeric budget

Retain all72 original administration cases, the owning identity/delivery inventories and all eight HADI refinements. They are retained owners, not new rows in this budget. These eight additional refinements do not replace them or claim eight additional independent product journeys.

| Area | Minimum distinct cases | Behaviors/risks covered |
|---|---:|---|
| Domain/configuration/pure planning | 1 | Pure public/private scope and exact alias/revision values |
| State/application/idempotency/races | 1 | Current-owner preference original-result privacy and concurrent atomic writes |
| Adapters/provider contracts | 1 | Bounded verified facts versus denial/unavailability/absence |
| Application use cases | 1 | Existing administrator safeguards and explicit form actions |
| Security/abuse | 1 | Closed context-bound journal/HTTP and original request fencing |
| Presentation/localization/accessibility/sanitization | 1 | Actual EN/ES responsive keyboard and inert-content states |
| Integration/end-to-end/compatibility/migration | 1 | Actual both-runtime/image history/restore compatibility |
| Workflows/permissions/schemas/setup | 1 | Full traceability, quality evidence and original owners preserved |
| Total | 8 | Distinct integration inventory; repeated executions do not add cases |

| Case ID | Area | Requirements | Scenario |
|---|---|---|---|
| household-workspace-C01 | Domain/configuration/pure planning | HADW-01 | Alias remains inert/scoped with exact revisions and cannot change identity or private state; own/admin authority is explicit. |
| household-workspace-C02 | State/application/idempotency/races | HADW-02 | Current owner alone can save/read/recover original preferences; authority loss/concurrent writes/restore preserve one result without shared private leakage. |
| household-workspace-C03 | Adapters/provider contracts | HADW-03 | Bounded verified source yields honest display/directory facts while denial, outage, malformed input and confirmed omission cannot fabricate identity or selectors. |
| household-workspace-C04 | Application use cases | HADW-04 | Explicit pending activation and settings/profile/mapping changes reuse current source and last-administrator guards with no silent privilege change. |
| household-workspace-C05 | Security/abuse | HADW-05 | Unknown fields/actions, inexact numbers, cross-owner/context or forged/expired journal cannot select a principal, disclose originals or replace/resend a request. |
| household-workspace-C06 | Presentation/localization/accessibility/sanitization | HADW-06 | Real EN/ES native/standalone browser views preserve exact drafts/recovery, keyboard/focus, narrow/dark layouts and inert metadata with truthful status. |
| household-workspace-C07 | Integration/end-to-end/compatibility/migration | HADW-07 | Actual both-CPU/runtime controls preserve schema9, original operation/recurrence state and supported restore/rollback without false old-image compatibility. |
| household-workspace-C08 | Workflows/permissions/schemas/setup | HADW-08 | Every retained case maps to actual evidence; Clean Architecture, full supported per-module/global coverage, applicable CI and discoverable docs remain required. |

Tests precede behavior. Require100% supported statements/branches globally and per authored module; complete new pure-policy branches. Use deterministic clocks/IDs/fakes, actual SQLite, current permission/replay/race/privacy controls, semantic HTTP/journal/capability tests and browser assertions. Every PR CI Check runs all applicable suites and both real CPU images. Meet the retained manual UX review contract; agent dogfooding, provider fixtures and owner evidence must remain distinguishable. No case here is claimed executed.

## 15. Documentation and discoverability

| Path | Change |
|---|---|
| `specs/household-administration-workspace.md` | create |
| `specs/household-administration.md` | reference |
| `specs/household-administration-integration.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` | update |
| `backend/src/domus/application/member_profile_ports.py` | update |
| `backend/src/domus/application/member_profile_access.py` | create |
| `backend/src/domus/application/member_profile_commands.py` | create |
| `backend/src/domus/application/household_administration_queries.py` | create |
| `backend/src/domus/application/household_queries.py` | update |
| `backend/src/domus/infrastructure/ha_member_profiles.py` | create |
| `backend/src/domus/infrastructure/ha_websocket.py` | update |
| `backend/src/domus/entrypoints/administration_http.py` | create |
| `backend/src/domus/entrypoints/administration_dto.py` | create |
| `backend/src/domus/composition/household_administration.py` | create |
| `backend/src/domus/composition/ingress.py` | update |
| `backend/src/domus/composition/server.py` | update |
| `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 |
| `frontend/src/composition/entry-runtime.ts` | update |
| `frontend/stories/administration.stories.ts` | create |
| `frontend/tests/administration.test.ts` | create |
| `frontend/tests/e2e/administration.spec.ts` | 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/containers/test_administration_image.py` | update |
| `.github/workflows/ci_check.yml` | update |
| `docs/household-administration.md` | create |
| `docs/household-administration-operations.md` | create |
| `docs/architecture-household-administration.md` | update |
| `docs/household-administration-migration.md` | update |
| `docs/evidence/household-administration.json` | update |

These are proposed paths, not claims that a file/API/provider/library capability exists. Declare any additional actual path before implementing it. Keep user/default, setup/permission, operator/recovery, contributor/architecture and migration/compatibility guidance discoverable; verify links/examples against actual behavior.

## 16. Acceptance scenarios

1. Given current permitted context, an alias changes only public presentation, while identical labels do not merge HA accounts.
2. Given own preferences and original receipt, another member or administrator cannot disclose/edit them through any new or existing path.
3. Given unavailable provider facts, the roster retains actual canonical membership with honest unavailable presentation and no fabricated selector.
4. Given stale authority/revision or an unknown original action, a request has no unauthorized effect or original-result disclosure.
5. Given a lost response or retired context, recovery retains the exact original request without automatic resend, replacement or late private view.
6. Given both deployments and EN/ES preferences, actual browser journeys satisfy the complete retained inventory and manual UX requirements.
7. Given actual images/runtime and restore controls, existing schema9/history/recurrence and compatible rollback are preserved with correctly scoped evidence.

## 17. Requirements traceability

| Requirement | Cases |
|---|---|
| HADW-01 | household-workspace-C01 |
| HADW-02 | household-workspace-C02 |
| HADW-03 | household-workspace-C03 |
| HADW-04 | household-workspace-C04 |
| HADW-05 | household-workspace-C05 |
| HADW-06 | household-workspace-C06 |
| HADW-07 | household-workspace-C07 |
| HADW-08 | household-workspace-C08 |

## 18. Implementation sequence

1. Confirm retained contracts and exact source; implement current-authorized application behavior with failing privacy/replay/race tests first.
2. Wire semantic HA/HTTP/composition boundaries and closed exact-revision/journal contracts with adapter/security tests.
3. Build accessible EN/ES workspace and both-runtime Storybook/real Python/SQLite browser journeys.
4. Complete all retained cases, truthful docs, manual UX, full coverage, actual image/restore/rollback evidence and no-findings review.

## 19. Definition of Done

- [ ] All eight new refinements and every retained owner requirement/case have actual scoped acceptance evidence.
- [ ] Clean Architecture and semantic DTO/journal/permission/source/recovery constraints pass.
- [ ] 100% supported global/per-module statement/branch coverage and all applicable PR/image checks pass.
- [ ] Both deployment EN/ES/browser/accessibility and retained manual UX contracts are satisfied.
- [ ] Privacy, idempotency, races, source failures, restore/rollback and cleanup pass without false delivery claims.
- [ ] Catalogs and documentation are consistent; original pinned SDD format/consistency validation passes.
- [ ] No Copilot/gateway modification, lost owner inventory, invented migration/provider facts or unproven release acceptance.

## 20. References and decisions

Selected source: https://github.com/vypdev/domus/tree/6d84d4815a8bbfe071979df6650d01e433dcc2db . Issue25 continues merged PR24; recurrence/calendar continues in issue23. Existing registered household-identity owner documents and delivery contracts remain authoritative. Use a new unregistered companion `specs/household-administration-workspace.md` after a terminal18,000-character response rejection; do not change Copilot limits or existing owner scope. No product policy remains unresolved. Future source work begins only after native publication and exact Action branch readiness. Publication remains Draft until actual implementation/review supports acceptance.