Record exact-intent approvals and action identities

ALYT provides private ledger routes that store intent and reviews for bounded, typed action proposals without dispatching device traffic. Use this flow to store intent and reviews for the current household actor in a selected home, then read, approve, revoke, cancel, or replace the resulting record by exact identity. This surface is internal, not a public SDK route, and every receipt remains consent-only: APPROVED does not imply transport, ACK, dispatch, or physical success, and every receipt reports physicalEffects=0 and executionAuthority=false.

Who can call these routes

These routes are for ALYT internal services acting with an ordinary current household session, an explicit tenant, and a selected home.

Two access rules are strict:

• API-key credentials cannot call these routes.
• DEV and LIVE credentials cannot call the ledger.

Models can provide bounded typed intent, but they cannot create the actor, approval, generation, or physical target. DEV credentials continue to act in the developer sandbox on their public routes. LIVE credentials continue to act only for their own installed connector on public routes.

Household access is actor-scoped. Other actors' history is inaccessible. A different current login can still read retained records that belong to that same actor in the same home and may revoke or cancel them later, but it cannot inherit the original approval session.

Submit a proposal

Send ledger-submit/draft-0.1.0 to the internal proposal route with:

• idempotencyKey
• the current A1-qualified intent

Idempotency keys are scoped to actor, session and home. Reuse the same key only for the same actor, session, home, and input. For identical retries, the proposal identity, effect identities, and expiry stay stable across retries and restart. If the input changes within the same scope, the request conflicts. If authorization scope changes, ALYT creates a separate record with separate history and approval.

The ledger stores immutable intent and an immutable snapshot of the qualified effect set. Never mutate stored intent and never reuse approval across effects, homes, properties, or versions.

Read a receipt

Read the actor’s receipt by proposal ID. The receipt includes the proposal identity, request identity, revision, effect digest, status, timestamps, and per-effect status.

Before any review, read the receipt and confirm the exact effect digest and revision you intend to review.

The ledger lifecycle includes pending, APPROVED, revoked, cancelled, superseded, and expired outcomes. APPROVED means recorded consent only.

Review a proposal

To review a proposal, send ledger-mutation/draft-0.1.0 with:

• a fresh requestId
• expectedDigest
• expectedRevision
• a decision of APPROVE, REVOKE, or CANCEL

Duplicate review request IDs cannot change a recorded decision.

Approval is stricter than read access. Approval requires all of the following to still match the original reviewed proposal:

• the original ordinary session
• unchanged current policy
• unchanged targets and descriptors
• unchanged original preconditions
• the full installed routine graph when a routine is involved

Concurrent changes serialize. If another change lands first, a stale review conflicts and you must read the current receipt and review again.

A later revoke or cancel does not grant new authority. A different current login may revoke or cancel its own retained record, but cannot reuse or inherit the original approval.

Replace a proposal

To correct a stored proposal, send ledger-replace/draft-0.1.0 with the exact old digest and revision plus a new ledger-submit payload as the replacement.

Replacement supersedes the old record atomically and creates a fresh unapproved record. The replacement requires its own approval. This is the correction path when the intended effect changes; do not edit an existing stored record in place.

What approval means

Approval records consent and identity only. It does not dispatch commands and it does not grant execution rights.

Every ledger receipt has physicalEffects=0 and executionAuthority=false.

Effects remain disabled until the existing physical owner separately governs authority. Physical outcome records belong to existing command/run/evidence owners. The ledger calls no transport and does not imply ACK, dispatch, or physical success.

Existing manual control, routine, security, voice, and developer connector APIs keep their existing owners and behavior.

Expiry rules

Expiry is fixed from the original proposal context and does not renew on reads, retries, or restart.

Two rules matter most:

• Original proposal expiry is never more than 5 minutes
• Only routine installation proof expires within 90 seconds

Other proposal context, access, and token limits keep their original bounds. If those original bounds become shorter before approval, approval can no longer succeed.

Limits and retention

Limit	Value
Request body	16KiB
Immutable snapshot	32KiB
Each effect	2KiB
Effects per proposal	8
Retained proposals per home	256
Retained proposals per actor/session/home	32
Active operations	8

Additional retention rules:

• on new submission, ALYT may prune up to 32 uncorrelated expired records older than seven days
• records with correlated physical history are preserved for reconciliation
• leased effects and correlated physical history are preserved

Developer workflow

1. Produce the current qualified intent.
2. Submit ledger-submit/draft-0.1.0 with an idempotency key.
3. Read the receipt and record the exact digest and revision.
4. Review it with ledger-mutation/draft-0.1.0 using a fresh review request ID.
5. If the intent must change, replace it with ledger-replace/draft-0.1.0 instead of modifying the stored record.

Use this flow when you need durable exact-intent consent records and stable action identities while leaving execution and physical outcome ownership to the existing ALYT command, run, and evidence surfaces.