@kehto/services 0.19.0 → 0.20.1

package/dist/index.d.ts

@@ -1,13 +1,13 @@
 import { ServiceHandler, Signer, RelayEventResult, ServiceRuntimeContext } from '@kehto/runtime';
 import { IdentityGetProfileMessage, IdentityGetProfileResultMessage, IdentityGetFollowsMessage, IdentityGetFollowsResultMessage, IdentityGetListMessage, IdentityGetListResultMessage, IdentityGetZapsMessage, IdentityGetZapsResultMessage, IdentityGetMutesMessage, IdentityGetMutesResultMessage, IdentityGetBlockedMessage, IdentityGetBlockedResultMessage, IdentityGetBadgesMessage, IdentityGetBadgesResultMessage } from '@napplet/nap/identity/types';
-import { NostrFilter, NostrEvent, EventTemplate, IntentRequest, IntentResult, IntentAvailability, IntentBehavior, IntentCandidate, LinkOpenOptions, LinkOpenResult, ListSupport, ListRef, ListItem, ListOptions, ListMutationResult, SerialOpenRequest, SerialOpenResult, BleEvent, BleOpenRequest, BleOpenResult, BleService, BleAttribute, BleWriteOptions, WebrtcEvent, WebrtcOpenRequest, WebrtcOpenResult, CommonProfileTarget, CommonProfileResult, CommonFollowsResult, CommonActionResult, CommonReaction, CommonReportTarget, CommonReportReason } from '@napplet/core';
-export { IntentAvailability, IntentBehavior, IntentCandidate, IntentHandlerPreference, IntentOpenOptions, IntentRequest, IntentResult } from '@napplet/core';
+import { NostrFilter, NostrEvent, EventTemplate, IntentRequest, IntentResult, IntentAvailability, IntentBehavior, IntentCandidate, LinkOpenOptions, LinkOpenResult, ListSupport, ListRef, ListItem, ListOptions, ListMutationResult, SerialEvent, SerialOpenRequest, SerialOpenResult, BleEvent, BleOpenRequest, BleOpenResult, BleService, BleAttribute, BleWriteOptions, WebrtcEvent, WebrtcOpenRequest, WebrtcOpenResult, CommonProfileTarget, CommonProfileResult, CommonFollowsResult, CommonActionResult, CommonReaction, CommonReportTarget, CommonReportReason, DmStatus, DmConversationQuery, DmConversationPage, DmMessageQuery, DmMessagePage, DmSendRequest, DmSendResult, DmSubscribeRequest, DmMessage, DmSubscription, DmOk, DmHexPubkey, FsInfo, FsPickOptions, FsPickResult, FsMetadata, FsDirectoryEntry, FsReadOptions, FsReadResult, FsWriteOptions, FsWriteResult, FsMkdirOptions, FsWatchOptions, FsChange, FsError } from '@napplet/core';
+export { DmConversation, DmConversationPage, DmConversationQuery, DmHexPubkey, DmMessage, DmMessagePage, DmMessageQuery, DmMessageStatus, DmOk, DmPeer, DmSendRequest, DmSendResult, DmStatus, DmSubscribeRequest, DmSubscription, DmTimestamp, IntentAvailability, IntentBehavior, IntentCandidate, IntentHandlerPreference, IntentOpenOptions, IntentRequest, IntentResult } from '@napplet/core';
 import { MediaMetadata, MediaAction } from '@napplet/nap/media/types';
 export { MediaAction } from '@napplet/nap/media/types';
-import { NotifySendMessage } from '@napplet/nap/notify/types';
+import { NotifyActionMessage, NotifyClickedMessage, NotifyDismissedMessage, NotifySendMessage, NotifyChannelRegisterMessage, NotifyControl } from '@napplet/nap/notify/types';
 import { Theme, ThemeChangedMessage } from '@napplet/nap/theme/types';
-import { ConfigSchemaErrorCode, ConfigValues, NappletConfigSchema } from '@napplet/nap/config/types';
-export { a as CvmCloseMessage, b as CvmCloseResultMessage, c as CvmDiscoverMessage, d as CvmDiscoverQuery, e as CvmDiscoverResultMessage, f as CvmEventMessage, g as CvmInboundMessage, h as CvmOutboundMessage, i as CvmRequestMessage, j as CvmRequestOptions, k as CvmRequestResultMessage, l as CvmServer, m as CvmServerRef, n as CvmService, o as CvmServiceOptions, C as CvmTransport, p as CvmTransportError, M as McpContentBlock, q as McpMessage, r as McpTool, s as McpToolResult, t as createCvmService } from './cvm-service-DKIzbiDw.js';
+import { ConfigSchemaErrorCode, NappletConfigSchema, ConfigValues } from '@napplet/nap/config/types';
+export { a as CvmCloseMessage, b as CvmCloseResultMessage, c as CvmDiscoverMessage, d as CvmDiscoverQuery, e as CvmDiscoverResultMessage, f as CvmEventMessage, g as CvmInboundMessage, h as CvmOutboundMessage, i as CvmRequestMessage, j as CvmRequestOptions, k as CvmRequestResultMessage, l as CvmServer, m as CvmServerRef, n as CvmService, o as CvmServiceOptions, C as CvmTransport, p as CvmTransportError, M as McpContentBlock, q as McpMessage, r as McpTool, s as McpToolResult, t as createCvmService } from './cvm-service-t5syG4tU.js';
 
 /**
  * @kehto/services — Shared types for reference service implementations.
@@ -260,11 +260,11 @@ interface RelayPoolServiceOptions {
      * Subscribe to events matching filters. Returns handle with unsubscribe().
      *
      * @param filters - NIP-01 filter objects
-     * @param callback - Receives matching events or 'EOSE'
+     * @param callback - Receives matching events or 'EOSE' plus optional observed relay URLs
      * @param relayUrls - Optional relay URL hints
      * @returns Handle to cancel the subscription
      */
-    subscribe(filters: NostrFilter[], callback: (item: NostrEvent | 'EOSE') => void, relayUrls?: string[]): {
+    subscribe(filters: NostrFilter[], callback: (item: NostrEvent | 'EOSE', observedRelayUrls?: string[]) => void, relayUrls?: string[]): {
         unsubscribe(): void;
     };
     /**
@@ -1014,81 +1014,62 @@ declare function createMediaService(options?: MediaServiceOptions): ServiceHandl
 };
 
 /**
- * notify-service.ts — NIP-5D notify NAP reference service (stub-level).
- *
- * Handles the 5 napplet -> shell request types from `@napplet/nap/notify`:
- *   - `notify.send`                -> `notify.send.result` (shell-assigned id)
- *   - `notify.dismiss`             -> fire-and-forget
- *   - `notify.badge`               -> fire-and-forget
- *   - `notify.channel.register`    -> fire-and-forget
- *   - `notify.permission.request`  -> `notify.permission.result { granted }`
- *
- * Stub-level: no real Notification API calls, no real channel registry.
- * Host apps wire a real backend via
- * `runtime.registerService('notify', realHandler)`.
+ * NAP-NOTIFY reference service.
  *
- * `notify-service.ts` is the canonical `@napplet/nap/notify` NIP-5D path.
- * It lives alongside the direct notification state registry in
- * `notification-service.ts`; neither service interprets an `inc.emit` topic.
- * If the host app registers this service via
- * `runtime.registerService('notify', ...)`, @napplet/nap/notify messages
- * land here.
- *
- * Shell -> napplet push messages (`notify.action`, `notify.clicked`,
- * `notify.dismissed`, `notify.controls`) are not emitted by this stub —
- * they are the host app's responsibility and are deferred to a future plan.
+ * The service owns protocol correlation and per-window lifecycle while a host
+ * backend owns presentation, permission, badges, and channels.
  */
 
-/**
- * Optional configuration for `createNotifyService`.
- *
- * @example
- * ```ts
- * const notify = createNotifyService({
- *   generateId: () => crypto.randomUUID(),
- *   defaultGrant: false,
- *   onSend: (windowId, msg) => console.log(`napplet ${windowId} sent ${msg.title}`),
- * });
- * runtime.registerService('notify', notify);
- * ```
- */
+/** User-interaction events emitted by a host notification presentation. */
+type NotifyInteractionMessage = NotifyActionMessage | NotifyClickedMessage | NotifyDismissedMessage;
+/** Host presentation request for one accepted notification. */
+interface NotifyPresentation {
+    /** Window that requested the notification. */
+    readonly windowId: string;
+    /** Shell-assigned notification identifier. */
+    readonly notificationId: string;
+    /** Original, untrusted notification payload. */
+    readonly message: NotifySendMessage;
+    /** Route a host-side user interaction back to the requesting napplet. */
+    readonly emit: (message: NotifyInteractionMessage) => void;
+}
+/** Host hooks required to turn NAP-NOTIFY messages into observable behavior. */
 interface NotifyServiceOptions {
-    /**
-     * Generate a shell-assigned notification ID for `notify.send.result`.
-     * Default: a monotonically increasing `shell-<n>` counter.
-     */
+    /** Generate a shell-assigned notification identifier. */
     generateId?: () => string;
-    /**
-     * Default permission grant for `notify.permission.request`.
-     * Host apps that want real permission prompts should replace this
-     * service with a real backend via `runtime.registerService`.
-     * Default: `true`.
-     */
-    defaultGrant?: boolean;
-    /**
-     * Called synchronously when a napplet dispatches `notify.send`.
-     * Intended for host-app plumbing (UI toast, logging, etc.) without
-     * requiring a full backend replacement.
-     */
-    onSend?: (windowId: string, payload: NotifySendMessage) => void;
-}
-/**
- * Create a stub-level notify service handler.
- *
- * Answers the 5 napplet->shell request types from `@napplet/nap/notify`.
- * Does NOT implement a real backend (no DOM Notification API, no channel
- * registry, no permission prompt). Host apps replace this via
- * `runtime.registerService('notify', realHandler)` when a real backend is
- * needed.
- *
- * @param options - Optional service configuration (see NotifyServiceOptions)
- * @returns A ServiceHandler to register with the runtime under domain `notify`
+    /** Render or otherwise deliver a notification. Missing backends fail closed. */
+    present?: (presentation: NotifyPresentation) => void | Promise<void>;
+    /** Remove an active notification from host presentation. */
+    dismiss?: (windowId: string, notificationId: string) => void | Promise<void>;
+    /** Display or clear the requesting napplet's badge count. */
+    setBadge?: (windowId: string, count: number) => void | Promise<void>;
+    /** Persist a channel registration in host-owned state. */
+    registerChannel?: (windowId: string, channel: NotifyChannelRegisterMessage) => void | Promise<void>;
+    /** Apply policy or prompt the user for notification permission. */
+    requestPermission?: (windowId: string, channel?: string) => boolean | Promise<boolean>;
+    /** Release host-owned state when the runtime destroys a napplet window. */
+    destroyWindow?: (windowId: string) => void | Promise<void>;
+    /** Notification controls implemented by the host backend. */
+    controls?: readonly NotifyControl[];
+    /** Observe asynchronous fire-and-forget backend failures. */
+    onError?: (error: unknown) => void;
+}
+/**
+ * Create a NAP-NOTIFY service backed by host-owned notification behavior.
+ *
+ * A backendless instance is safe to register for conformance testing: send
+ * requests return an error and permission requests return `granted: false`
+ * instead of manufacturing successful delivery.
+ *
+ * @param options - Host presentation, policy, and lifecycle hooks.
+ * @returns Runtime service handler for the `notify` domain.
  *
  * @example
  * ```ts
- * import { createNotifyService } from '@kehto/services';
- *
- * const notify = createNotifyService();
+ * const notify = createNotifyService({
+ *   present: ({ message }) => showToast(message.title, message.body),
+ *   requestPermission: () => promptUser(),
+ * });
  * runtime.registerService('notify', notify);
  * ```
  */
@@ -1198,6 +1179,19 @@ interface ThemeService {
  */
 declare function createThemeService(options?: ThemeServiceOptions): ThemeService;
 
+/** Result of validating a NAP-CONFIG Core Subset schema. */
+type ConfigSchemaValidation = {
+    ok: true;
+} | {
+    ok: false;
+    code: ConfigSchemaErrorCode;
+    error: string;
+};
+/** Validate the complete bounded NAP-CONFIG Core Subset recursively. */
+declare function validateConfigSchema(schema: unknown): ConfigSchemaValidation;
+/** Apply schema defaults and drop values that do not validate. */
+declare function resolveConfigValues(schema: NappletConfigSchema, values: ConfigValues): ConfigValues;
+
 /**
  * config-service.ts — NAP-CONFIG reference service (9th NAP domain, v1.7 Phase 39).
  *
@@ -1219,44 +1213,29 @@ declare function createThemeService(options?: ThemeServiceOptions): ThemeService
  * (H-07 in PITFALLS.md) — such state belongs in NAP-STORAGE.
  * ──────────────────────────────────────────────────────────────────────────────────
  *
- * Host integration: provide `getValues()` returning the current
- * `ConfigValues` snapshot. Call the returned `publishValues(newValues)`
- * whenever the configuration changes — the service fans the new snapshot
- * out to every napplet that has an active `config.subscribe`.
+ * Host integration: provide `getValues(windowId)` and `saveValues(windowId,
+ * values)` backed by storage scoped to the source window's napplet identity.
+ * The service validates and defaults every snapshot before delivery.
  *
- * Optional: provide `registerSchema` to accept napplet-declared schemas at
- * runtime (the ref impl does a minimal shape check using the Core Subset
- * validator; use `ajv` in host impls that need strict draft-07 conformance).
- * Provide `openSettings` to open a shell-side UI for the napplet (no
- * response envelope — fire-and-forget UI hook).
+ * Provide `openSettings` to render the shell-owned settings UI. Optional
+ * hooks may add host policy around schema acceptance and lifecycle cleanup.
  *
  * @example
  * ```ts
  * import { createConfigService } from '@kehto/services';
  *
- * const configFixtures = { theme: 'dark', density: 'compact', recentSearches: [] };
+ * const configFixtures = new Map<string, ConfigValues>();
  * const config = createConfigService({
- *   getValues: () => ({ ...configFixtures }),
+ *   getValues: (windowId) => ({ ...configFixtures.get(windowId) }),
+ *   saveValues: (windowId, values) => configFixtures.set(windowId, values),
  * });
  * runtime.registerService('config', config.handler);
  *
  * // Later, when shell-side values change:
- * configFixtures.theme = 'light';
- * config.publishValues({ ...configFixtures });
+ * config.publishValues({ theme: 'light' }, 'window-1');
  * ```
  */
 
-/**
- * Shape returned by a successful `registerSchema` result (ok=true) or a
- * rejection (ok=false + code + error). Mirrors the wire envelope fields.
- */
-type ConfigSchemaValidation = {
-    ok: true;
-} | {
-    ok: false;
-    code: ConfigSchemaErrorCode;
-    error: string;
-};
 /**
  * Configuration options for `createConfigService` (options-as-bridge
  * per v1.6 Decision 18).
@@ -1264,8 +1243,9 @@ type ConfigSchemaValidation = {
  * @example
  * ```ts
  * const config = createConfigService({
- *   getValues: () => ({ theme: 'dark', density: 'compact' }),
- *   openSettings: (windowId, section) => showSettingsPanel(windowId, section),
+ *   getValues: (windowId) => loadScopedValues(windowId),
+ *   saveValues: (windowId, values) => saveScopedValues(windowId, values),
+ *   openSettings: (windowId, section, context) => showSettingsPanel(windowId, section, context),
  * });
  * ```
  */
@@ -1275,7 +1255,9 @@ interface ConfigServiceOptions {
      * Called on every `config.get` and at every `config.subscribe` initial push.
      * Implementations should return a fresh object (not a mutable reference).
      */
-    getValues(): ConfigValues;
+    getValues(windowId: string): ConfigValues;
+    /** Persist one shell-validated full snapshot after settings UI commit. */
+    saveValues?: (windowId: string, values: ConfigValues) => void;
     /**
      * Optional: receive notification when a napplet subscribes to config updates.
      * Fire-and-forget — the service tracks the subscription internally regardless.
@@ -1288,9 +1270,9 @@ interface ConfigServiceOptions {
     /**
      * Optional: validate and store a napplet-provided schema.
      *
-     * If omitted, the ref impl runs its own Core Subset check (hand-coded
-     * validator; 30-50 lines) and returns ok/reject. Hosts that need strict
-     * draft-07 conformance should provide an ajv-backed implementation.
+     * The reference implementation always runs its complete bounded Core Subset
+     * validator first. This hook may add host policy such as version acceptance
+     * or durable schema persistence, but cannot weaken protocol validation.
      *
      * Return shape mirrors `config.registerSchema.result` wire envelope
      * (minus the `id` — the dispatch layer correlates).
@@ -1299,10 +1281,21 @@ interface ConfigServiceOptions {
     /**
      * Optional: open the shell-side settings UI for this napplet.
      * Fire-and-forget — no response envelope per the wire spec.
-     * If omitted, `config.openSettings` is silently dropped (D10 allows
-     * the config-demo napplet to function without a settings UI).
+     * If omitted, `config.openSettings` is silently dropped. A conformant host
+     * must supply this hook before advertising the CONFIG domain.
      */
-    openSettings?: (windowId: string, section: string | undefined) => void;
+    openSettings?: (windowId: string, section: string | undefined, context: ConfigSettingsContext) => void;
+    /** Release host-owned transient UI or state for a destroyed window. */
+    onWindowDestroyed?: (windowId: string) => void;
+}
+/** Shell-owned settings state and commit boundary passed to host UI code. */
+interface ConfigSettingsContext {
+    /** Accepted schema for this live napplet window. */
+    readonly schema: NappletConfigSchema;
+    /** Current validated/defaulted values. */
+    readonly values: ConfigValues;
+    /** Validate, persist, and publish a full settings snapshot. */
+    commit(values: ConfigValues): ConfigValues;
 }
 /**
  * NAP-CONFIG reference service bundle — `handler` to register with the
@@ -1319,8 +1312,14 @@ interface ConfigService {
      * push from correlated `config.get` response).
      *
      * @param values - The new configuration snapshot (full object, not a diff)
+     * @param windowId - Optional source window scope. Omit only for a host-wide
+     *   update that should be independently validated for every subscriber.
      */
-    publishValues(values: ConfigValues): void;
+    publishValues(values: ConfigValues, windowId?: string): void;
+    /** Return the accepted schema for one live window, or null. */
+    getSchema(windowId: string): NappletConfigSchema | null;
+    /** Return the current validated/defaulted values for one live window, or null. */
+    getValues(windowId: string): ConfigValues | null;
 }
 /**
  * Create a NAP-CONFIG reference service.
@@ -1348,13 +1347,14 @@ interface ConfigService {
  * import { createConfigService } from '@kehto/services';
  *
  * const config = createConfigService({
- *   getValues: () => ({ theme: 'dark', density: 'compact' }),
- *   openSettings: (windowId, section) => openSettingsUI(section),
+ *   getValues: (windowId) => loadScopedValues(windowId),
+ *   saveValues: (windowId, values) => saveScopedValues(windowId, values),
+ *   openSettings: (windowId, section, context) => openSettingsUI(section, context),
  * });
  * runtime.registerService('config', config.handler);
  *
- * // Push a live update to all subscribers:
- * config.publishValues({ theme: 'light', density: 'compact' });
+ * // Push one externally-originated scoped update:
+ * config.publishValues({ theme: 'light', density: 'compact' }, 'window-1');
  * ```
  */
 declare function createConfigService(options: ConfigServiceOptions): ConfigService;
@@ -1364,8 +1364,7 @@ declare function createConfigService(options: ConfigServiceOptions): ConfigServi
  *
  * Shell-side reference implementation for the canonical NAP-RESOURCE wire
  * protocol (`internal-resource.ts` in @kehto/shell/src/types; kehto-internal
- * model per PROJECT.md Decision #31. Kehto keeps legacy single-fetch fields
- * for existing callers and also emits the current NAP-RESOURCE fields.
+ * model per PROJECT.md Decision #31.
  * Handles:
  *   Inbound:  resource.info, resource.bytes, resource.bytesMany, resource.cancel
  *   Outbound: resource.info.result, resource.info.error,
@@ -1373,22 +1372,18 @@ declare function createConfigService(options: ConfigServiceOptions): ConfigServi
  *             resource.bytesMany.result, resource.bytesMany.error
  *
  * ──────────────────────── SCOPE BOUNDARY (RESOURCE-01) ────────────────────────
- * NAP-RESOURCE is an **authenticated fetch proxy** — read-only, atomic.
- *
- * This service is NOT responsible for:
- *   - Streaming / chunked responses (host-app concern)
- *   - Response caching / conditional requests (host-app concern)
- *   - Upload / POST body construction (NAP-RESOURCE v1.7 is read-only)
- *   - Redirect limits, MIME sniffing, SVG rasterization (host-fetch concern)
- *   - Private-IP blocking, SSRF mitigation (host-provided-fetch responsibility)
- *
- * These belong to the host-app's `fetch` implementation per D7 and
- * SHELL-RESOURCE-POLICY.md (Phase 40 Plan 40-03). Kehto ships a reference
- * service; production hardening is the host app's concern.
+ * NAP-RESOURCE is a runtime-mediated byte resolver — read-only, atomic.
+ *
+ * Kehto owns neutral wire lifecycle, cancellation, result projection, and
+ * policy tooling. The runtime supplies the resolver and decides whether to use
+ * the origin-grant hooks, which schemes to resolve, and which limits to expose.
+ * Advisory `resource.info` scheme disclosure never authorizes or blocks a byte
+ * request.
  * ──────────────────────────────────────────────────────────────────────────────
  *
- * Host integration: provide `fetch`, `isOriginGranted`, `getConnectGrants`,
- * and `resolveIdentity`. ALL FOUR are required from day one (H-03 prevention).
+ * Runtime integration requires only `fetch`. A runtime MAY also install the
+ * optional origin-policy adapter (`isOriginGranted`, `getConnectGrants`, and
+ * `resolveIdentity` together).
  *
  * @example
  * ```ts
@@ -1396,11 +1391,18 @@ declare function createConfigService(options: ConfigServiceOptions): ConfigServi
  *
  * const resourceSvc = createResourceService({
  *   fetch: (url, init) => globalThis.fetch(url, init),
+ * });
+ * runtime.registerService('resource', resourceSvc);
+ * ```
+ *
+ * @example
+ * ```ts
+ * const resourceSvc = createResourceService({
+ *   fetch: (url, init) => runtimeResources.resolve(url, init),
  *   isOriginGranted: (origin, grants) => grants.includes(origin),
  *   getConnectGrants: (dTag, hash) => myOriginGrantStore.getOrigins(dTag, hash),
  *   resolveIdentity: (windowId) => sessionRegistry.getEntryByWindowId(windowId) ?? null,
  * });
- * runtime.registerService('resource', resourceSvc);
  * ```
  */
 
@@ -1428,24 +1430,22 @@ type ResourceInfoProvider = ResourceInfo | ((context: ResourceInfoContext) => Re
 /**
  * Options for `createResourceService` (options-as-bridge per v1.6 Decision 18).
  *
- * ALL FOUR fields are required. The factory throws at construction if any is
- * missing — H-03 prevention: the grants source (`getConnectGrants`) MUST be
- * wired from day one so there is no window where resource requests bypass the
- * grant check.
- *
- * @see PITFALLS.md:228 (H-03) — grants-source coupling must be present at construction
+ * `fetch` is the only required field. Kehto does not select a runtime's scheme
+ * or origin policy. The optional origin-policy fields form one adapter and must
+ * therefore be supplied together when a runtime chooses to use it.
  */
 interface ResourceServiceOptions {
     /**
-     * Host-supplied fetch implementation. Receives the URL, a partial init
-     * (method, headers, signal), and must return a `Response`-compatible promise.
+     * Runtime-supplied resource resolver. Receives the requested URL and returns
+     * a byte-classified `Response`.
      *
-     * The host's `fetch` is the ONLY place to implement redirect limits, MIME
-     * sniffing, SVG rasterization, private-IP / SSRF blocking, etc.
-     * This service does NOT filter: it proxies transparently.
+     * The runtime owns scheme dispatch and every NAP-RESOURCE policy decision.
+     * The returned `content-type` must describe the runtime-classified bytes, not
+     * an untrusted upstream header. Throw `ResourceServiceError` to preserve a
+     * canonical protocol error classification.
      *
      * @param url - The URL from the resource.bytes request
-     * @param init - Method, headers (from napplet), and an AbortSignal
+     * @param init - Read-only method and request-scoped AbortSignal
      */
     fetch(url: string, init: {
         method?: string;
@@ -1455,6 +1455,8 @@ interface ResourceServiceOptions {
     /**
      * Returns true if `origin` is present in `grants` (the list returned by
      * `getConnectGrants` for the napplet's dTag + aggregateHash).
+     * Optional: when omitted with `getConnectGrants`, Kehto delegates directly
+     * to the runtime resolver without an origin-grant decision.
      *
      * The reference implementation is simply `grants.includes(origin)`. Host apps
      * may provide normalized-origin comparison if needed.
@@ -1462,21 +1464,19 @@ interface ResourceServiceOptions {
      * @param origin - Parsed origin of the requested URL (scheme + host + port)
      * @param grants - Readonly list from getConnectGrants for this napplet identity
      */
-    isOriginGranted(origin: string, grants: readonly string[]): boolean;
+    isOriginGranted?(origin: string, grants: readonly string[]): boolean;
     /**
      * Returns the list of allowed fetch origins for the given napplet identity.
      * Called on every `resource.bytes` request — must be synchronous and fast.
+     * Optional and paired with `isOriginGranted` plus `resolveIdentity`.
      *
      * Host-supplied grant source (e.g. a static per-dTag allowlist map, or any
      * other host-controlled policy). Returns an empty array to deny all origins.
      *
-     * H-03 prevention: REQUIRED from day one — factory throws on construction
-     * if omitted.
-     *
      * @param dTag - The napplet's d-tag (from session registry)
      * @param aggregateHash - The napplet's aggregate hash (from session registry)
      */
-    getConnectGrants(dTag: string, aggregateHash: string): readonly string[];
+    getConnectGrants?(dTag: string, aggregateHash: string): readonly string[];
     /**
      * Resolve a windowId to the napplet's identity (dTag + aggregateHash).
      * Returns null if the window is not in the session registry.
@@ -1485,7 +1485,7 @@ interface ResourceServiceOptions {
      *
      * @param windowId - The iframe window identifier
      */
-    resolveIdentity(windowId: string): {
+    resolveIdentity?(windowId: string): {
         dTag: string;
         aggregateHash: string;
     } | null;
@@ -1493,8 +1493,8 @@ interface ResourceServiceOptions {
      * Advisory NAP-RESOURCE introspection exposed through `resource.info`.
      *
      * Provide a static snapshot or a resolver when the shell wants to disclose
-     * configured schemes and coarse limits. Omit to expose the reference
-     * service's conservative default (`https` enabled, no numeric limits).
+     * configured schemes and coarse limits. Scheme disclosure is advisory and is
+     * never used as fetch authorization. Omit to disclose no schemes or limits.
      */
     resourceInfo?: ResourceInfoProvider;
 }
@@ -1503,6 +1503,16 @@ interface ResourceServiceOptions {
  * Exported for host apps that need to type-annotate the handler reference.
  */
 type ResourceService = ServiceHandler;
+type ResourceErrorCode = 'invalid-request' | 'not-found' | 'blocked-by-policy' | 'timeout' | 'too-large' | 'unsupported-scheme' | 'decode-failed' | 'network-error' | 'quota-exceeded';
+/** A runtime resolver failure with a stable NAP-RESOURCE error classification. */
+declare class ResourceServiceError extends Error {
+    readonly code: ResourceErrorCode;
+    /**
+     * @param code - Canonical NAP-RESOURCE error code.
+     * @param message - Diagnostic detail safe to return to the napplet.
+     */
+    constructor(code: ResourceErrorCode, message: string);
+}
 /**
  * Create a NAP-RESOURCE reference service.
  *
@@ -1510,15 +1520,14 @@ type ResourceService = ServiceHandler;
  * `resource.bytes`, `resource.bytesMany`, `resource.cancel`, and their
  * result/error envelopes.
  *
- * On-construction guard (H-03 prevention): all four options are validated at
- * factory call time. If any is missing, the factory throws immediately with a
- * message containing `[RESOURCE-01 / H-03]` so misconfigured shell apps fail
- * loudly at startup rather than silently at first dispatch.
+ * The runtime resolver is validated at construction. Runtime implementers may
+ * additionally install the origin-grant adapter; Kehto provides and enforces
+ * the hook contract without selecting the grants or requiring that policy.
  *
  * Returns a `ServiceHandler` (no `publishValues`-style surface — resource has
  * no shell-initiated push beyond the response/error path).
  *
- * @param options - REQUIRED: fetch, isOriginGranted, getConnectGrants, resolveIdentity
+ * @param options - Runtime resolver plus optional runtime-owned policy helpers
  * @returns ServiceHandler to register via `runtime.registerService('resource', handler)`
  *
  * @example
@@ -1526,7 +1535,7 @@ type ResourceService = ServiceHandler;
  * import { createResourceService } from '@kehto/services';
  *
  * const svc = createResourceService({
- *   fetch: (url, init) => globalThis.fetch(url, init),
+ *   fetch: (url, init) => runtimeResources.resolve(url, init),
  *   isOriginGranted: (origin, grants) => grants.includes(origin),
  *   getConnectGrants: (dTag, hash) => myOriginGrantStore.getOrigins(dTag, hash),
  *   resolveIdentity: (windowId) => sessionRegistry.getEntryByWindowId(windowId) ?? null,
@@ -2445,6 +2454,8 @@ declare function createListsService(options?: ListsServiceOptions): ServiceHandl
 interface SerialServiceContext {
     /** Window id of the requesting napplet. */
     windowId: string;
+    /** Emit a runtime-owned serial event back to the requesting napplet. */
+    emit(event: SerialEvent): void;
 }
 /** Options for {@link createSerialService}. */
 interface SerialServiceOptions {
@@ -2575,94 +2586,14 @@ interface CommonServiceOptions {
  */
 declare function createCommonService(options?: CommonServiceOptions): ServiceHandler;
 
-/** Hex Nostr public key. */
-type DmHexPubkey = string;
-/** Unix timestamp in seconds. */
-type DmTimestamp = number;
-/** Current runtime direct-message availability. */
-interface DmStatus {
-    available: boolean;
-    ownerPubkey?: DmHexPubkey;
-    implementations: string[];
-    capabilities: string[];
-}
-/** Query parameters for normalized DM conversation summaries. */
-interface DmConversationQuery {
-    cursor?: string;
-    limit?: number;
-}
-/** Public peer metadata safe for napplet display. */
-interface DmPeer {
-    pubkey: DmHexPubkey;
-    label?: string;
-    avatar?: string;
-}
-/** A normalized direct or group conversation summary. */
-interface DmConversation {
-    id: string;
-    kind: 'direct' | 'group';
-    participants: DmPeer[];
-    subject?: string;
-    unread: number;
-    updatedAt?: DmTimestamp;
-}
-/** Page of normalized conversation summaries. */
-interface DmConversationPage {
-    conversations: DmConversation[];
-    cursor?: string;
-}
-/** Query parameters for message history within one conversation. */
-interface DmMessageQuery {
-    conversationId: string;
-    cursor?: string;
-    limit?: number;
-}
-/** Runtime-normalized delivery state for a DM message. */
-type DmMessageStatus = 'sent' | 'delivered' | 'received' | 'failed';
-/** Normalized cleartext message visible to the napplet by runtime policy. */
-interface DmMessage {
-    id: string;
-    conversationId: string;
-    senderPubkey: DmHexPubkey;
-    createdAt: DmTimestamp;
-    content: string;
-    status: DmMessageStatus;
-}
-/** Page of normalized messages for one conversation. */
-interface DmMessagePage {
-    messages: DmMessage[];
-    cursor?: string;
-}
-/** Request to send a direct message. */
-interface DmSendRequest {
-    conversationId?: string;
-    recipients: DmHexPubkey[];
-    content: string;
-    clientMessageId?: string;
-}
-/** Result of a runtime-mediated send. */
-interface DmSendResult {
-    ok: boolean;
-    message: DmMessage;
-}
-/** Request to start live DM delivery. */
-interface DmSubscribeRequest {
-    conversationId?: string;
-}
-/** Runtime-assigned live subscription identity. */
-interface DmSubscription {
-    subscriptionId: string;
-}
-/** Generic boolean acknowledgement used by `dm.unsubscribe`. */
-interface DmOk {
-    ok: boolean;
-}
 /** Relay pool contract for DM adapters. */
 interface DmRelayPool {
     subscribe(filters: NostrFilter[], callback: (item: NostrEvent | 'EOSE') => void, relayUrls?: string[]): {
         unsubscribe(): void;
     };
     publish(event: NostrEvent): void | Promise<void>;
+    /** Query persisted encrypted messages before serving normalized history. */
+    query?(filters: NostrFilter[], relayUrls?: string[]): Promise<NostrEvent[]>;
     selectRelayTier(filters: NostrFilter[]): string[];
     isAvailable(): boolean;
 }
@@ -2730,6 +2661,8 @@ interface Nip17DmAdapterOptions {
     relays?: string[];
     /** Optional normalized message store. Defaults to an in-memory store. */
     store?: DmMemoryStore;
+    /** Runtime policy invoked once before encrypted relay publication. */
+    authorizeSend?(request: DmSendRequest): boolean | Promise<boolean>;
 }
 /**
  * Create a concrete NIP-17 NAP-DM adapter.
@@ -2860,4 +2793,60 @@ declare function createCordnRelayCoordinatorClient(options: CordnRelayCoordinato
 /** Create a Cordn/ContextVM-backed NAP-DM adapter. */
 declare function createCordnDmAdapter(options: CordnDmAdapterOptions): DmAdapter;
 
-export { type BleServiceContext, type BleServiceOptions, type CacheServiceOptions, type CatalogIntentResolver, type CatalogIntentResolverOptions, type CommonServiceContext, type CommonServiceOptions, type ConfigSchemaValidation, type ConfigService, type ConfigServiceOptions, type CoordinatedRelayOptions, type CordnCodecResult, type CordnCoordinatorClient, type CordnCoordinatorSubscription, type CordnDmAdapterOptions, type CordnDmClient, type CordnGroupMessage, type CordnRelayCoordinatorOptions, type CountRequest, type CountResult, type CountServiceOptions, type DmAdapter, type DmConversation, type DmConversationPage, type DmConversationQuery, type DmHexPubkey, DmMemoryStore, type DmMessage, type DmMessagePage, type DmMessageQuery, type DmMessageStatus, type DmOk, type DmPeer, type DmRelayPool, type DmSendRequest, type DmSendResult, type DmService, type DmServiceOptions, type DmStatus, type DmSubscribeRequest, type DmSubscription, type DmTimestamp, type HostCacheBridge, type HostKeyEvent, type HostKeysBridge, type HostMediaBridge, type HttpUploaderOptions, type HttpUploaderRails, type IdentityServiceOptions, type IntentArchetypeSupport, type IntentCatalogEntry, type IntentDispatchParams, type IntentResolver, type IntentResolverContext, type IntentServiceOptions, type IntentTargetController, type IntentTargetDispatch, type KeysServiceOptions, type LinkOpenContext, type LinkServiceOptions, type ListsServiceContext, type ListsServiceOptions, type ManifestArchetypeInput, type MaybePromise, type MediaMetadataLike, type MediaPlaybackOwner, type MediaServiceOptions, type MediaSessionCreateOptions, type MediaSessionTarget, type MediaSourceRef, type NdrDmAdapterOptions, type NdrRelayTransport, type NdrRelayTransportOptions, type NdrRumorLike, type NdrRuntimeLike, type Nip17DmAdapterOptions, type NostrTag, type Notification, type NotificationServiceOptions, type NotifyServiceOptions, type OutboxEventOptions, type OutboxEventResult, type OutboxPublishOptions, type OutboxPublishResult, type OutboxQueryOptions, type OutboxQueryStream, type OutboxQueryStreamSink, type OutboxRelayPlan, type OutboxRelayPool, type OutboxResult, type OutboxRouter, type OutboxRouterSubscription, type OutboxServiceOptions, type OutboxSubscribeOptions, type OutboxSubscriptionSink, type OutboxTarget, type RailServerConfig, type RelayListEntry, type RelayPoolOutboxRouterOptions, type RelayPoolServiceOptions, type ResourceInfo, type ResourceInfoContext, type ResourceInfoProvider, type ResourceSchemeInfo, type ResourceService, type ResourceServiceOptions, type SerialServiceContext, type SerialServiceOptions, type SignEvent, type StreamingOutboxRouter, type ThemeService, type ThemeServiceOptions, type UploadDimensions, type UploadInfo, type UploadInfoContext, type UploadInfoProvider, type UploadRail, type UploadRailInfo, type UploadRequest, type UploadResult, type UploadServiceOptions, type UploadState, type UploadStatus, type Uploader, type UploaderContext, type WebrtcServiceContext, type WebrtcServiceOptions, createBleService, createBrowserMediaBridge, createCacheService, createCatalogIntentResolver, createCommonService, createConfigService, createCoordinatedRelay, createCordnDmAdapter, createCordnRelayCoordinatorClient, createCountService, createDmService, createHttpUploader, createIdentityService, createIntentService, createKeysService, createLinkService, createListsService, createMediaService, createNdrDmAdapter, createNdrRelayTransport, createNip17DmAdapter, createNotificationService, createNotifyService, createOutboxService, createRelayPoolOutboxRouter, createRelayPoolService, createResourceService, createSerialService, createThemeService, createUploadService, createWebrtcService, manifestToIntentCatalogEntry };
+/**
+ * NAP-FS service boundary for runtime-owned virtual filesystems.
+ *
+ * The service owns wire correlation and per-window watch identity. Backends own
+ * virtual-path policy, authorization, persistence, picker mediation, and I/O.
+ */
+
+/** Change details emitted by a backend before the service adds its scoped watch id. */
+type FsBackendChange = Omit<FsChange, 'watchId'>;
+/** Active backend watch handle. */
+interface FsBackendWatch {
+    /** Stop the backing watch. Must be idempotent. */
+    close(): void | Promise<void>;
+}
+/** Filesystem operations supplied to the NAP-FS service. */
+interface FsBackend {
+    info(windowId: string): FsInfo | Promise<FsInfo>;
+    pickFile(windowId: string, options?: FsPickOptions): FsPickResult | Promise<FsPickResult>;
+    pickFiles(windowId: string, options?: FsPickOptions): FsPickResult | Promise<FsPickResult>;
+    pickDirectory(windowId: string, options?: FsPickOptions): FsPickResult | Promise<FsPickResult>;
+    pickSaveFile(windowId: string, options?: FsPickOptions): FsPickResult | Promise<FsPickResult>;
+    stat(windowId: string, path: string): FsMetadata | Promise<FsMetadata>;
+    list(windowId: string, path: string): FsDirectoryEntry[] | Promise<FsDirectoryEntry[]>;
+    read(windowId: string, path: string, options?: FsReadOptions): FsReadResult | Promise<FsReadResult>;
+    write(windowId: string, path: string, data: string, options?: FsWriteOptions): FsWriteResult | Promise<FsWriteResult>;
+    mkdir(windowId: string, path: string, options?: FsMkdirOptions): void | Promise<void>;
+    remove(windowId: string, path: string, recursive?: boolean): void | Promise<void>;
+    move(windowId: string, fromPath: string, toPath: string): void | Promise<void>;
+    watch(windowId: string, path: string, options: FsWatchOptions | undefined, onChange: (change: FsBackendChange) => void): FsBackendWatch | Promise<FsBackendWatch>;
+    /** Release session-scoped backend state for a destroyed runtime window. */
+    onWindowDestroyed?(windowId: string): void;
+    /** Release all backend resources. */
+    close?(): void;
+}
+/** Error with a closed NAP-FS wire reason. */
+declare class FsServiceError extends Error {
+    readonly code: FsError;
+    constructor(code: FsError, message?: FsError);
+}
+/** Options for {@link createFsService}. */
+interface FsServiceOptions {
+    backend: FsBackend;
+}
+/** Created NAP-FS service. */
+interface FsService extends ServiceHandler {
+    /** Close watches and backend resources. */
+    dispose(): void;
+}
+/**
+ * Create a NAP-FS wire service over a runtime-owned backend.
+ *
+ * @param options - Filesystem backend.
+ * @returns Service handler for `runtime.registerService('fs', handler)`.
+ */
+declare function createFsService(options: FsServiceOptions): FsService;
+
+export { type BleServiceContext, type BleServiceOptions, type CacheServiceOptions, type CatalogIntentResolver, type CatalogIntentResolverOptions, type CommonServiceContext, type CommonServiceOptions, type ConfigSchemaValidation, type ConfigService, type ConfigServiceOptions, type ConfigSettingsContext, type CoordinatedRelayOptions, type CordnCodecResult, type CordnCoordinatorClient, type CordnCoordinatorSubscription, type CordnDmAdapterOptions, type CordnDmClient, type CordnGroupMessage, type CordnRelayCoordinatorOptions, type CountRequest, type CountResult, type CountServiceOptions, type DmAdapter, DmMemoryStore, type DmRelayPool, type DmService, type DmServiceOptions, type FsBackend, type FsBackendChange, type FsBackendWatch, type FsService, FsServiceError, type FsServiceOptions, type HostCacheBridge, type HostKeyEvent, type HostKeysBridge, type HostMediaBridge, type HttpUploaderOptions, type HttpUploaderRails, type IdentityServiceOptions, type IntentArchetypeSupport, type IntentCatalogEntry, type IntentDispatchParams, type IntentResolver, type IntentResolverContext, type IntentServiceOptions, type IntentTargetController, type IntentTargetDispatch, type KeysServiceOptions, type LinkOpenContext, type LinkServiceOptions, type ListsServiceContext, type ListsServiceOptions, type ManifestArchetypeInput, type MaybePromise, type MediaMetadataLike, type MediaPlaybackOwner, type MediaServiceOptions, type MediaSessionCreateOptions, type MediaSessionTarget, type MediaSourceRef, type NdrDmAdapterOptions, type NdrRelayTransport, type NdrRelayTransportOptions, type NdrRumorLike, type NdrRuntimeLike, type Nip17DmAdapterOptions, type NostrTag, type Notification, type NotificationServiceOptions, type NotifyInteractionMessage, type NotifyPresentation, type NotifyServiceOptions, type OutboxEventOptions, type OutboxEventResult, type OutboxPublishOptions, type OutboxPublishResult, type OutboxQueryOptions, type OutboxQueryStream, type OutboxQueryStreamSink, type OutboxRelayPlan, type OutboxRelayPool, type OutboxResult, type OutboxRouter, type OutboxRouterSubscription, type OutboxServiceOptions, type OutboxSubscribeOptions, type OutboxSubscriptionSink, type OutboxTarget, type RailServerConfig, type RelayListEntry, type RelayPoolOutboxRouterOptions, type RelayPoolServiceOptions, type ResourceErrorCode, type ResourceInfo, type ResourceInfoContext, type ResourceInfoProvider, type ResourceSchemeInfo, type ResourceService, ResourceServiceError, type ResourceServiceOptions, type SerialServiceContext, type SerialServiceOptions, type SignEvent, type StreamingOutboxRouter, type ThemeService, type ThemeServiceOptions, type UploadDimensions, type UploadInfo, type UploadInfoContext, type UploadInfoProvider, type UploadRail, type UploadRailInfo, type UploadRequest, type UploadResult, type UploadServiceOptions, type UploadState, type UploadStatus, type Uploader, type UploaderContext, type WebrtcServiceContext, type WebrtcServiceOptions, createBleService, createBrowserMediaBridge, createCacheService, createCatalogIntentResolver, createCommonService, createConfigService, createCoordinatedRelay, createCordnDmAdapter, createCordnRelayCoordinatorClient, createCountService, createDmService, createFsService, createHttpUploader, createIdentityService, createIntentService, createKeysService, createLinkService, createListsService, createMediaService, createNdrDmAdapter, createNdrRelayTransport, createNip17DmAdapter, createNotificationService, createNotifyService, createOutboxService, createRelayPoolOutboxRouter, createRelayPoolService, createResourceService, createSerialService, createThemeService, createUploadService, createWebrtcService, manifestToIntentCatalogEntry, resolveConfigValues, validateConfigSchema };