RunicToolkit.Hosting.Abstractions 0.1.0-preview.30.1

RunicToolkit.Hosting.Abstractions

RunicToolkit.Hosting.Abstractions contains the dependency-neutral vocabulary shared by the Hosting lifecycle, composition kernel, build tooling, and adapters. The assembly targets the repository's net10.0 policy and references only the BCL plus the frontend-neutral RunicToolkit.Desktop contracts. It does not reference Application Bridge, CommandLine, Microsoft.Extensions Hosting/DI/logging, a native runtime, or external lowercase cs-webui.

The complete declared surface is recorded in PUBLIC-API.md.

Contract groups

• Launch and routing: LaunchDecision, ILaunchIntentResolver, mode runners, route selection, and stable runner-cardinality errors.
• Validation and lifecycle: immutable validation inputs/errors, host and participant seams, stop convergence, states, phases, timeout options, stable failures/results, and exit-code policy.
• Assets: normalized manifest-relative metadata, deterministic manifests, and a manifest/validate/open-only provider seam.
• Browser hosting: validated host/window options, factory/host/window lifetime seams, close signaling, dispatcher-affine asynchronous work, and an optional desktop adapter seam without native handles.
• Observability: ordered sanitized lifecycle events and a non-owning sink boundary; the kernel queues delivery so sink latency and failures are isolated from lifecycle work.

All concrete implementations must preserve explicit registration. These contracts do not authorize runtime assembly discovery or dynamic activation.

Deterministic and security guarantees

Contract data snapshots consumer-owned collections where ownership crosses into Hosting. Asset paths are normalized to forward-slash application-relative paths and reject rooted, drive-qualified, empty, current-directory, parent-directory, query, fragment, colon, control-character, encoded-separator, and encoded-traversal forms. Media types reject control characters. SHA-256 values are exactly 64 hexadecimal characters and normalize to lowercase. Compressed variants must be distinct from their source and from each other.

Browser application/window identifiers accept only ASCII letters, digits, periods, hyphens, and underscores. Window titles reject empty values and control characters; window dimensions must be positive. Browser interfaces expose neither a native handle nor an implementation-specific runtime type. Close callbacks are signaling boundaries, not application-logic execution contexts.

Stable validation/failure messages and lifecycle events do not echo launch arguments, exception messages, asset content, native payloads, or authorization data.

Diagnostic allocation

The Hosting family owns RTKHOST0001-RTKHOST9999. Wave A/B allocates the following exact identities; shared registry changes remain an orchestrator handoff:

Exceptions may be retained in-process on ApplicationFailure, but their messages are not promoted to stable diagnostics or lifecycle events.

Lifecycle event allocation

The Hosting family reserves event IDs 11000-11999. Wave B allocates:

Sequences and timestamps are assigned by the Hosting kernel, not event constructors. Consumers may construct the immutable records for testing, but must not infer global ordering across application instances from their per-kernel sequence values. A failure event retains only an exact RTKHOST plus four-ASCII-digit code; foreign or malformed codes become null.

Frozen lifecycle decisions

• One immutable lifecycle selects exactly one LaunchKind and mode runner.
• Validation completes before host startup. Composition validation checks decision shape, non-Invalid route cardinality, common validators, then selected-mode validators; an invalid launch requires no runner.
• Startup is phase-then-registration order. Only completed participants stop, in reverse completion order.
• The first terminal non-success result or failure remains primary. A later teardown failure can replace success, but cannot replace an earlier non-zero result/failure.
• Competing stop sources converge on one request and completion; disposal is idempotent.
• Every bounded wait and event timestamp uses an injected TimeProvider; aggregate startup and shutdown deadlines cap individual waits.

Dependency manifest and Wave C boundary

RunicToolkit.Hosting.Abstractions depends only on the authored RunicToolkit.Desktop contract package. Its remaining shipping-project lock entries are SDK-supplied ILLink build tooling. The runtime kernel and deterministic manifest builder depend inward on it; generator/build tooling is not a runtime dependency of this assembly.

Integration packages supply the Generic Host, Application Bridge/root-session, WebUi/external cs-webui, CommandLine, structured logging, and runtime asset-provider implementations. No concrete adapter type belongs in this package, and lower-level Application Bridge/CommandLine/native packages must not reference Hosting abstractions merely to participate in Hosting; their adapter packages translate into these seams.