Integrate governed model suggestions

Use governed model suggestions as a validation step, not as execution. ALYT keeps authority over physical state, permissions, deterministic checks, and evidence. Your model submits bounded intent in alyt.proposal-validation-input/draft-0.1.0, and ALYT evaluates it against the current authorized household context. A successful shadow result is still non-acting: physicalEffects=0, executionAuthority=false, and VALID means the suggestion is acceptable for review, not approved or dispatched.

What this validation does

The shadow validation route accepts a request with:

• schemaVersion
• intent as strict alyt.intent/draft-0.1.0

The intent can reference context, entities, controls, and routines only through opaque references from an ALYT context view. Device names, routine names, and retrieved text are data only. They do not grant identity, permission, or execution authority.

Validation rechecks the current household session, the current home access, and the current descriptor or routine evidence before returning a result. You must use an actor-bound full-home context from ALYT’s existing context reader. A local projection or room-only view does not substitute for that authority.

These are not public SDK routes. They are internal ALYT validation boundaries.

Route and access requirements

The validation endpoint is:

POST /internal/physical-ai/properties/:propertyId/proposals/shadow?tenantId=...

This route requires both:

• an internal ALYT service credential
• a verified ordinary current household session

API-key credentials cannot call this route. Public API credentials do not replace the ordinary household session required at this boundary.

The route is available only for operator-selected homes. If validation is disabled for the home, the route fails closed.

Request and response contracts

Request

The request body must match alyt.proposal-validation-input/draft-0.1.0. Requests are limited to 16KiB.

JSON Schema validation alone is not enough here. ALYT also applies canonical authorization and state checks against the current context.

Response

The response body matches alyt.proposal-validation-result/draft-0.1.0.

A result always has:

• mode SHADOW
• ALYT-issued validationId
• ALYT-issued requestId
• the original context reference
• an expiry
• accepted
• reason
• up to 8 per-effect explanations
• physicalEffects=0
• executionAuthority=false

If accepted, the top-level reason is VALID. If denied, the result still grants nothing. Non-acting dispositions and denied effects never create authority.

Supported suggestion scope

Only a narrow effect family qualifies.

Direct actions

Only light set effects qualify, and only for these keys:

• power
• brightness
• colorTemp
• color

ALYT checks the exact referenced entity and control, writability, resolved constraints, finite type and range rules, step rules, and declared options.

Validation refuses suggestions when targets are unknown, read-only, cross-entity, duplicated, or outside resolved constraints.

Preconditions

Preconditions must still match synchronized original evidence. Fresh or unchanged checks require real synchronized observations. Retained, replayed, null, or unknown evidence is not enough.

Routines

A routine suggestion is only valid when ALYT can prove the installed routine still matches its pinned canonical graph and installation proof.

Validation checks every child and target in the routine. It refuses routines with:

• cycles or dangling dependencies
• dynamic room targets
• cloud-tagged steps
• unsupported conditions
• security, lock, appliance, media, or speech effects
• changed owner, version, or definitions
• missing or stale installation proof

Routine limits are strict:

Limit	Value
Nodes	16
Depth	3
Steps	64
Distinct light writes	1–8
Total wait	30 seconds

The original context expiry also bounds routine validation. The 90-second limit applies to installation proof. Routine installation proof expires within 90 seconds.

Reason vocabulary

The top-level and per-effect reason vocabulary is fixed:

• VALID
• MALFORMED
• EXPIRED
• CONTEXT_CHANGED
• UNKNOWN_REFERENCE
• UNSUPPORTED_FAMILY
• INVALID_VALUE
• PRECONDITION
• DUPLICATE_TARGET
• ROUTINE_UNPROVEN
• ROUTINE_CHANGED
• ROUTINE_CYCLE
• ROUTINE_BUDGET
• DYNAMIC_EFFECT
• UNSUPPORTED_CONDITION
• NO_ACTION
• CLARIFICATION
• ESCALATION

Malformed HTTP requests are rejected before a validation result is returned.

Capacity, expiry, and duplicate handling

ALYT bounds this workflow to prevent unbounded work.

Limit	Value
Request body	16KiB
Active validations	8
Concurrent scopes	128
Rate	30requests per minute per actor/session/home
Cached receipts	up to 128 total
Cached receipts per scope	8
Response body	8KiB
Client timeout	5second

Duplicate validations can reuse the original receipt identity without extending expiry, while still performing fresh access and state checks.

Direct-action receipts expire with original context, at most5minutes.

Failure behavior

Expected HTTP failures are:

Status	Meaning
400	Invalid schema or malformed bounded request
401	Missing service identity or ordinary current session
403	No current home access
404	Validation disabled for the home
409	Context changed or expired, or routine evidence changed
429	Capacity or rate limit reached

The client does not redirect or retry. It uses a strict 5second timeout and an 8KiB response limit.

Execution boundaries

Shadow validation never approves, dispatches, or confirms a physical action. It does not create a command, invoke a routine runner, contact a connector, or call a provider. It cannot fall back to a command or cloud provider path.

That distinction matters for reliability and authority:

• local functions can continue during a cloud outage when they do not depend on cloud services
• cloud connectors require the provider and network
• a successful shadow validation does not imply any later transport path is available

Use this route when you need governed acceptance of model suggestions against current ALYT authority and original bounded context, before any separate review or execution workflow.