Integrate bounded environmental Reasoning adapters

Summary

ALYT supports a bounded environmental Reasoning flow for developers who need an explicit input/output contract around context-aware decisions. The runner uses opaque ALYT references, a goal, bounded query and reference history, and fixed limits. It does not receive execution credentials or native device identity. You retrieve current physical context through the existing Tenant context reader, then validate decisions through the zero-effect A1 proposal endpoint. The negotiated alyt.reasoning-graph-input/1.1.0 keeps the input/output contract unchanged; it may correlate declared-goal findings against the supplied selectedDeclaredGoalId and record revision while the typed target remains UNKNOWN, and the legacy 1.0 and frozen qualified contracts retain their original behavior. If the contract cannot be satisfied, the turn returns UNAVAILABLE with a clear reason rather than falling back to another path.

Negotiate the private structured runner boundary

Use the authenticated semantic shadow controller and its receipt-bearing input0.2 path only with the same original admission, current actor, placement, cancellation, and Tenant companion reads. It keeps the original pin, shorter lifetime, two actual tool reads, failed-only retry origin, and non-authoritative per-step findings; it does not write state or claim physical execution.

Use the existing private runner tokenize/reason operations with alyt.reasoning-semantic-input/draft-0.1.0 or explicit receipt-bearing alyt.reasoning-semantic-input/draft-0.2.0 only under an exact verified REASONING manifest and installed adapter whose contextVersion is alyt.reasoning-semantics/draft-0.1.0. The configured ALYT runner client also requires the operator binding’s interfaceVersion to equal the input version; it refuses mismatches before network access. The installed fake worker now also accepts the same semantic request shape through its private semantic tokenize/reason RPC path. Native load/tokenize/reason retain their pinned executable/argv hashes, original request/reply identities and owned-process cancellation. No automatic ABI upgrade or default substitution occurs. The legacy interactive shadow route refuses a semantic placement and preserves its original request/result contract.

The shared inference slot, original companion expiry and24/32/16KiB context/request/reply budgets remain enforced, together with the original 2-call/4-step safety limits. Results preserve non-authoritative findings, exact supplied evidence and goal revisions, and two separately scoped queries. Duplicate query refs, used refs, expired reads and retries without a FAILED/TIMED_OUT prior attempt are refused. The current event adapter only returns proposals from the original ledger as PENDING_APPROVAL; it does not dispatch. These checks do not execute tools, write memory, confirm physical results or authorize a proposal. Disable the selected companion binding or unload its role for rollback; keep the accepted legacy manifest and ordinary platform paths unchanged.

Use the authenticated semantic shadow controller for developer

POST /internal/physical-ai/reasoning/semantic-shadow accepts the existing alyt.reasoning-request/draft-0.1.0 body from the authenticated ordinary household actor plus internal service identity. The default-empty Reasoning shadow cohort, independent companion-read cohort, and exact trusted receipt-input0.2 binding remain required. The legacy shadow endpoint keeps its ABI and shared admission, rate, owned-turn cancellation, and metrics, and adds no executor. The semantic route is /internal/physical-ai/reasoning/semantic-shadow, with the authenticated ordinary actor/internal key boundary preserved.

The controller obtains canonical context and projection from the authenticated Tenant reasoning-context owner and rechecks original actor, source, companion, binding/key, current placement/egress consent, and shorter original context/projection lifetime around tokenization, decode, tool reads, and release. Existing 0.1 request, new 0.1 result, and explicit 0.2 runner contracts stay in force. Two independent scoped reads retain their original query refs, kind, selected refs, expiry, and failed-only retry origin. STATE/HISTORY, CAPABILITIES, POLICY, ROUTINE, OUTCOME, and SPATIAL preserve source availability and actual distinct tool results/statuses; FAILED/TIMED_OUT/EXPIRED carry no invented result, NO_DATA preserves the actual bounded empty/unknown source result, and per-step findings are non-authoritative with no memory writes. The strict alyt.reasoning-semantic-result/draft-0.1.0 reports bounded step findings, intent/A1 validation, unavailability, counts, and deadline-limited completion. The exact admitted escalation owner remains the existing minimized/current-consent owner, and rollback is by disabling the binding/cohort or restoring the prior accepted runner pair. Actual limits remain 24KiB combined context, 32KiB request, 16KiB response, 4KiB history, 4096/1024 tokens, two reads, four steps, and 30-second absolute deadline; original unauthorized service identity is 403. NO_DATA remains supported.

Read source-bound structured context

POST /internal/physical-ai/properties/:propertyId/reasoning-context?tenantId=... with the existing alyt.context-query/draft-0.1.0 body and cursor:null from the trusted ALYT adapter. The internal service identity and original current ordinary household actor, or an explicit verified HOUSEHOLD_DEVICE authority under the existing Owner-granted household-voice authority, are required; application API keys and model text cannot supply either boundary. PHYSICAL_AI_REASONING_CONTEXT_PROPERTY_IDS is an independent default-empty cohort. Existing context reads and strict runner0.1 operation remain independently supported.

The strict alyt.reasoning-context/draft-0.1.0 result contains canonical context and its pinned alyt.reasoning-semantics/draft-0.1.0 projection. ALYT rechecks current session, membership, source revision and original context expiry before release; no refresh or expiry renewal occurs. The combined context/companion is at most24KiB. Pagination and an oversized combination are refused, never silently trimmed. Choose a bounded goal-relevant context query and preserve omissions.

The runner boundary checks do not execute tools: RPC validates query shape, scope, identity and lifetime only. Typed context reader remains the separate authenticated source, and the original interactive shadow remains legacy and refuses companion placement.

Entity categories come from ALYT’s existing brand-independent thing mapping. Location revisions are opaque hashes of the actual source’s kind/identity/room assignment; they are equality pins, not ordered epochs or native integer revisions. Original observation boot identities, decimal sequences, clocks, age and evidence stay in canonical context. Never hash or lexically sort a boot cookie into an epoch.

Only explicit active owned draft0.2 memory declarations produce typed goals, rebound to current opaque entity/control/room/routine refs and exact record revisions. Raw descriptor units such as % or °C are retained exactly; the model adapter must perform reviewed native-unit mapping or refuse, without implicit conversion. Dependencies retain their declared ORDER/OBSERVED_COMPLETION meaning; record revision is not a retained-intent revision. An omitted/out-of-view declaration, legacy text goal or missing dependency yields TRUNCATED goal availability. Unavailable memory yields UNKNOWN. Neither is a known-empty complete collection.

Absent authoritative policy/consent, ledger outcome, relation/guard, WAN/external availability and retained-intent producers remain explicitly UNKNOWN/null. Writable descriptors and ordinary read access grant no execution authority. The companion’s executionAuthority is false. Interpretation, findings, ACK, SATISFIED claims and a successful read cannot confirm a physical outcome. Use the deterministic validator, current permissions, executor and outcome ledger.

Obtaining this read response does not negotiate a runner ABI. Preserve the configured runner’s exact declared contract; never send semantic input to an old strict runner0.1 consumer. Native projection/formatter/token counting, reversible references and complete pinned IPC belong to the adapter boundary. Unknown/unrepresentable location/order/unit/range/causal/selector facts are refused.

Fake/pinned native test executable evidence proves plumbing only and does not establish model quality, readiness or physical effect.

Workflow

A Reasoning turn follows a strict sequence:

1. Provide opaque ALYT refs, the goal, bounded query/reference history, and the requested limits.
2. Retrieve the current bounded physical context through the existing Tenant context reader.
3. Run the bounded Reasoning request with read-only context access.
4. Validate the decision through the zero-effect A1 proposal endpoint.
5. Accept UNAVAILABLE when the budget, version, model, cancellation state, or consent/binding checks do not hold.

The runner never sees authenticated ordinary actor claims, tenant or property scope, execution credentials, or native device identity. Those remain outside model input.

Contract boundaries

The explicit internal Reasoning entry uses ALYT-owned draft request, input, reply, and result contracts. The supported modes are:

• QUERY, which binds the supplied context and revision and permits only bounded read tools.
• DECISION, which binds the supplied context and re-enters A1.
• UNAVAILABLE, which abstains with an explicit budget, version, model, or cancellation reason.
• SHADOW, which always states zero physical effects and no execution authority.

A new owned turn cancels its prior invocation. Cancellation, deadlines, and current consent or binding are rechecked around tokenization, inference, tools, and validation. Crashes, hostile or invalid output, stale context, and exhausted budgets do not invoke a dispatcher or provider fallback.

Limits

These are defensive contract ceilings, not measured performance:

Limit	Value
Occupied calls	2
Admissions per minute	12
Steps	4
Context tools	2
Time limit	30s
Input tokens	4096
Output tokens	1024
Request bytes	32768
Reply bytes	16384
Context bytes	24576
History bytes	4096

No truncation or silent budget increase is allowed. Configured tokenization must return the pinned actual tokenizer revision. The fake four-byte tokenization behavior belongs only to the deterministic test adapter.

What you can use

Use the bounded physical context through the existing Tenant context reader. Use only bounded read tools in QUERY. Use A1 for zero-effect proposal validation in DECISION. The runner receives bounded query and reference history, but not execution authority.

Local functions can keep working during a cloud outage. Cloud-dependent connectors require the provider and network; do not expect them to work when the cloud path is unavailable.

Permission and scope notes

Access boundaries matter only where they affect the turn:

• Household permissions are narrower than staff permissions.
• DEV credentials act in the developer sandbox.
• LIVE credentials apply only to the developer’s own installed connector.

Do not assume broader actor claims or tenant scope than the request already carries, and do not try to pass those claims into the Reasoning entry.

Related behavior

The existing G3 home-agent subscriber stays separate. It keeps its authenticated projection, private goal scope, persisted at-most-once work, and injected EnvironmentShadowRunner. Do not add another subscriber or treat ordinary actor claims as part of this flow.

Existing metrics export bounded counts and a 64-duration window without context or actor/home labels. Voice and chat behavior remain independent of this Reasoning path.

Practical result

For developers, the useful pattern is: collect bounded context, submit a constrained Reasoning turn, and validate the outcome through A1. If the turn cannot stay within limits or context binding, return UNAVAILABLE rather than expanding scope. The result remains bounded, auditable, and effect-free unless a separate approved path performs an actual action.

Read retained physical history

The verified ALYT retained-history path keeps the original internal service authentication, current actor, and context pin for POST /internal/physical-ai/properties/:propertyId/reasoning-history?tenantId=.... The query uses the exact physicalAiReasoningSemanticQuery fields with kind HISTORY, 1–4 current entity/control refs, maxEvents up to 16, maxNodes up to 4, positive historyWindowMs up to 30000, and the original expiresAt/retryOf; no schemaVersion field is present. The window is anchored to the original context createdAt and does not renew expiry.

The existing EnvironmentEvent journal is the source of record, scoped by tenant/home/current native bindings, with at most 64 records plus one overflow sentinel. Recorded journal entries are not latest state. Current inventory, actor, source, and expiry are checked before release. Missing records are returned as actual empty rows; recorded gaps, malformed records, unknown physical occurrence times, or overflow yield TRUNCATED. Exceeding maxEvents or 24KiB refuses the read rather than trimming. Findings remain non-authoritative, and receipt0.2 may cite only supplied observations or successful ALYT history receipts. Supported budgets stay two-call/four-step with 4KiB receipt history; rollback uses the accepted runtime and disabled companion binding.

The result is a physicalAiReasoningToolResult with kind HISTORY, not model-generated history or a new state store. Opaque observation refs stay stable in the original snapshot and remain separate from current-state refs; the reference cache is capped at 256 entries. The semantic controller places the typed historical result into receipt-input0.2. When data are missing, the system preserves explicit no-data or gap handling instead of inventing state. Supported budgets remain the original two-call/four-step limit and 4KiB receipt history limit; disabling the selected companion cohort/binding or restoring the accepted runtime provides rollback.

Read current permission, consent and original outcomes

The new flow captures the current household permission or verified device authority, the tenant cloud-inference flag, and the latest tenant.cloud_inference_consent audit record in the same transaction as inventory. ALLOWED now requires both a positive tenant flag and a latest audited enabled=true record; DENIED follows a negative flag or audit, and missing or inconsistent positive proof stays UNKNOWN. This is consent evidence only; it does not become export permission, frontier readiness, or execution authority.

The policy adapter computes proposal eligibility from current control permission, verified device control scope, descriptor bindings, and a representative valid value produced only for validator checking. That metadata proves control-proposal capability, not acceptance of arbitrary values, approval, or execution. It also keeps security mode, external readiness, missing routine proof, and other undeclared facts explicitly UNKNOWN. The shadow cohort remains the only proposal-exposed control surface, and writable permission alone is insufficient.

The outcome reader still requires the home to be selected for outcome rows and remains limited to tenant, property, client, and original actor scope. It reads at most eight effects plus one overflow sentinel and verifies the immutable parent proposal snapshot, effect snapshot, and digest before rebinding only current controls. Correlation handling remains strict: malformed, unmapped, compound, or mismatched correlation is TRUNCATED rather than confirmed. Empty original correlation yields only current proposal lifecycle status, and expiry cannot create AUTHORIZED.

The ledger adapter remains constrained to existing ledger and outcome cohorts and reads only the home selected for those rows. It verifies the original immutable proposal snapshot and digest, then compares each stored effect snapshot to the current rebounded control. It accepts only fresh physical event/command/readback references when they are exact and current; retained, replayed, stale, or replaced observations cannot substitute. Unknown newer manual-change evidence stays null. The adapter also enforces the no-physical-effects rule: it does not execute, reconcile, or modify outcomes, and it preserves zero physical effects and zero execution authority.

Installation-facing checks now align source revisioning with current tenant consent and the verified device or household authority already present in the database snapshot. The service captures the current permission state and latest consent audit record together, then derives a source-pinned environment revision. If the source or consent changes, the original source pin becomes invalid and release must recheck the same actor, source, and shorter original expiry. This keeps old or unknown measurements from being promoted by an event envelope and prevents stale facts from being rewritten into fresh physical history.

The historical field-time repair is preserved: a stale or older physical measurement cannot be made fresh by a newer event envelope. A valid original execution record can supply physical outcome status, but SQL status and transport ACK are not proof of completion.

Overflow handling is bounded: up to eight effects are returned, with a sentinel/overflow condition causing TRUNCATED. Combined results remain under the existing 24KiB budget. Rollback remains default-off, with existing cloud, voice, routines, and device controls continuing their prior behavior.

Updating or creating an ALYT effect ledger record does not change the canonical physical context pin, so it does not self-invalidate approval of an immutable proposal. The canonical source still pins physical inventory and observations, plus the current permission or consent state. Exact own-actor ledger records change the companion policy revision, and the Tenant owner rechecks the complete captured ledger at final release while the semantic controller checks the exact companion. Pending approval metadata keeps its shorter original expiry. Any changed or revoked actor, permission, or physical source still refuses, and there is no new authority, refresh, lifetime extension, or physical send; existing approval, execution, and fence owners remain.

Read proven routine eligibility

The bounded reasoning adapter path now documents that routine references are selected from the canonical context and original bounded graph owner, then filtered through the existing shadow cohort. The environment service reuses the original deterministic graph/installation owner and applies a bounded routineFacts pass only when the current proof, source revision, and selected refs are available. The proof window is strict: expiration cannot exceed the original context, current authority, or positive proof expiry, and the read refuses a stale companion window. The packed graph, version, bytes, protocol, runnable roots, and selected refs remain the proof basis, while the companion revision records graph, proof, installed version, permitted status, and validation result. The service then rechecks current authority and consent, along with the original canonical source and own-actor ledger withholding, before returning eligible refs. When alyt.reasoning-graph-input/1.1.0 is negotiated, the adapter can correlate the declared-goal finding with the supplied selectedDeclaredGoalId and preserved record revision, but the typed target stays unknown and the legacy 1.0 / frozen contracts stay unchanged. Speech Map ABI remains unchanged, and the deterministic approval, fence, execution, and physical-result confirmation owners remain unchanged. No approval or physical execution is produced, and any missing proof remains UNKNOWN or ineligible.

Read durable local typed reasoning context

These changes establish the bounded reasoning companion as an explicit negotiation layered over the existing projection data. The snapshot query keeps its ordinary body and reply, and a client must ask for reasoningSemantics: "alyt.reasoning-semantics/draft-0.1.0" to receive the sealed companion. If a reasoning reply is negotiated but absent or downgraded, the client rejects it. The Linux HomeAgent typed flag is default-off, and PHYSICAL_AI_PROJECTION_REASONING_ENABLED=true requires PHYSICAL_AI_PROJECTION_ENABLED=true; the server also requires its existing projection/read/observation cohorts plus PHYSICAL_AI_REASONING_CONTEXT_PROPERTY_IDS. The graph1.1 path only adds declared-goal finding correlation for the supplied selectedDeclaredGoalId, while typed targets remain unknown and the legacy 1.0 / frozen qualified contracts stay unchanged; this is a claim only, with physicalConfirmation:false.

The internal reasoning-context endpoint now reads from the current local durable snapshot using the original internal key and current enrollment. It returns bounded physical context together with the sealed typed companion, but it grants no execution authority and accepts no snapshot imports or paged queries. The current selected entities and controls scope typed goals, relations, guards, outcomes, and policy. Absent declarations remain UNKNOWN; filtered declared facts become TRUNCATED. The semantics are preserved across restart, replay, scope, and expiry: original context, observation, policy, and companion expiry do not renew through aging or replay, and expired companion reads refuse while ordinary physical reads keep their own valid lease.

Replay and aging now perform invalidation instead of fabrication. Replayed or changed observations remove cached outcome confirmations/readbacks, clear dependent outcome goals, and invalidate matching last-handled observation markers. The result surfaces bounded availability using UNKNOWN versus TRUNCATED, and any stale policy eliminates proposal eligibility. The tenant-facing projection path and the HomeAgent sync client both forward the optional reasoning-semantic request so the sealed companion is only returned when explicitly negotiated, with no new migration, no second database, and no model requirement added.

Identify source-qualified manual overrides

Reread current facts before release and keep manual-change evidence separate from immutable approval pins. Record newerManualChange only when the later differing command is user-issued with valid provenance; service, connector, malformed, or unattributed history remains null. Do not fabricate false absence, and do not infer physical movement from a request. Existing cohort controls and rollback are sufficient, with execution authority unchanged and mutable facts excluded from the original physical approval. No new API, model requirement, SQL, durable store, hub RAM, or execution authority is introduced.

bounded-reasoning-adapters

The frozen alyt.physical-ai-qualified-interface/1.0.0 release keeps the literal draft wire identities as compatibility identities only, with explicit negotiation against the release, immutable schema and fixture pins, and mandatory canonical validation before any export. Current-source ALYT authority governs the adapter behavior: unsupported native facts remain unknown or are refused, only FAILED or TIMED_OUT attempts may be retried, and EXPIRED attempts are refused. Every convenience-mapper result must pass canonical reply validation, the primary-view mapper stays unchanged, and any adapter lacking receipt-aware history mapping must refuse actual history-only evidence. Findings and history do not establish physical confirmation, and bounded reasoning does not imply full native coverage or activation.

Verify source-bound local reads

Local Linux voice reads remain pinned to the original source context, source revision, and finite expiry already present in the existing eight-view cache; current enrollment and shutdown withdrawal are enforced, and only successful SUCCEEDED receipts together with returned source rows count as delivery. A query or tool-attempt counter alone does not establish receipt of evidence, and this read path introduces no physical authority, MCU allocation, or model-selection change; the existing voice selection and default model settings stay unchanged.

Optional source pairing and rollback

Use the paired source/model adapter installation only for the optional private profile. When selecting this optional profile, configure the reviewed pair; existing runner profiles remain valid. It stays default off. Each selection keeps the whole dependency closure: typed goal, guard, routine, bindings, omissions, Speech aliases, the original utterance, and the same context/revision. This Voice profile uses two combined reads, three model calls, and a 19-second deadline. Oversized whole closures refuse, and a successful source read that does not fit the 4 KiB delivery budget fails delivery. Disable the binding to roll back to the original Voice path.

Source facts negotiation and guards

LEGACY requests and replies retain their original shapes; the opt-in path adds source metadata only when negotiated. It keeps descriptor units literal, reports explicit unknown units, and preserves same-hub native guards separately from current controller send-time checks. Same-hub native guards are acceptance conditions on the same recorded hub, while controller checks still inspect current send-time evidence; never treat either as permission, write qualification, or reachability. Every receiver must preserve every proposed guard, and every proposed guard must remain in place; do not remove model guards to make incompatible intent executable. The ledger keeps the original reason, grant deadline, confirmation deadline, and recovery state, and replay preserves the original reason, grant deadline, confirmation deadline, and recovery state for surviving outcomes while invalidated outcomes have their diagnostics removed and only surviving outcomes retain original diagnostics and times. Matched adapter negotiation is exact and default-off, with no extra metadata query. Test changed epoch and map values, expiry, restart, replay, and cancellation with a model-independent adapter. Disable the selected profile and keep one retained rollback; ordinary voice remains unchanged. Two combined reads, three model calls, and 19 seconds stay in place, along with the original standalone native budgets.