@kehto/services 0.16.5 → 0.17.0

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 import { ServiceHandler, Signer, RelayEventResult } 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, 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';
+import { NostrFilter, NostrEvent, EventTemplate, IntentRequest, IntentRejectedResult, IntentAcceptedResult, IntentAvailability, IntentContract, IntentDelivery, 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 { IntentAcceptedResult, IntentAvailability, IntentBehavior, IntentCandidate, IntentContract, IntentDelivery, IntentHandlerPreference, IntentInvokeOptions, IntentRejectedResult, 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';
@@ -14,46 +15,6 @@ export { a as CvmCloseMessage, b as CvmCloseResultMessage, c as CvmDiscoverMessa
  * These types describe the internal state that services manage and expose
  * to the shell host via callbacks. They are NOT NIP-01 wire types.
  */
-/**
- * An active audio source registered by a napplet.
- *
- * @example
- * ```ts
- * const source: AudioSource = {
- *   windowId: 'win-1',
- *   nappletClass: 'music-player',
- *   title: 'Now Playing',
- *   muted: false,
- * };
- * ```
- */
-interface AudioSource {
-    /** The napplet window that registered this audio source. */
-    windowId: string;
-    /** The napplet class/type (e.g., 'music-player'). */
-    nappletClass: string;
-    /** Human-readable title for the audio source. */
-    title: string;
-    /** Whether this source is currently muted. */
-    muted: boolean;
-}
-/**
- * Options for creating an audio service via createAudioService().
- *
- * @example
- * ```ts
- * const audioService = createAudioService({
- *   onChange: (sources) => console.log('Audio sources changed:', sources.size),
- * });
- * ```
- */
-interface AudioServiceOptions {
-    /**
-     * Called when the audio source registry changes (register, unregister,
-     * mute, state update). The shell host uses this to update UI.
-     */
-    onChange?: (sources: ReadonlyMap<string, AudioSource>) => void;
-}
 /**
  * A notification created by a napplet.
  *
@@ -107,49 +68,13 @@ interface NotificationServiceOptions {
     maxPerWindow?: number;
 }
 
-/**
- * audio-service.ts — Audio source registry as a ServiceHandler.
- *
- * Tracks which napplet windows are producing audio. Shell hosts wire this
- * into the runtime via registerService('audio', createAudioService(opts)).
- * Browser-agnostic — no DOM, no window, no postMessage.
- */
-
-/**
- * Create an audio service handler.
- *
- * The audio service is a state registry that tracks active audio sources
- * per napplet window. Napplets announce audio state via `audio:*` topic
- * events; the service tracks sources and can relay mute commands back.
- *
- * @param options - Optional configuration (onChange callback for UI updates)
- * @returns A ServiceHandler to register with the runtime
- *
- * @example
- * ```ts
- * import { createAudioService } from '@kehto/services';
- *
- * const audio = createAudioService({
- *   onChange: (sources) => {
- *     // Update UI with current audio sources
- *     for (const [windowId, source] of sources) {
- *       console.log(`${source.title} (${source.muted ? 'muted' : 'playing'})`);
- *     }
- *   },
- * });
- *
- * runtime.registerService('audio', audio);
- * ```
- */
-declare function createAudioService(options?: AudioServiceOptions): ServiceHandler;
-
 /**
  * Create a notification service handler.
  *
  * The notification service is a state registry that tracks notifications
- * per napplet window. Napplets create and manage notifications via
- * `notifications:*` topic events; the shell host controls presentation
- * via the onChange callback.
+ * per napplet window. It accepts direct `notify.*` service envelopes; INC
+ * topics are opaque application data and never select a host service. The
+ * shell host controls presentation through the onChange callback.
  *
  * @param options - Optional configuration (onChange callback, maxPerWindow limit)
  * @returns A ServiceHandler to register with the runtime
@@ -166,7 +91,7 @@ declare function createAudioService(options?: AudioServiceOptions): ServiceHandl
  *   maxPerWindow: 50,
  * });
  *
- * runtime.registerService('notifications', notifications);
+ * runtime.registerService('notify', notifications);
  * ```
  */
 declare function createNotificationService(options?: NotificationServiceOptions): ServiceHandler;
@@ -346,8 +271,9 @@ interface RelayPoolServiceOptions {
      * Publish an event to relays.
      *
      * @param event - The event to publish
+     * @returns Nothing, or a promise that settles when the publish request completes
      */
-    publish(event: NostrEvent): void;
+    publish(event: NostrEvent): void | Promise<void>;
     /**
      * Select relay URLs appropriate for the given filters.
      *
@@ -892,11 +818,8 @@ declare function createBrowserMediaBridge(opts?: {
  * via bridge.setMetadata / bridge.setPlaybackState. When the active session is
  * destroyed, the next-most-recently-touched session is promoted automatically.
  *
- * Note: this is SEPARATE from packages/services/src/audio-service.ts, which
- * is the legacy inc-topic-based audio source registry (audio:* topic events
- * over inc.emit). media-service is the canonical @napplet/nap/media NIP-5D
- * path and they coexist — audio-service continues to track audio sources for
- * shell UI, while media-service handles the NAP protocol envelope surface.
+ * This is the canonical @napplet/nap/media NIP-5D path. It handles media
+ * protocol envelopes directly and does not depend on convention-topic routing.
  *
  * Shell -> Napplet push types (media.command) are emitted here when
  * bridge.onAction callbacks fire — this is the canonical Phase 27 real backend.
@@ -1104,14 +1027,12 @@ declare function createMediaService(options?: MediaServiceOptions): ServiceHandl
  * Host apps wire a real backend via
  * `runtime.registerService('notify', realHandler)`.
  *
- * Coexistence note: this is SEPARATE from
- * `packages/services/src/notification-service.ts`, which is the legacy
- * inc-topic-based notification registry (operates on `inc.emit` topics
- * under `notifications:*`). `notify-service.ts` is the canonical
- * `@napplet/nap/notify` NIP-5D path and lives alongside the legacy module.
+ * `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; the legacy inc-emit topic path remains untouched.
+ * land here.
  *
  * Shell -> napplet push messages (`notify.action`, `notify.clicked`,
  * `notify.dismissed`, `notify.controls`) are not emitted by this stub —
@@ -2147,109 +2068,17 @@ interface HttpUploaderOptions {
  */
 declare function createHttpUploader(options: HttpUploaderOptions): Uploader;
 
-/**
- * intent-types.ts — NAP-INTENT (archetype intent dispatch) value types.
- *
- * Kehto-internal model for the NAP-INTENT wire contract (upstream draft:
- * napplet/naps NAP-INTENT, namespace `window.napplet.intent`). The installed
- * `@napplet/core` peer predates these types, so — as with {@link ./cvm-types} —
- * kehto defines them here, wire-compatible with the upstream shapes, rather
- * than redefining the generic NIP-5D envelope.
- *
- * NAP-INTENT standardizes the *envelope*, not the payload. `archetype` is the
- * routing axis (which role, whose default), `protocol` is the parsing axis
- * (which NAP-N wire format shapes `payload`); the two are orthogonal.
- *
- * @packageDocumentation
- */
-/**
- * How the shell should pick the handling napplet for an intent.
- *
- * - `"default"` — route to the user's default handler for the archetype.
- * - `"choose"`  — prompt the user with an "open with…" chooser.
- * - any other string — a specific napplet dTag (cross-napplet targeting; the
- *   shell SHOULD require the user to have authorized this for the caller).
- */
-type IntentHandlerPreference = 'default' | 'choose' | (string & {});
-/** Window-behavior hints carried with an intent invoke. */
-interface IntentBehavior {
-    /** Bring the handler window to the foreground. */
-    focus?: boolean;
-    /** Force a new window rather than reusing an existing handler instance. */
-    newWindow?: boolean;
-    /** Prefer reusing an already-open handler instance when one exists. */
-    reuse?: boolean;
-}
-/** A request to dispatch an action to a napplet of a given archetype. */
-interface IntentRequest {
-    /** Role slug, e.g. `"note"` (see the archetype registry). */
-    archetype: string;
-    /** Verb, default `"open"` (e.g. `"open"` | `"edit"` | `"pick"` | `"share"`). */
-    action?: string;
-    /** NAP-N id shaping `payload`; omit to use the archetype's recommended default. */
-    protocol?: string;
-    /** Opaque payload, typed by `protocol`. */
-    payload?: unknown;
-    /** Handler-selection preference. */
-    handler?: IntentHandlerPreference;
-    /** Window-behavior hints. */
-    behavior?: IntentBehavior;
-}
-/** A napplet that can fulfill an archetype, sourced from the manifest catalog. */
-interface IntentCandidate {
-    /** dTag of the napplet that can fulfill the archetype. */
-    dTag: string;
-    /** Human-readable title from the manifest. */
-    title?: string;
-    /** Verbs this candidate supports for the archetype. */
-    actions: string[];
-    /** NAP-N ids this candidate accepts for the archetype. */
-    protocols: string[];
-    /** Whether this candidate is the user/runtime default for the archetype. */
-    isDefault?: boolean;
-}
-/** Availability of an archetype, sourced from the installed-napplet catalog. */
-interface IntentAvailability {
-    /** The archetype this availability describes. */
-    archetype: string;
-    /** True when at least one installed napplet fulfills the archetype. */
-    available: boolean;
-    /** Candidate napplets that fulfill the archetype (from manifests, not instances). */
-    candidates: IntentCandidate[];
-    /** True when a user/runtime default handler is set for the archetype. */
-    hasDefault: boolean;
-}
-/** The result of an intent invocation. */
-interface IntentResult {
-    /** Whether the intent was dispatched successfully. */
-    ok: boolean;
-    /** The requested archetype, echoed back. */
-    archetype: string;
-    /** The resolved action (defaults to `"open"` when the request omits it). */
-    action: string;
-    /** True when a handler accepted the dispatch. */
-    handled: boolean;
-    /** dTag of the napplet that handled the intent, when one did. */
-    handler?: string;
-    /** Window id the handler was created or focused in. */
-    windowId?: string;
-    /** The wire format actually used to deliver `payload`. */
-    protocol?: string;
-    /** Error reason when the intent could not be fulfilled. */
-    error?: string;
-}
-
 /**
  * intent-service.ts — NAP-INTENT (archetype intent dispatch) reference service.
  *
  * Shell-side handler for the NAP-INTENT wire protocol. It is a pure envelope
  * router: it validates `intent.*` envelopes, delegates archetype resolution,
- * default handling, window lifecycle, and payload delivery to an injected
- * {@link IntentResolver}, and posts the correlated result / push messages
- * (echoing the request `id`) back to the napplet.
+ * default handling and retained target delivery to an injected
+ * {@link IntentResolver}, then posts correlated result and push messages back
+ * to the napplet.
  *
  * The resolver is injected (options-as-bridge) so this service has no shell or
- * window-manager dependency and is fully unit-testable. A concrete
+ * target-lifecycle dependency and is fully unit-testable. A concrete
  * catalog-backed resolver ships alongside as {@link createCatalogIntentResolver}.
  *
  * ──────────────────────────── Responsibilities ────────────────────────────
@@ -2258,15 +2087,15 @@ interface IntentResult {
  *             intent.handlers.result, intent.changed
  *
  * The shell owns archetype→handler resolution, the user's default-handler
- * preference, the "open with…" chooser, and window creation/focus — all behind
- * the {@link IntentResolver}. This service only marshals the wire protocol and
- * fans `intent.changed` pushes out to the napplets it has served.
+ * preference, chooser, and retained target policy behind the
+ * {@link IntentResolver}. This service only marshals the wire protocol and
+ * fans `intent.changed` pushes out to eligible napplets.
  *
  * @example
  * ```ts
  * import { createIntentService, createCatalogIntentResolver } from '@kehto/services';
  *
- * const resolver = createCatalogIntentResolver({ loadCatalog, windows });
+ * const resolver = createCatalogIntentResolver({ loadCatalog, targets });
  * runtime.registerService('intent', createIntentService({ resolver }));
  * ```
  *
@@ -2275,22 +2104,53 @@ interface IntentResult {
 
 /** Context passed to {@link IntentResolver.invoke} for trust/attribution. */
 interface IntentResolverContext {
-    /** Window id of the napplet that issued the request. */
-    windowId: string;
+    /** Runtime-attested dTag of the napplet that issued the request. */
+    sender: string;
+}
+/**
+ * Opaque runtime-owned delivery responsibility retained before acceptance.
+ *
+ * Starting the task may wait for target readiness and apply host retry,
+ * replacement, or terminal-failure policy. It never produces a second source
+ * result.
+ */
+interface IntentRetainedDelivery {
+    /**
+     * Begin target lifecycle and eventual delivery policy.
+     *
+     * @returns Nothing, or a promise settled when controller policy completes.
+     */
+    start(): void | Promise<void>;
+}
+/** A resolver rejection before delivery responsibility was retained. */
+interface IntentRejectedResolverOutcome {
+    /** Exact canonical pre-acceptance rejection. */
+    result: IntentRejectedResult;
+}
+/** A resolver acceptance backed by already-retained delivery responsibility. */
+interface IntentAcceptedResolverOutcome {
+    /** Exact canonical acceptance result. */
+    result: IntentAcceptedResult;
+    /** Opaque task that the service starts only after sending the source result. */
+    retained: IntentRetainedDelivery;
 }
+/** Pre-acceptance rejection or accepted retained-delivery responsibility. */
+type IntentResolverOutcome = IntentRejectedResolverOutcome | IntentAcceptedResolverOutcome;
 /**
  * Abstract intent resolver. Implementors own the installed-napplet catalog,
  * archetype→handler resolution, the user's default-handler preference, the
- * "open with…" chooser, window creation/focus, and payload delivery. The
+ * chooser and retained target delivery policy. The
  * service translates wire envelopes into these calls and back.
  */
 interface IntentResolver {
     /**
-     * Resolve `request.archetype` to a handler, create or focus its window, and
-     * deliver `payload`. Returns once the handler is resolved and the window
-     * created; delivery MAY complete asynchronously.
+     * Resolve the request and retain target delivery responsibility.
+     *
+     * @param request - Validated normalized intent request.
+     * @param context - Runtime-attested source identity.
+     * @returns A structured rejection, or an acceptance plus an unstarted task.
      */
-    invoke(request: IntentRequest, context: IntentResolverContext): IntentResult | Promise<IntentResult>;
+    invoke(request: IntentRequest, context: IntentResolverContext): IntentResolverOutcome | Promise<IntentResolverOutcome>;
     /** Report whether the runtime can currently satisfy `archetype`, and how. */
     available(archetype: string): IntentAvailability | Promise<IntentAvailability>;
     /** Report availability for every archetype the runtime can currently satisfy. */
@@ -2320,35 +2180,32 @@ declare function createIntentService(options: IntentServiceOptions): ServiceHand
 /**
  * catalog-intent-resolver.ts — NAP-INTENT concrete {@link IntentResolver}.
  *
- * A reference resolver that satisfies {@link IntentResolver} from an
- * installed-napplet catalog plus host-supplied policy: the user's
- * default-handler preference, an optional "open with…" chooser, the archetype's
- * recommended default protocol, and a window controller that creates or focuses
- * the handler window and delivers the payload.
- *
- * Resolution policy (mirrors an OS implicit-intent + default-app model):
- *   1. Gather candidates for the archetype from the catalog.
- *   2. Pick the handler — an explicit `handler` dTag, a user choice
- *      (`handler: "choose"`), the user's default, the sole candidate, or a
- *      deterministic first-candidate fallback.
- *   3. Validate the resolved handler supports the requested `action` and
- *      `protocol` (or fall back to the archetype's recommended default protocol,
- *      then the candidate's first accepted protocol).
- *   4. Open or focus the handler window and return its id.
- *
- * The catalog, defaults, chooser, and window controller are all injected, so
- * this resolver carries no shell, manifest, or DOM dependency and is fully
- * unit-testable.
+ * A reference resolver backed by installed, verified NIP-5A manifest contracts
+ * plus host-supplied user policy. Contract compatibility is exact complete
+ * convention equality. Catalog order, payload contents, quick action indexes,
+ * and event-kind metadata never select a handler.
+ *
+ * Selection policy:
+ *   1. Filter installed candidates by exact manifest contract.
+ *   2. Require positive host authorization for an explicit handler dTag.
+ *   3. Otherwise use an explicit chooser, a compatible user default, the sole
+ *      compatible candidate, or an injected chooser.
+ *   4. Reject ambiguity when no chooser policy exists.
+ *
+ * The catalog, defaults, chooser, authorization hook, and target controller are
+ * injected, so this resolver has no shell, manifest, or DOM dependency.
  *
  * @packageDocumentation
  */
 
-/** The actions/protocols a napplet fulfills for a single archetype. */
+/** The exact manifest-derived conventions a napplet fulfills for one archetype. */
 interface IntentArchetypeSupport {
-    /** Verbs this napplet supports for the archetype (e.g. `["open", "edit"]`). */
+    /** Verbs derived from this napplet's accepted conventions. */
     actions: string[];
-    /** NAP-N protocol ids this napplet accepts for the archetype. */
-    protocols: string[];
+    /** Stable queryless convention identities derived from {@link contracts}. */
+    conventions: string[];
+    /** Authoritative ordered contracts parsed from the installed manifest. */
+    contracts: IntentContract[];
 }
 /**
  * One installed napplet's intent surface, derived from its signed NIP-5A
@@ -2360,57 +2217,60 @@ interface IntentCatalogEntry {
     dTag: string;
     /** Human-readable title from the manifest. */
     title?: string;
-    /** Archetype slug → the actions/protocols this napplet fulfills for it. */
+    /** Archetype slug to exact manifest-derived support. */
     archetypes: Record<string, IntentArchetypeSupport>;
 }
-/** Parameters handed to {@link IntentWindowController.open}. */
-interface IntentOpenParams {
-    /** dTag of the resolved handler napplet. */
-    dTag: string;
-    /** The archetype being dispatched. */
-    archetype: string;
-    /** The resolved action (e.g. `"open"`). */
-    action: string;
-    /** The wire format the payload is delivered with, when one was resolved. */
-    protocol?: string;
-    /** The opaque payload to deliver. */
-    payload?: unknown;
-    /** Window-behavior hints from the request. */
-    behavior?: IntentBehavior;
-    /** Window id of the napplet that issued the intent. */
-    callerWindowId: string;
-}
-/** Creates or focuses the handler window and delivers the intent payload. */
-interface IntentWindowController {
-    /**
-     * Create or focus the handler window and deliver `payload` via `protocol`.
-     * Returns the window id the handler was created or focused in.
-     */
-    open(params: IntentOpenParams): {
-        windowId: string;
-    } | Promise<{
-        windowId: string;
-    }>;
+/** Exact carrier-neutral values retained for one selected intent target. */
+interface IntentRetentionParams {
+    /** Selected target napplet dTag. */
+    readonly handler: string;
+    /** Immutable canonical delivery retained independently of the source. */
+    readonly delivery: Readonly<IntentDelivery>;
+    /** Copied non-authoritative target lifecycle hints. */
+    readonly behavior?: Readonly<IntentBehavior>;
+}
+/** Host controller that retains source-independent target delivery policy. */
+interface IntentTargetController {
+    /**
+     * Retain delivery responsibility without starting target policy.
+     *
+     * @param params - Immutable selected target and canonical delivery values.
+     * @returns An opaque unstarted delivery task.
+     */
+    retain(params: IntentRetentionParams): IntentRetainedDelivery | Promise<IntentRetainedDelivery>;
 }
 /** Options for {@link createCatalogIntentResolver}. */
 interface CatalogIntentResolverOptions {
-    /** Return the installed-napplet catalog (signed NIP-5A manifests). Required. */
+    /** Return the installed-napplet catalog sourced from signed manifests. */
     loadCatalog(): IntentCatalogEntry[] | Promise<IntentCatalogEntry[]>;
-    /** Window controller used to create/focus the resolved handler's window. Required. */
-    windows: IntentWindowController;
+    /** Target controller that retains responsibility before resolver acceptance. */
+    targets: IntentTargetController;
     /**
-     * The user's default handler dTag for an archetype, or `undefined` when none
-     * is set. Default-handler settings are user state — never set by napplets.
+     * Return the user's default handler dTag for an archetype.
+     *
+     * @param archetype - Normalized archetype slug.
+     * @returns The user-selected default dTag, or `undefined`.
      */
     getDefaultHandler?(archetype: string): string | undefined;
     /**
-     * Resolve a `handler: "choose"` prompt (or a no-default ambiguity) to a dTag.
-     * Returning `undefined` means the user cancelled. When omitted, ambiguous
-     * resolution falls back to the first candidate.
+     * Ask user policy to select one exact-compatible candidate.
+     *
+     * @param archetype - Normalized archetype slug.
+     * @param candidates - Only candidates with an exact matching contract.
+     * @param sender - Runtime-attested source napplet dTag.
+     * @returns A candidate dTag, or `undefined` when the user cancels.
      */
-    chooseHandler?(archetype: string, candidates: IntentCandidate[], callerWindowId: string): string | undefined | Promise<string | undefined>;
-    /** The archetype's recommended default protocol when the caller omits one. */
-    defaultProtocol?(archetype: string): string | undefined;
+    chooseHandler?(archetype: string, candidates: IntentCandidate[], sender: string): string | undefined | Promise<string | undefined>;
+    /**
+     * Authorize a caller's explicit handler dTag preference.
+     *
+     * @param sender - Runtime-attested source napplet dTag.
+     * @param handler - Explicit requested handler dTag.
+     * @param request - Normalized intent request.
+     * @param candidate - Installed exact-compatible candidate.
+     * @returns `true` only when explicit targeting is user-authorized.
+     */
+    authorizeExplicitHandler?(sender: string, handler: string, request: IntentRequest, candidate: IntentCandidate): boolean | Promise<boolean>;
 }
 /**
  * A {@link IntentResolver} backed by a catalog, with a host hook to announce
@@ -2418,26 +2278,27 @@ interface CatalogIntentResolverOptions {
  */
 interface CatalogIntentResolver extends IntentResolver {
     /**
-     * Announce that the catalog or default handler for `archetype` changed. The
-     * resolver recomputes availability and notifies `onChanged` listeners, which
-     * the intent service forwards to napplets as `intent.changed` pushes.
+     * Announce that the catalog or default handler for `archetype` changed.
+     *
+     * @param archetype - Changed archetype slug.
+     * @returns Nothing.
      */
     notifyChanged(archetype: string): void;
 }
 /**
  * Create a catalog-backed NAP-INTENT resolver.
  *
- * @param options - Catalog loader and window controller (required) plus
- *   optional default-handler, chooser, and default-protocol policy hooks.
- * @returns A {@link CatalogIntentResolver} for `createIntentService({ resolver })`.
- * @throws If `options.loadCatalog` or `options.windows` is missing.
+ * @param options - Catalog loader and target controller plus optional user
+ *   default, chooser, and explicit-handler authorization hooks.
+ * @returns A catalog-backed resolver.
+ * @throws If required catalog or target-controller options are missing.
  *
  * @example
  * ```ts
  * const resolver = createCatalogIntentResolver({
  *   loadCatalog: () => installedNapplets,
- *   windows: { open: ({ dTag }) => ({ windowId: openWindow(dTag) }) },
- *   getDefaultHandler: (a) => userDefaults[a],
+ *   targets: { retain: (params) => retainTargetDelivery(params) },
+ *   getDefaultHandler: (archetype) => userDefaults[archetype],
  * });
  * ```
  */
@@ -2471,22 +2332,22 @@ interface ManifestArchetypeInput {
     /** Optional human-readable title from the manifest. */
     title?: string;
     /**
-     * Archetype slugs this napplet fulfills, from the manifest's `archetype` tags;
-     * the optional `nap` is the recommended default wire protocol.
+     * Ordered convention contracts from the manifest's `archetype` tags.
      */
     archetypes: Array<{
         slug: string;
-        nap?: string;
+        convention: string;
+        eventKinds?: number[];
     }>;
 }
 /**
  * Map a resolved napplet manifest's archetype data into an
  * {@link IntentCatalogEntry}.
  *
- * Each archetype `{ slug, nap }` becomes a keyed support record where `actions`
- * defaults to `['open']` (the NAP-INTENT default action — manifests do not
- * enumerate actions in this phase) and `protocols` is `[nap]` when a NAP-N is
- * present, else `[]`. Duplicate slugs keep the last occurrence.
+ * Each manifest tag remains one ordered contract. Repeated slugs group into one
+ * support record while repeated conventions remain distinct contracts; action
+ * and convention arrays are stable, deduplicated indexes derived from those
+ * contracts.
  *
  * @param manifest - A resolved manifest's structural archetype data.
  * @returns The `IntentCatalogEntry` for `createCatalogIntentResolver`.
@@ -2496,10 +2357,14 @@ interface ManifestArchetypeInput {
  * manifestToIntentCatalogEntry({
  *   dTag: 'profile-viewer',
  *   title: 'Profile',
- *   archetypes: [{ slug: 'profile', nap: 'NAP-1' }],
+ *   archetypes: [{ slug: 'profile', convention: 'napplet:profile/open' }],
  * });
  * // → { dTag: 'profile-viewer', title: 'Profile',
- * //     archetypes: { profile: { actions: ['open'], protocols: ['NAP-1'] } } }
+ * //     archetypes: { profile: {
+ * //       actions: ['open'],
+ * //       conventions: ['napplet:profile/open'],
+ * //       contracts: [{ convention: 'napplet:profile/open' }],
+ * //     } } }
  * ```
  */
 declare function manifestToIntentCatalogEntry(manifest: ManifestArchetypeInput): IntentCatalogEntry;
@@ -3009,4 +2874,4 @@ declare function createCordnRelayCoordinatorClient(options: CordnRelayCoordinato
 /** Create a Cordn/ContextVM-backed NAP-DM adapter. */
 declare function createCordnDmAdapter(options: CordnDmAdapterOptions): DmAdapter;
 
-export { type AudioServiceOptions, type AudioSource, 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 IntentAvailability, type IntentBehavior, type IntentCandidate, type IntentCatalogEntry, type IntentHandlerPreference, type IntentOpenParams, type IntentRequest, type IntentResolver, type IntentResolverContext, type IntentResult, type IntentServiceOptions, type IntentWindowController, 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, createAudioService, 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 };
+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 IntentAcceptedResolverOutcome, type IntentArchetypeSupport, type IntentCatalogEntry, type IntentRejectedResolverOutcome, type IntentResolver, type IntentResolverContext, type IntentResolverOutcome, type IntentRetainedDelivery, type IntentRetentionParams, type IntentServiceOptions, type IntentTargetController, 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 };