Review exact household plans and physical results

Use the ordinary household proposal APIs when you need to inspect exact plans, review or revoke them, make bounded corrections to light values, and read back the original physical outcome. These endpoints work only through the current authenticated household session for the explicitly selected tenant and property. The gateway rechecks session and home membership on each operation, and approval stays separate from execution. API keys and DEV/LIVE do not grant household control, and corrections start unapproved until the current session confirms the change.

Use the current household session

Open the workflow only with an ordinary current session and explicit tenant/property. Actor identity comes from the verified session. API keys and DEV/LIVE do not grant household control. Program or model principals also do not grant household authority, and a model response cannot supply actor identity, permission, physical evidence, or transport identifiers.

The versioned household projection is alyt.household-proposal/draft-0.1.0, and pages use alyt.household-proposals/draft-0.1.0. Keep those versions explicit so they are not confused with private intent, ledger snapshots, or model runner interfaces.

Read availability and original proposals

All read paths use ?tenantId=<tenant UUID> under the existing gateway:

• GET /properties/{propertyId}/proposal-access returns current actor and home availability. readable and reviewEnabled are UI information only and never a physical grant.
• GET /properties/{propertyId}/proposals returns original actor/home plans in pages of at most sixteen. Use the returned after UUID to read the next bounded page.
• GET /properties/{propertyId}/proposals/{proposalId} returns the original version, effect digest, requested actions and dependency IDs, routine installation version, context timing, original expiry, per-effect outcomes, and recovery.

A null contextTiming means the original context age is unavailable. Prepared time is not context capture time. contextCurrent records whether the captured context remains available and valid; advisory approval and execution checks require it. Execution affordances also require current owner readiness and every separate execution, fence, and outcome cohort. They never authorize dispatch.

Device and room names, and plan explanations, are untrusted text. Render them escaped and never execute them. Missing or moved targets are unavailable rather than relabeled from another home’s inventory. Reads can reconcile original evidence, but they never send commands, restore state, or extend an original deadline.

Review, correct, and execute as separate decisions

POST /properties/{propertyId}/proposals/{proposalId}/review accepts alyt.ledger-mutation/draft-0.1.0, a requestId UUID, expectedDigest, expectedRevision, and one of APPROVE, REVOKE, or CANCEL. Approval and execution remain separate, and approval never sends. Reuse the same requestId for the same exact decision after a lost reply.

POST /properties/{propertyId}/proposals/{proposalId}/correct accepts requestId, expectedDigest, expectedRevision, and up to eight distinct changes containing an original effectId and a light value. Original targets, controls, preconditions, and dependencies stay bound by ALYT; callers cannot provide fresh opaque context refs or a new command manifest. The platform captures fresh context and creates a new unapproved record, so corrections start unapproved. A retry returns the original replacement; changed values with that request identity are refused. Once an owner attempt begins, replacement is refused. Saved routine edits use the existing Routines API, and an empty correction refreshes the routine’s current installed plan for a separate review.

POST /properties/{propertyId}/proposals/{proposalId}/execute accepts alyt.execution-request/draft-0.1.0, the original proposalId, expectedDigest, and a stable requestId. Existing outcome, fence, device, and routine owners enforce current policy, home and family cohorts, and finite original authority at actual dispatch. A duplicate or lost reply must not manufacture another attempt, so a lost reply reads original result instead of creating a new one.

Read the physical result honestly

The per-effect result is authoritative. ACK is not physical confirmation, and PARTIAL must preserve each changed, failed, and unknown effect. Late evidence can resolve recovery while an original UNKNOWN remains historical. Brightness zero requires power-off evidence. Cancellation withdraws unsent permission and cannot retract already transmitted commands.

Do not implement compensating restoration over newer operator state. Read the original proposal after timeout or connection failure. Do not enable automatic mutation retries, offline queued execution, or optimistic success. Scope client caches by account, session, tenant, home, proposal, revision, and digest, and discard stale responses after account or home changes. Return to the original read after 409; 429 means finite admission is exhausted. Disabled workflows return 404. Current-session and access denial remain 401 and 403. Read-only rollback retains results while preventing new household review or execution.

What developers can rely on

Use these controls to review exact household plans, decide on the current version, correct direct light values into a fresh unapproved record, and read back the original physical outcome without guessing from cached state. The page preserves exact identity, version, digest, and outcome boundaries, and it does not turn approval into device dispatch.

This workflow respects no private service key or owner lease. It also keeps execution separate from review, so a proposal can be approved without sending anything, corrected into a new unapproved record, or read again after failure without changing the original result.