@oxy.so/core 7.9.2 → 7.10.1

package/dist/esm/session/SessionClient.js

@@ -36,6 +36,8 @@ export class SessionClient {
         this.tokenUnsub = null;
         this.started = false;
         this.lifecycleGeneration = 0;
+        /** Changes whenever the locally projected device changes, including ABA. */
+        this.deviceGeneration = 0;
         this.fullSignOutPersistence = null;
         /** Same-origin cross-tab state-propagation channel; null on platforms without BroadcastChannel. */
         this.channel = null;
@@ -65,6 +67,25 @@ export class SessionClient {
             throw new Error('Device session request was superseded');
         return response;
     }
+    /** Capture the local device before a request, including device ABA. */
+    captureDeviceRequest() {
+        return { generation: this.deviceGeneration, initialDevice: this.state?.deviceId ?? null };
+    }
+    isCurrentDeviceRequest(request, response) {
+        if (request.generation === this.deviceGeneration)
+            return true;
+        if (request.initialDevice !== null || this.deviceGeneration !== request.generation + 1)
+            return false;
+        if (response === null || typeof response !== 'object')
+            return false;
+        const record = response;
+        const deviceId = record.state?.deviceId ?? record.directory?.deviceId ?? record.deviceId;
+        return typeof deviceId === 'string' && deviceId === this.state?.deviceId;
+    }
+    assertCurrentDeviceRequest(request, response) {
+        if (!this.isCurrentDeviceRequest(request, response))
+            throw new Error('Device session request was superseded');
+    }
     /** Stop and discard only this client's local device projection; no server revocation. */
     resetLocalState() {
         this.lifecycleGeneration += 1;
@@ -213,6 +234,8 @@ export class SessionClient {
             return false;
         }
         const previousState = this.state;
+        if (previousState?.deviceId !== next.deviceId)
+            this.deviceGeneration += 1;
         this.state = next;
         if (next.accounts.length === 0) {
             // A device with nobody signed in has no principals either. The directory
@@ -321,11 +344,13 @@ export class SessionClient {
                 .ensureActiveToken(next)
                 .then(finishApply)
                 .catch((error) => {
-                if (generation !== this.lifecycleGeneration)
+                if (generation !== this.lifecycleGeneration || this.state !== next)
                     return;
                 logger.warn('[SessionClient] ensureActiveToken failed — reverting session state', { component: 'SessionClient' }, error);
                 // Do NOT notify under a mismatched bearer. Revert to the last applied
                 // state so subscribers keep observing the account whose token is planted.
+                if (this.state?.deviceId !== previousState?.deviceId)
+                    this.deviceGeneration += 1;
                 this.state = previousState ?? null;
             });
         }
@@ -375,6 +400,21 @@ export class SessionClient {
         if (this.fullSignOutPersistence?.state === this.state)
             await this.fullSignOutPersistence.pending;
     }
+    /** Keep mutation callers from reporting success after a device change during persistence. */
+    async applySyncForMutation(raw) {
+        const before = this.captureDeviceRequest();
+        const lifecycle = this.lifecycleGeneration;
+        const checked = deviceSessionSyncCheck(raw, []);
+        const responseDevice = checked.ok ? checked.value.state.deviceId : before.initialDevice;
+        const expectedGeneration = before.generation + (responseDevice === before.initialDevice ? 0 : 1);
+        const pending = this.applySync(raw);
+        const generation = this.deviceGeneration;
+        await pending;
+        if (generation !== expectedGeneration ||
+            generation !== this.deviceGeneration ||
+            lifecycle !== this.lifecycleGeneration)
+            throw new Error('Device session request was superseded');
+    }
     /**
      * The apply + token-plant half of {@link applySync}, on an ALREADY-VALIDATED
      * sync. Split out so the context-aware removal lane — whose response is a
@@ -394,14 +434,15 @@ export class SessionClient {
         const applied = this.applyState(sync.state, 'request', sync.activeToken?.accessToken);
         // Equal-revision restate (this revision was already applied by a preceding
         // socket push): `applyState` no-ops without planting, but the token still
-        // needs planting. Guard on the sync's active account STILL being the current
-        // active account so a stale response cannot adopt a token for an account a
-        // newer state already switched away from — and, when pinned, on that account
-        // being the PINNED one (same rule as the applied path in `applyState`).
+        // needs planting. Only the exact same device revision is an equal-revision
+        // restate: an older response may identify a different operator of the same
+        // account. Also require the current account and the identity pin to match.
         const pinnedAccountId = this.pinnedAccountId();
         if (!applied &&
             sync.activeToken &&
             this.state &&
+            sync.state.deviceId === this.state.deviceId &&
+            sync.state.revision === this.state.revision &&
             sync.state.activeAccountId !== null &&
             sync.state.activeAccountId === this.state.activeAccountId &&
             (pinnedAccountId === null || sync.state.activeAccountId === pinnedAccountId) &&
@@ -451,9 +492,12 @@ export class SessionClient {
     }
     /** `GET /session/device/directory` → {@link applyDirectory}. No notify. */
     async fetchDirectory() {
+        const request = this.captureDeviceRequest();
         const res = await this.requestDevice('GET', '/session/device/directory', undefined, {
             cache: false,
         });
+        if (!this.isCurrentDeviceRequest(request, res))
+            return false;
         return this.applyDirectory(res);
     }
     /**
@@ -515,14 +559,13 @@ export class SessionClient {
         if (!accessToken) {
             return;
         }
+        const pinnedAccountId = this.pinnedAccountId();
         const subjectAccountId = resolveActiveContext(directory)?.subject.accountId ?? null;
         if (subjectAccountId === null) {
             return;
         }
-        const pinnedAccountId = this.pinnedAccountId();
-        if (pinnedAccountId !== null && subjectAccountId !== pinnedAccountId) {
+        if (pinnedAccountId !== null && subjectAccountId !== pinnedAccountId)
             return;
-        }
         if (accessToken === this.host.getAccessToken()) {
             return;
         }
@@ -562,9 +605,12 @@ export class SessionClient {
         }
     }
     async bootstrap() {
+        const request = this.captureDeviceRequest();
         const res = await this.requestDevice('GET', '/session/device/state', undefined, {
             cache: false,
         });
+        if (!this.isCurrentDeviceRequest(request, res))
+            return;
         await this.applySync(res);
     }
     /**
@@ -608,13 +654,41 @@ export class SessionClient {
      * compatibility path for callers still keyed on account ids.
      */
     async activateContext(contextId) {
+        const request = this.captureDeviceRequest();
         const res = await this.requestDevice('POST', '/session/device/activate', { contextId }, { cache: false });
+        this.assertCurrentDeviceRequest(request, res);
         const activation = checkContract(deviceActivateResponseCheck, res);
         if (!activation) {
             logger.warn('[SessionClient] discarded invalid activation response');
             return;
         }
+        if (this.pinnedAccountId() === null) {
+            const active = resolveActiveContext(activation.directory);
+            if (!active || activation.directory.activeContextId !== contextId)
+                throw new Error('Device session request was superseded');
+            const claims = activation.activeToken?.accessToken
+                ? decodeTokenClaims(activation.activeToken.accessToken)
+                : null;
+            const contextClaim = claims?.device_context_id;
+            const actor = claims?.act;
+            const actorClaim = actor !== null && typeof actor === 'object' ? actor.sub : undefined;
+            const subjectClaim = claims?.userId ?? claims?.id ?? claims?.sub;
+            // Decoded claims are only a consistency check, never authorization.
+            // Legacy and opaque bearers may omit these claims entirely.
+            if ((typeof contextClaim === 'string' && contextClaim !== active.contextId) ||
+                (typeof actorClaim === 'string' && actorClaim !== active.actor.userId) ||
+                (typeof subjectClaim === 'string' && subjectClaim !== active.subject.accountId))
+                throw new Error('Device session request was superseded');
+        }
         const known = this.knownRevisionFor(activation.directory.deviceId);
+        if (known !== null && activation.directory.revision < known)
+            throw new Error('Device session request was superseded');
+        const held = this.directory;
+        if (this.pinnedAccountId() === null &&
+            held?.deviceId === activation.directory.deviceId &&
+            held.revision === activation.directory.revision &&
+            held.activeContextId !== activation.directory.activeContextId)
+            throw new Error('Device session request was superseded');
         const moved = known === null || activation.directory.revision > known;
         this.plantActiveContextToken(activation.directory, activation.activeToken?.accessToken);
         // Applied BEFORE the reconcile, and only then: the reconcile's own
@@ -624,8 +698,21 @@ export class SessionClient {
         // already holding in hand.
         const applied = this.applyDirectory(activation.directory);
         if (moved) {
+            const beforeReconcile = this.captureDeviceRequest();
+            const lifecycle = this.lifecycleGeneration;
             await this.reconcileFlatState(activation.directory);
+            const landedOnTarget = beforeReconcile.initialDevice !== activation.directory.deviceId &&
+                this.deviceGeneration === beforeReconcile.generation + 1 &&
+                this.state?.deviceId === activation.directory.deviceId;
+            if (lifecycle !== this.lifecycleGeneration ||
+                (this.deviceGeneration !== beforeReconcile.generation && !landedOnTarget))
+                throw new Error('Device session request was superseded');
         }
+        if (this.pinnedAccountId() === null &&
+            (this.knownRevisionFor(activation.directory.deviceId) !== activation.directory.revision ||
+                this.directory?.deviceId !== activation.directory.deviceId ||
+                this.directory.activeContextId !== contextId))
+            throw new Error('Device session request was superseded');
         if (applied) {
             this.notify();
         }
@@ -634,8 +721,18 @@ export class SessionClient {
         }
     }
     async switchAccount(accountId) {
+        const request = this.captureDeviceRequest();
         const res = await this.requestDevice('POST', '/session/device/switch', { accountId }, { cache: false });
-        await this.applySync(res);
+        this.assertCurrentDeviceRequest(request, res);
+        const checked = deviceSessionSyncCheck(res, []);
+        const isStale = () => checked.ok &&
+            this.state?.deviceId === checked.value.state.deviceId &&
+            this.state.revision > checked.value.state.revision;
+        if (isStale())
+            throw new Error('Device session request was superseded');
+        await this.applySyncForMutation(res);
+        if (isStale())
+            throw new Error('Device session request was superseded');
         this.postCommitPing();
     }
     /**
@@ -650,10 +747,12 @@ export class SessionClient {
      * {@link signOutPrincipal} for the two that can tell those apart.
      */
     async signOut(target) {
+        const request = this.captureDeviceRequest();
         const res = await this.requestDevice('POST', '/session/device/signout', target, {
             cache: false,
         });
-        await this.applySync(res);
+        this.assertCurrentDeviceRequest(request, res);
+        await this.applySyncForMutation(res);
         this.postCommitPing();
         if (this.state?.accounts.length === 0)
             await this.persistFullSignOut();
@@ -695,21 +794,34 @@ export class SessionClient {
      * applied this revision.
      */
     async removeFromDevice(target) {
+        const request = this.captureDeviceRequest();
         const res = await this.requestDevice('POST', '/session/device/signout', target, {
             cache: false,
         });
+        this.assertCurrentDeviceRequest(request, res);
         const removal = checkContract(deviceDirectorySyncCheck, res);
         if (!removal) {
             logger.warn('[SessionClient] discarded invalid device removal response');
             return;
         }
         const directoryApplied = this.applyDirectory(removal.directory);
+        const beforeCommit = this.captureDeviceRequest();
+        const commitLifecycle = this.lifecycleGeneration;
+        const expectedGeneration = beforeCommit.generation + (beforeCommit.initialDevice === removal.state.deviceId ? 0 : 1);
         const stateApplied = this.commitSync({
             state: removal.state,
             activeToken: removal.activeToken,
         });
-        if (this.fullSignOutPersistence?.state === this.state)
+        if (expectedGeneration !== this.deviceGeneration ||
+            commitLifecycle !== this.lifecycleGeneration)
+            throw new Error('Device session request was superseded');
+        if (this.fullSignOutPersistence?.state === this.state) {
+            const generation = this.deviceGeneration;
+            const lifecycle = this.lifecycleGeneration;
             await this.fullSignOutPersistence.pending;
+            if (generation !== this.deviceGeneration || lifecycle !== this.lifecycleGeneration)
+                throw new Error('Device session request was superseded');
+        }
         // `commitSync` publishes whenever the flat state moved. When only the
         // directory did — a socket push already applied this revision — the
         // directory half would otherwise never reach a subscriber.
@@ -721,10 +833,12 @@ export class SessionClient {
             await this.persistFullSignOut();
     }
     async addCurrentAccount() {
+        const request = this.captureDeviceRequest();
         const res = await this.requestDevice('POST', '/session/device/add', undefined, {
             cache: false,
         });
-        await this.applySync(res);
+        this.assertCurrentDeviceRequest(request, res);
+        await this.applySyncForMutation(res);
         this.postCommitPing();
     }
     /**

package/dist/types/api/storeInstaller.d.ts

@@ -0,0 +1,155 @@
+/**
+ * The store's installer: how a store installs, opens and updates an application on a machine
+ * that installs applications, beside `oxy.store`, which reads the catalogue.
+ *
+ * `oxy.store` says what the store lists; an installer says what the machine can do with a
+ * listing. A runtime that installs applications registers one (OxyOS's Bloom host registers one
+ * backed by the system's install service before the application's code runs, OxyOS ADR 0030
+ * decision 9; ADR 0053 here). Where none is registered — the web, iOS, Android — there is
+ * nothing to install, and a store shows what it shows without one. An application never asks
+ * which platform it runs on: it asks whether there is an installer.
+ *
+ * The installer is the store's hands, never its judge. It is given a listing's slug and nothing
+ * else: the machine resolves slug → package → release from the store's signed metadata, verifies
+ * it, and asks the person in a sheet of its own that no application can draw or press. The store
+ * learns the outcome and nothing of the sheet. Its errors say whether the machine already told the
+ * person (`told`), so a store never repeats what the system said.
+ *
+ * React-free and dependency-free, as everything in `@oxy.so/core`.
+ */
+/** Where a listing stands on this machine, for the action a store's page shows. */
+export type StoreInstallState = 
+/** The store has a release this machine can run, and it is not installed: *Get*. */
+{
+    state: 'notInstalled';
+}
+/** Being installed or updated: a progress ring. `fraction` is null while it cannot be told. */
+ | {
+    state: 'installing';
+    fraction: number | null;
+}
+/** Installed and current: *Open*. */
+ | {
+    state: 'installed';
+    version: string;
+}
+/**
+ * Installed, with a newer release: *Update*. `needsConsent` when the newer release asks for
+ * more than the installed one, which the machine asks the person for in its own sheet.
+ */
+ | {
+    state: 'updateAvailable';
+    version: string;
+    newVersion: string;
+    needsConsent: boolean;
+}
+/** The store has no release this machine can run: *Not available for this computer*. */
+ | {
+    state: 'unavailable';
+};
+/** Why the machine could not do what the store asked. */
+export type StoreInstallerFailure = 
+/** The machine's install service is not running. */
+'serviceUnavailable'
+/** The store has no release of it this machine can run. */
+ | 'notAvailable'
+/** It is not installed (opening or updating it). */
+ | 'notInstalled'
+/** The installer refused the request (it lacks the right to install, or it was not a person's press). */
+ | 'refused'
+/** The install or update itself failed (a download, a verification, a compile). */
+ | 'failed';
+/** A failure of an installer's request. */
+export declare class StoreInstallerError extends Error {
+    readonly reason: StoreInstallerFailure;
+    /**
+     * Whether the machine already told the person, in its own sheet. A store says nothing more
+     * when it did: the system's word is the one the person reads.
+     */
+    readonly told: boolean;
+    constructor(reason: StoreInstallerFailure, options?: {
+        told?: boolean;
+        message?: string;
+    });
+}
+/** An update the machine has for an installed application. */
+export interface StoreUpdate {
+    /** The installer's own id for the application; what `apply` takes. Never a slug. */
+    id: string;
+    /** Its name in the person's language, from the store's signed metadata. */
+    name: string;
+    /** The version installed, and the one the update brings. */
+    version: string;
+    newVersion: string;
+    /** Bytes the machine would fetch: only what it does not have already. */
+    downloadSize: number;
+    /** What is new, in the person's language, or null when the release says nothing. */
+    releaseNotes: string | null;
+    /** The update asks for more than the installed version: the machine asks the person first. */
+    needsConsent: boolean;
+    /** Applied, waiting for the running copy to quit: it runs at its next launch. */
+    atNextLaunch: boolean;
+}
+/** The machine's updates for this account: one state, which every page that shows updates reads. */
+export interface StoreUpdates {
+    updates: StoreUpdate[];
+    /** A check of the store is running. */
+    checking: boolean;
+    /** When the store was last read (ISO 8601), or null. */
+    lastChecked: string | null;
+    /** The last check failed. */
+    checkFailed: boolean;
+}
+/** The machine's updates, as one state that changes by itself. */
+export interface StoreUpdatesSource {
+    /** The state last told, or null before the machine has said. */
+    current(): StoreUpdates | null;
+    /**
+     * The state as it is now, asked of the machine without reading the store. Rejects with a
+     * `StoreInstallerError` when the machine cannot say (its install service is not running).
+     */
+    read(): Promise<StoreUpdates>;
+    /** Reads the store now. A check asked while one runs joins it. */
+    check(): Promise<StoreUpdates>;
+    /** Applies these updates; one that needs consent is asked in the machine's sheet first. */
+    apply(ids: readonly string[]): Promise<void>;
+    /** Applies every update, asking for consent in turn after the rest. */
+    applyAll(): Promise<void>;
+    /** Told each change; returns the unsubscribe. */
+    subscribe(listener: (updates: StoreUpdates) => void): () => void;
+}
+/**
+ * What a runtime that installs applications gives a store. Every action that changes anything is
+ * asked from a person's press: the machine refuses what the person did not ask for.
+ */
+export interface StoreInstaller {
+    /**
+     * Where each listing stands. Rejects with a `StoreInstallerError` when the machine cannot say
+     * (its install service is not running): a store then shows its usual action and lets the
+     * machine say why when it is pressed.
+     */
+    status(slugs: readonly string[]): Promise<Record<string, StoreInstallState>>;
+    /**
+     * Installs a listing's application: the machine's sheet, then the install. Resolves when the
+     * person declined in the sheet or the install is done; the progress in between is told to
+     * `subscribe`'s listeners as `installing`.
+     */
+    install(slug: string): Promise<'installed' | 'declined'>;
+    /** Updates it, asking in the machine's sheet when the update needs the person's consent. */
+    update(slug: string): Promise<'updated' | 'declined'>;
+    /** Removes it and its data, after the machine's sheet. */
+    uninstall(slug: string): Promise<'removed' | 'declined'>;
+    /** Opens the installed application. */
+    open(slug: string): Promise<void>;
+    /** Told each listing whose state changed; returns the unsubscribe. */
+    subscribe(listener: (slug: string, state: StoreInstallState) => void): () => void;
+    /** The account's updates (a store's *Updates* page). */
+    readonly updates: StoreUpdatesSource;
+}
+/**
+ * Registers the machine's installer, or removes it with null. A runtime calls it once, before
+ * the application's code runs; nothing else should.
+ */
+export declare function setStoreInstaller(next: StoreInstaller | null): void;
+/** The machine's installer, or null where nothing installs applications. */
+export declare function getStoreInstaller(): StoreInstaller | null;

package/dist/types/index.d.ts

@@ -45,6 +45,8 @@ export type { AppsApi, AppAssertionsApi, Application, ApplicationType, Applicati
 export type { LinkedAccountsApi } from './api/linkedAccounts';
 export type { AgencyApi, AccountCapabilityPolicy, AvailableCapabilityCatalog, CapabilityExecutionAuthorization, CreateDelegationGrantInput, DelegationCatalogBinding, DelegationGrantView, PutAccountCapabilityPolicyInput, UpdateDelegationGrantInput, } from './api/agency';
 export type { StoreApi, StoreCategory, StoreRating, StoreListingSummary, StoreListingDetail, StoreScreenshot, StoreScreenshotPlatform, StoreReview, StoreOwnReview, WriteStoreReviewInput, StoreListingStatus, PublisherListing, WriteListingInput, AddScreenshotInput, UpdateScreenshotInput, StorePage, StorePageOptions, StoreReviewsOptions, } from './api/store';
+export { getStoreInstaller, setStoreInstaller, StoreInstallerError, } from './api/storeInstaller';
+export type { StoreInstallState, StoreInstaller, StoreInstallerFailure, StoreUpdate, StoreUpdates, StoreUpdatesSource, } from './api/storeInstaller';
 export type { BillingApi, SubscriptionPlan, SubscriptionStatus, SubscriptionFeatures, Subscription, Payment, WalletTransactionType, WalletTransactionStatus, WalletTransaction, WalletPagination, WalletTransactionsPage, } from './api/billing';
 export { REPUTATION_CACHE_PREFIX } from './api/reputation';
 export type { ReputationApi, ReputationPage } from './api/reputation';

package/dist/types/session/SessionClient.d.ts

@@ -110,6 +110,8 @@ export declare class SessionClient {
     private tokenUnsub;
     private started;
     private lifecycleGeneration;
+    /** Changes whenever the locally projected device changes, including ABA. */
+    private deviceGeneration;
     private fullSignOutPersistence;
     /** Same-origin cross-tab state-propagation channel; null on platforms without BroadcastChannel. */
     private channel;
@@ -120,6 +122,10 @@ export declare class SessionClient {
     constructor(host: SessionClientHost, options?: SessionClientOptions);
     private persistFullSignOut;
     private requestDevice;
+    /** Capture the local device before a request, including device ABA. */
+    private captureDeviceRequest;
+    private isCurrentDeviceRequest;
+    private assertCurrentDeviceRequest;
     /** Stop and discard only this client's local device projection; no server revocation. */
     resetLocalState(): void;
     getState(): DeviceSessionState | null;
@@ -189,6 +195,8 @@ export declare class SessionClient {
      * account that is no longer active.
      */
     private applySync;
+    /** Keep mutation callers from reporting success after a device change during persistence. */
+    private applySyncForMutation;
     /**
      * The apply + token-plant half of {@link applySync}, on an ALREADY-VALIDATED
      * sync. Split out so the context-aware removal lane — whose response is a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxy.so/core",
-  "version": "7.9.2",
+  "version": "7.10.1",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",

package/src/api/storeInstaller.ts

@@ -0,0 +1,158 @@
+/**
+ * The store's installer: how a store installs, opens and updates an application on a machine
+ * that installs applications, beside `oxy.store`, which reads the catalogue.
+ *
+ * `oxy.store` says what the store lists; an installer says what the machine can do with a
+ * listing. A runtime that installs applications registers one (OxyOS's Bloom host registers one
+ * backed by the system's install service before the application's code runs, OxyOS ADR 0030
+ * decision 9; ADR 0053 here). Where none is registered — the web, iOS, Android — there is
+ * nothing to install, and a store shows what it shows without one. An application never asks
+ * which platform it runs on: it asks whether there is an installer.
+ *
+ * The installer is the store's hands, never its judge. It is given a listing's slug and nothing
+ * else: the machine resolves slug → package → release from the store's signed metadata, verifies
+ * it, and asks the person in a sheet of its own that no application can draw or press. The store
+ * learns the outcome and nothing of the sheet. Its errors say whether the machine already told the
+ * person (`told`), so a store never repeats what the system said.
+ *
+ * React-free and dependency-free, as everything in `@oxy.so/core`.
+ */
+
+/** Where a listing stands on this machine, for the action a store's page shows. */
+export type StoreInstallState =
+  /** The store has a release this machine can run, and it is not installed: *Get*. */
+  | { state: 'notInstalled' }
+  /** Being installed or updated: a progress ring. `fraction` is null while it cannot be told. */
+  | { state: 'installing'; fraction: number | null }
+  /** Installed and current: *Open*. */
+  | { state: 'installed'; version: string }
+  /**
+   * Installed, with a newer release: *Update*. `needsConsent` when the newer release asks for
+   * more than the installed one, which the machine asks the person for in its own sheet.
+   */
+  | { state: 'updateAvailable'; version: string; newVersion: string; needsConsent: boolean }
+  /** The store has no release this machine can run: *Not available for this computer*. */
+  | { state: 'unavailable' };
+
+/** Why the machine could not do what the store asked. */
+export type StoreInstallerFailure =
+  /** The machine's install service is not running. */
+  | 'serviceUnavailable'
+  /** The store has no release of it this machine can run. */
+  | 'notAvailable'
+  /** It is not installed (opening or updating it). */
+  | 'notInstalled'
+  /** The installer refused the request (it lacks the right to install, or it was not a person's press). */
+  | 'refused'
+  /** The install or update itself failed (a download, a verification, a compile). */
+  | 'failed';
+
+/** A failure of an installer's request. */
+export class StoreInstallerError extends Error {
+  readonly reason: StoreInstallerFailure;
+  /**
+   * Whether the machine already told the person, in its own sheet. A store says nothing more
+   * when it did: the system's word is the one the person reads.
+   */
+  readonly told: boolean;
+
+  constructor(reason: StoreInstallerFailure, options: { told?: boolean; message?: string } = {}) {
+    super(options.message ?? reason);
+    this.name = 'StoreInstallerError';
+    this.reason = reason;
+    this.told = options.told ?? false;
+  }
+}
+
+/** An update the machine has for an installed application. */
+export interface StoreUpdate {
+  /** The installer's own id for the application; what `apply` takes. Never a slug. */
+  id: string;
+  /** Its name in the person's language, from the store's signed metadata. */
+  name: string;
+  /** The version installed, and the one the update brings. */
+  version: string;
+  newVersion: string;
+  /** Bytes the machine would fetch: only what it does not have already. */
+  downloadSize: number;
+  /** What is new, in the person's language, or null when the release says nothing. */
+  releaseNotes: string | null;
+  /** The update asks for more than the installed version: the machine asks the person first. */
+  needsConsent: boolean;
+  /** Applied, waiting for the running copy to quit: it runs at its next launch. */
+  atNextLaunch: boolean;
+}
+
+/** The machine's updates for this account: one state, which every page that shows updates reads. */
+export interface StoreUpdates {
+  updates: StoreUpdate[];
+  /** A check of the store is running. */
+  checking: boolean;
+  /** When the store was last read (ISO 8601), or null. */
+  lastChecked: string | null;
+  /** The last check failed. */
+  checkFailed: boolean;
+}
+
+/** The machine's updates, as one state that changes by itself. */
+export interface StoreUpdatesSource {
+  /** The state last told, or null before the machine has said. */
+  current(): StoreUpdates | null;
+  /**
+   * The state as it is now, asked of the machine without reading the store. Rejects with a
+   * `StoreInstallerError` when the machine cannot say (its install service is not running).
+   */
+  read(): Promise<StoreUpdates>;
+  /** Reads the store now. A check asked while one runs joins it. */
+  check(): Promise<StoreUpdates>;
+  /** Applies these updates; one that needs consent is asked in the machine's sheet first. */
+  apply(ids: readonly string[]): Promise<void>;
+  /** Applies every update, asking for consent in turn after the rest. */
+  applyAll(): Promise<void>;
+  /** Told each change; returns the unsubscribe. */
+  subscribe(listener: (updates: StoreUpdates) => void): () => void;
+}
+
+/**
+ * What a runtime that installs applications gives a store. Every action that changes anything is
+ * asked from a person's press: the machine refuses what the person did not ask for.
+ */
+export interface StoreInstaller {
+  /**
+   * Where each listing stands. Rejects with a `StoreInstallerError` when the machine cannot say
+   * (its install service is not running): a store then shows its usual action and lets the
+   * machine say why when it is pressed.
+   */
+  status(slugs: readonly string[]): Promise<Record<string, StoreInstallState>>;
+  /**
+   * Installs a listing's application: the machine's sheet, then the install. Resolves when the
+   * person declined in the sheet or the install is done; the progress in between is told to
+   * `subscribe`'s listeners as `installing`.
+   */
+  install(slug: string): Promise<'installed' | 'declined'>;
+  /** Updates it, asking in the machine's sheet when the update needs the person's consent. */
+  update(slug: string): Promise<'updated' | 'declined'>;
+  /** Removes it and its data, after the machine's sheet. */
+  uninstall(slug: string): Promise<'removed' | 'declined'>;
+  /** Opens the installed application. */
+  open(slug: string): Promise<void>;
+  /** Told each listing whose state changed; returns the unsubscribe. */
+  subscribe(listener: (slug: string, state: StoreInstallState) => void): () => void;
+  /** The account's updates (a store's *Updates* page). */
+  readonly updates: StoreUpdatesSource;
+}
+
+let installer: StoreInstaller | null = null;
+
+/**
+ * Registers the machine's installer, or removes it with null. A runtime calls it once, before
+ * the application's code runs; nothing else should.
+ */
+export function setStoreInstaller(next: StoreInstaller | null): void {
+  installer = next;
+}
+
+/** The machine's installer, or null where nothing installs applications. */
+export function getStoreInstaller(): StoreInstaller | null {
+  return installer;
+}