@deveye/types 0.15.1 → 0.16.0

package/src/sdk/manifest.ts

@@ -1,19 +1,16 @@
 import type { ZodType } from 'zod';
+import type { FeatureDescriptor } from '../domain/featureRegistry';
 import {
     EXTERNAL_FEATURE_ID_PATTERN,
     isExternalFeatureId,
+    type ExternalFeatureId,
     type FeatureId
 } from '../domain/workspaceRole';
 
 /**
  * The feature manifest: everything DevEye needs to know about a feature,
- * declared once.
- *
- * Historically this knowledge was scattered across ~14 registration points
- * (descriptor, catalog entry, settings wiring tables, invalidation keys,
- * teleport segments...). A module declares all of it here; the app's generated
- * glue reads the manifest and wires every screen from it. Native features are
- * being migrated onto the same contract (Weather first).
+ * declared once. The app's generated glue reads it and wires every screen
+ * (descriptor, catalog, settings tabs, invalidation keys, teleport segments).
  */
 
 /**
@@ -76,23 +73,48 @@ export type NativeCapability =
     | 'notify'
     | 'mail.accounts'
     | 'members.read'
+    /**
+     * List every workspace of this DevEye (id, name, kind, owner). A global
+     * administrator's surface only: the call refuses anyone else. What a
+     * fleet needs to attach a device to workspaces.
+     */
+    | 'workspaces.read'
     /** Read/authorize the workspace's devices. */
     | 'devices.read'
     /**
      * The full agent-fleet sync transport (outbound requests, browser fan-out,
-     * per-socket subscriptions). Reserved for repatriated NATIVE features: the
-     * agent protocol is app infrastructure, not a third-party surface.
+     * per-socket subscriptions). Reserved for native-id modules: the agent
+     * protocol is app infrastructure, not a third-party surface.
      */
-    | 'agents';
+    | 'agents'
+    /**
+     * Read the devices' telemetry (process instants, metric rows, evidence
+     * pinning). Reserved for native-id modules like `'agents'`: the metric
+     * store is app infrastructure.
+     */
+    | 'telemetry.read'
+    /**
+     * Public HTTP routes: endpoints reachable WITHOUT a session (an analytics
+     * beacon), mounted on every listener the host exposes, with open CORS.
+     * Declared, because opening a door is the one thing a module must not do
+     * quietly. See `FeatureService.publicRoutes`.
+     */
+    | 'routes.public';
 
 /**
  * Settings tabs the shell can render for you.
  *  - `'notifications'` and `'permissions'` are fully generic: DevEye renders
  *    them from the manifest alone, you write no component.
- *  - `'general'` and `'sources'` need a panel component, provided by your
- *    client entry (`settingsPanels`), keyed by the tab id.
+ *  - `'general'`, `'sources'`, `'sync'` and `'encryption'` need a panel
+ *    component, provided by your client entry (`settingsPanels`), keyed by
+ *    the tab id. `'sync'` (item scope only) is the cadence and maintenance of
+ *    an item the module keeps fresh in the background (a mailbox).
+ *    `'encryption'` (item scope only) is where an item chooses the form of
+ *    its own data, when the feature leaves the choice: the shell names and
+ *    places the tab, the module owns the choice.
  */
-export type SettingsTab = 'general' | 'sources' | 'notifications' | 'permissions';
+export type SettingsTab =
+    'general' | 'sources' | 'notifications' | 'permissions' | 'sync' | 'encryption';
 
 /** A custom settings tab. Needs a matching panel in `settingsPanels`. */
 export interface CustomTabRef {
@@ -125,6 +147,22 @@ export interface CrossTopicInvalidation {
 /** Where a feature's card can live on the home grid. */
 export type FeatureCategory = 'supervision' | 'security' | 'dev' | 'work' | 'daily' | 'analysis';
 
+/**
+ * A data link from this feature to another one, as the "About" card of the
+ * home grid reads it (in both directions): a real coupling (an alert sender
+ * goes through a Mail account, a project points its repositories), not a
+ * thematic neighbourhood.
+ */
+export interface FeatureLink {
+    /** The feature linked to. Never your own id. */
+    to: FeatureId;
+    /** What the link allows, said from this feature's point of view. */
+    what: string;
+}
+
+/** Hard cap on `links`: the "About" card stays a card. */
+export const MAX_FEATURE_LINKS = 6;
+
 export interface FeatureManifest<Id extends FeatureId = FeatureId> {
     /** External modules: `x-<slug>`. Native features keep their enum id. */
     id: Id;
@@ -150,14 +188,20 @@ export interface FeatureManifest<Id extends FeatureId = FeatureId> {
     sources?: { hint: string };
     /**
      * Whether an item can be projected into another workspace. Decided by
-     * encryption, not preference. External modules: `'never'` only for now
-     * (cross-workspace listing requires repo-level wiring not yet in the SDK).
+     * encryption: only the open tier is readable by the server alone. Anything
+     * but `'never'` commits the module to the sharing contract: a server entry
+     * with `items`, listings that read `ctx.sharing.scope()` and pick the
+     * cipher row by row, and `ctx.items.restrictions()` applied to what they
+     * return. External modules declare `'never'` for now.
      */
     shareTier: 'open' | 'perItem' | 'never';
 
     /** Card rendering on the home grid. `compact` halves the minimum height. */
     tile?: { compact?: boolean };
 
+    /** See {@link FeatureLink}. At most {@link MAX_FEATURE_LINKS}. */
+    links?: readonly FeatureLink[];
+
     /**
      * The feature offers a compact TOPBAR widget (pinned top-right of the
      * navbar). Declares only the DATA the picker shows; the component itself
@@ -184,6 +228,15 @@ export interface FeatureManifest<Id extends FeatureId = FeatureId> {
      */
     invalidatedByTopic?: readonly string[];
 
+    /**
+     * Secondary live topics of your own, beaten separately from your id so a
+     * frequent write does not refresh everything (a chat thread that must not
+     * re-fetch the board). Each names the keys it re-fetches (a subset of
+     * `resources`); its id starts with yours. A handler beats it with
+     * `mutates: ['<topic>']`, a service with `live.changed(ws, ['<topic>'])`.
+     */
+    topics?: readonly { id: string; keys: readonly string[] }[];
+
     /**
      * Keys ALSO re-fetched when another feature's topic fires. The escape
      * hatch for real data coupling (CloudSync's share rows carry device names:
@@ -200,13 +253,6 @@ export interface FeatureManifest<Id extends FeatureId = FeatureId> {
      */
     commandPrefix?: string;
 
-    /**
-     * Builds the live/teleport segment for one item, e.g. `(id) => `job:${id}``.
-     * MUST return byte-for-byte what your view declares via `useLiveSegment('l1', ...)`:
-     * it is a rendezvous, not a convention. Requires `hasItems`.
-     */
-    itemSegment?: (itemId: number | string) => string;
-
     /** Settings tabs, per scope. Omit a scope to render no settings there. */
     settings?: {
         feature?: readonly (SettingsTab | CustomTabRef)[];
@@ -231,7 +277,6 @@ export function validateManifest(m: FeatureManifest): void {
     if (!m.label.trim()) fail(m.id, 'empty label');
     if (!m.description.trim()) fail(m.id, 'empty description');
     if (m.hasItems && !m.itemNoun?.trim()) fail(m.id, 'hasItems requires itemNoun');
-    if (!m.hasItems && m.itemSegment) fail(m.id, 'itemSegment requires hasItems');
     if (external && m.shareTier !== 'never') {
         fail(m.id, "external modules must declare shareTier 'never' for now");
     }
@@ -261,6 +306,27 @@ export function validateManifest(m: FeatureManifest): void {
             fail(m.id, `invalidatedByTopic « ${key} » is not in resources`);
         }
     }
+    for (const topic of m.topics ?? []) {
+        if (
+            !/^[a-z][a-zA-Z0-9-]{1,31}$/.test(topic.id) ||
+            !topic.id.startsWith(m.id) ||
+            topic.id === m.id
+        ) {
+            fail(m.id, `topic « ${topic.id} » must start with the feature id and differ from it`);
+        }
+        for (const key of topic.keys) {
+            if (!m.resources.includes(key)) {
+                fail(m.id, `topic « ${topic.id} » key « ${key} » is not in resources`);
+            }
+        }
+    }
+
+    const links = m.links ?? [];
+    if (links.length > MAX_FEATURE_LINKS) fail(m.id, `more than ${MAX_FEATURE_LINKS} links`);
+    for (const link of links) {
+        if (link.to === m.id) fail(m.id, 'links must name ANOTHER feature');
+        if (!link.what.trim()) fail(m.id, `link to « ${link.to} »: empty what`);
+    }
 
     const cross = m.alsoInvalidatedBy ?? [];
     if (cross.length > 4) fail(m.id, 'more than 4 alsoInvalidatedBy entries');
@@ -273,8 +339,10 @@ export function validateManifest(m: FeatureManifest): void {
         }
     }
 
-    if ((m.nativeCapabilities ?? []).includes('agents') && external) {
-        fail(m.id, "capability 'agents' is reserved for native-id modules");
+    for (const reserved of ['agents', 'telemetry.read'] as const) {
+        if ((m.nativeCapabilities ?? []).includes(reserved) && external) {
+            fail(m.id, `capability '${reserved}' is reserved for native-id modules`);
+        }
     }
 
     const extras = m.extraPermissions ?? [];
@@ -313,6 +381,9 @@ export function validateManifest(m: FeatureManifest): void {
                 if (tab === 'sources' && scope === 'item') {
                     fail(m.id, 'sources is a feature-scope tab');
                 }
+                if (tab === 'encryption' && scope === 'feature') {
+                    fail(m.id, 'encryption is an item-scope tab');
+                }
             } else {
                 if (!CUSTOM_TAB_PATTERN.test(tab.id) || BUILTIN_TABS.includes(tab.id)) {
                     fail(m.id, `invalid custom tab id « ${tab.id} »`);
@@ -324,3 +395,67 @@ export function validateManifest(m: FeatureManifest): void {
         }
     }
 }
+
+/**
+ * The registry descriptor of an EXTERNAL module, read off its manifest: what
+ * the roles screen, the settings shell and the catalog need to know without
+ * opening the module. Natives keep their published descriptor; the app's
+ * server and client registries both project through here.
+ */
+export function externalDescriptorOf(
+    m: FeatureManifest
+): FeatureDescriptor & { id: ExternalFeatureId } {
+    if (!isExternalFeatureId(m.id)) {
+        throw new Error(`externalDescriptorOf: « ${m.id} » is not an external id`);
+    }
+    return {
+        id: m.id,
+        label: m.label,
+        description: m.description,
+        icon: m.icon,
+        notifies: m.notifies,
+        hasItems: m.hasItems,
+        itemNoun: m.itemNoun,
+        sources: m.sources,
+        shareTier: m.shareTier
+    };
+}
+
+export interface ExtrasResolver {
+    canExtra(key: string): boolean;
+    extraValue(key: string): string;
+}
+
+/**
+ * The runtime rules of extra permissions, shared by the app's request context
+ * and the test harness so the two can never drift:
+ *  - a key the manifest does not declare, or of the other kind, yields
+ *    `false` / `''`;
+ *  - the workspace owner holds every toggle and gets `ownerValue` of every
+ *    choice;
+ *  - a member holds a toggle when the grant says `true`, and gets a choice's
+ *    granted value when it is one of the options, `default` otherwise.
+ */
+export function resolveExtras(
+    specs: readonly ExtraPermissionSpec[] | undefined,
+    isOwner: boolean,
+    granted: Readonly<Record<string, boolean | string>>
+): ExtrasResolver {
+    const byKey = new Map((specs ?? []).map((spec) => [spec.key, spec]));
+    return {
+        canExtra(key) {
+            const spec = byKey.get(key);
+            if (!spec || spec.type !== 'toggle') return false;
+            return isOwner || granted[key] === true;
+        },
+        extraValue(key) {
+            const spec = byKey.get(key);
+            if (!spec || spec.type !== 'choice') return '';
+            if (isOwner) return spec.ownerValue;
+            const value = granted[key];
+            return typeof value === 'string' && spec.options.some((o) => o.value === value)
+                ? value
+                : spec.default;
+        }
+    };
+}

package/src/sdk/providers.ts

@@ -1,12 +1,14 @@
 /**
- * Provider contracts: the inversion for PUBLIC app code that needs a MODULE's
- * data.
+ * Provider contracts: the inversion for code that needs a MODULE's data,
+ * whether it is the app or another module.
  *
  * A module exposes named contracts on its service (`FeatureService.providers`);
  * the app looks them up at call time (`moduleProvider(key)` in its SDK
- * assembly) and degrades cleanly when the module is absent. The contract types
- * live here, in the published package, because both sides must agree on them
- * while neither may import the other.
+ * assembly, `ctx.providers.get(key)` from a module) and degrades cleanly when
+ * the module is absent. The contract types live here, in the published
+ * package, because both sides must agree on them while neither may import the
+ * other. Every provider is offered by a module's service: the app offers none
+ * itself.
  */
 
 /** Key under `FeatureService.providers` for the CloudSync backup source. */
@@ -46,3 +48,306 @@ export interface CloudSyncBackupProvider {
     /** Decrypted plaintext stream of one blob. */
     openBlob(shareId: number, hash: string): Promise<AsyncIterable<Uint8Array>>;
 }
+
+/**
+ * Key of the database access the Backup module consumes: a logical dump goes
+ * through the SAME access as the monitoring (SSH tunnel or SOCKS proxy
+ * included), and only the Databases feature knows how to decrypt a connection.
+ */
+export const DATABASE_BACKUP_PROVIDER = 'database.backup' as const;
+
+/** A database of the workspace, as the source picker lists it. */
+export interface DatabaseBackupCandidate {
+    id: number;
+    name: string;
+    engine: 'mysql' | 'postgres';
+    host: string;
+    database: string;
+}
+
+/**
+ * An OPEN access to a database: what a dump tool needs, reachable from the
+ * server (the tunnel's local listener when there is one). `close()` releases
+ * the tunnel; call it whatever happens, a forgotten tunnel keeps an SSH
+ * session and a listener alive.
+ */
+export interface DatabaseBackupAccess {
+    engine: 'mysql' | 'postgres';
+    host: string;
+    port: number;
+    database: string;
+    username: string;
+    password: string | null;
+    close(): Promise<void>;
+}
+
+export interface DatabaseBackupProvider {
+    /** The databases of the workspace, its own only (a projection is not a source). */
+    listDatabases(workspaceId: number): Promise<readonly DatabaseBackupCandidate[]>;
+    findDatabase(databaseId: number, workspaceId: number): Promise<DatabaseBackupCandidate | null>;
+    /** null when the database is unknown to this workspace. */
+    openAccess(databaseId: number, workspaceId: number): Promise<DatabaseBackupAccess | null>;
+}
+
+/**
+ * Key under `FeatureService.providers` for the Databases items the Projects
+ * feature links to: same shape and reason as `UPTIME_ITEMS_PROVIDER`
+ * (`project_database_links` is Projects' table).
+ */
+export const DATABASE_ITEMS_PROVIDER = 'database.items' as const;
+
+export interface DatabaseItemsProvider {
+    /** Does this database live in this workspace? Its home only, never a projection. */
+    exists(databaseId: number, workspaceId: number): Promise<boolean>;
+    /**
+     * The item's display name under the OPEN cipher of `workspaceId`, its home;
+     * `null` when it is gone or unreadable. What a window onto a projected
+     * project shows for a link it cannot open: a name, never an id.
+     */
+    labelOf(databaseId: number, workspaceId: number): Promise<string | null>;
+}
+
+/**
+ * Key under `FeatureService.providers` for the workspace's outgoing mail: the
+ * transport the app's notification channels of kind `email` send through.
+ * Offered by the Mail module; absent, an email channel cannot be readied and
+ * the settings screen says so. Senders are the module's OPEN-tier, enabled
+ * accounts: a guarded mailbox needs a session unlock no background job has.
+ */
+export const MAIL_TRANSPORT_PROVIDER = 'mail.transport' as const;
+
+/** A mailbox able to send without anyone unlocking anything. */
+export interface MailSender {
+    id: number;
+    label: string;
+    address: string;
+}
+
+export interface MailTransportProvider {
+    /** The workspace's ready senders (open tier, enabled). */
+    listSenders(workspaceId: number): Promise<readonly MailSender[]>;
+    /** Is this account a ready sender of this workspace right now? */
+    isReady(accountId: number, workspaceId: number): Promise<boolean>;
+    /**
+     * Sends one plain-text message from this account. Resolves `true` when the
+     * provider accepted it; `false` (never a throw) when the account is not a
+     * ready sender or the send failed, the failure logged by the module.
+     */
+    send(
+        accountId: number,
+        workspaceId: number,
+        message: { to: string; subject: string; text: string }
+    ): Promise<boolean>;
+}
+
+/**
+ * Key under `FeatureClient.providers` for the Mail pieces the app's settings
+ * shell composes: the ready senders an email channel picks from, and the
+ * feature's own account dialog (the "+" of the channel form). The contract
+ * types live in `@deveye/types/sdk/client`.
+ */
+export const MAIL_CLIENT_PROVIDER = 'mail.client' as const;
+
+/**
+ * Key under `FeatureService.providers` for the Audience sites the app's
+ * Projects feature links to: same shape and same reason as
+ * `UPTIME_ITEMS_PROVIDER` (`project_audience_links` is Projects' table).
+ */
+export const AUDIENCE_ITEMS_PROVIDER = 'audience.items' as const;
+
+export interface AudienceItemsProvider {
+    /** Does this site live in this workspace? Its home only, never a projection. */
+    exists(siteId: number, workspaceId: number): Promise<boolean>;
+    /**
+     * The item's display name under the OPEN cipher of `workspaceId`, its home;
+     * `null` when it is gone or unreadable. What a window onto a projected
+     * project shows for a link it cannot open: a name, never an id.
+     */
+    labelOf(siteId: number, workspaceId: number): Promise<string | null>;
+}
+
+/**
+ * Key under `FeatureClient.providers` for the Audience pieces the app's
+ * Projects screens compose: the list of the workspace's sites, a linked site
+ * shown in full inside a project's tab, and the feature's own site dialog.
+ * The contract types live in `@deveye/types/sdk/client`.
+ */
+export const AUDIENCE_CLIENT_PROVIDER = 'audience.client' as const;
+
+/**
+ * Key under `FeatureService.providers` for the Git repositories the app's
+ * Projects feature links to: same shape and same reason as
+ * `UPTIME_ITEMS_PROVIDER` (`project_repo_links` is Projects' table).
+ */
+export const GIT_ITEMS_PROVIDER = 'git.items' as const;
+
+export interface GitItemsProvider {
+    /** Does this repository live in this workspace? Its home only, never a projection. */
+    exists(repoId: number, workspaceId: number): Promise<boolean>;
+    /**
+     * The item's display name under the OPEN cipher of `workspaceId`, its home;
+     * `null` when it is gone or unreadable. What a window onto a projected
+     * project shows for a link it cannot open: a name, never an id.
+     */
+    labelOf(repoId: number, workspaceId: number): Promise<string | null>;
+}
+
+/**
+ * Key under `FeatureClient.providers` for the Git pieces the app's Projects
+ * screens compose: the list of the workspace's repositories, a linked
+ * repository shown in full inside a project's tab, and the feature's own
+ * repository dialog. The contract types live in `@deveye/types/sdk/client`.
+ */
+export const GIT_CLIENT_PROVIDER = 'git.client' as const;
+
+/**
+ * Key under `FeatureService.providers` for the Deploy targets the app's
+ * Projects feature links to: same shape and same reason as
+ * `UPTIME_ITEMS_PROVIDER` (`project_deploy_links` is Projects' table).
+ */
+export const DEPLOY_ITEMS_PROVIDER = 'deploy.items' as const;
+
+export interface DeployItemsProvider {
+    /** Does this target live in this workspace? Its home only, never a projection. */
+    exists(targetId: number, workspaceId: number): Promise<boolean>;
+    /**
+     * The item's display name under the OPEN cipher of `workspaceId`, its home;
+     * `null` when it is gone or unreadable. What a window onto a projected
+     * project shows for a link it cannot open: a name, never an id.
+     */
+    labelOf(targetId: number, workspaceId: number): Promise<string | null>;
+}
+
+/**
+ * Key under `FeatureClient.providers` for the Deploy pieces the app's
+ * Projects screens compose: the list of the workspace's targets, a linked
+ * target shown in full inside a project's tab, and the feature's own target
+ * dialog. The contract types live in `@deveye/types/sdk/client`.
+ */
+export const DEPLOY_CLIENT_PROVIDER = 'deploy.client' as const;
+
+/**
+ * Key under `FeatureClient.providers` for the Databases pieces the app's
+ * Projects screens compose: the list of the workspace's databases, a linked
+ * database shown in full inside a project's tab, and the feature's own
+ * database dialog (declaring a database from a project goes through the real
+ * form, never a reduced copy). The contract types live in
+ * `@deveye/types/sdk/client` (they are React components).
+ */
+export const DATABASE_CLIENT_PROVIDER = 'database.client' as const;
+
+/**
+ * Key of what Projects knows about the items of OTHER features: the projects
+ * of the workspace that link them (a module's list shows how many projects use
+ * each item, its detail lists them by title), without reading Projects'
+ * tables. Keyed by the linked feature's id so every linkable feature reads the
+ * same contract.
+ */
+export const PROJECTS_USAGE_PROVIDER = 'projects.usage' as const;
+
+/**
+ * A project that links an item. Open tier only: a guarded project cannot link
+ * a workspace item (its link row is plain, the item lives at the open tier),
+ * so every title here is readable without a session.
+ */
+export interface ProjectUsage {
+    projectId: number;
+    title: string;
+    status: 'draft' | 'active' | 'paused' | 'done';
+}
+
+export interface ProjectsUsageProvider {
+    /** The workspace's projects linking this item of this feature, in Projects' display order. */
+    usageOf(feature: string, itemId: number, workspaceId: number): Promise<readonly ProjectUsage[]>;
+    /** How many projects of the workspace link each item of this feature (absent = zero). */
+    countByItem(feature: string, workspaceId: number): Promise<ReadonlyMap<number, number>>;
+    /**
+     * Writes one line in a project's timeline (a deployment triggered from a
+     * project's tab). Open tier only: an event aimed at a guarded project is
+     * dropped silently. Rejects when the write fails; a lost timeline line
+     * never turns a deployment into an error.
+     */
+    recordEvent(
+        projectId: number,
+        workspaceId: number,
+        event: { kind: string; label: string; actorUserId: number | null }
+    ): Promise<void>;
+    /**
+     * Reports a version on the projects linking this item that asked to
+     * follow it (Projects' `versionSource`, `'github_release'` for a git
+     * repository): the field then belongs to the item, and the project's
+     * screen shows it read-only. All linked projects of the workspace, open
+     * tier only; the others are left untouched.
+     */
+    applyVersion(
+        feature: string,
+        itemId: number,
+        workspaceId: number,
+        version: string
+    ): Promise<void>;
+}
+
+/**
+ * Key under `FeatureService.providers` for the Uptime items the app's Projects
+ * feature links to. Projects stores only identifiers; before linking one it
+ * asks the module whether the service exists in the workspace, so a foreign
+ * id can neither be linked nor leak its existence.
+ */
+export const UPTIME_ITEMS_PROVIDER = 'uptime.items' as const;
+
+export interface UptimeItemsProvider {
+    /** Does this service live in this workspace? Its home only, never a projection. */
+    exists(serviceId: number, workspaceId: number): Promise<boolean>;
+    /**
+     * The item's display name under the OPEN cipher of `workspaceId`, its home;
+     * `null` when it is gone or unreadable. What a window onto a projected
+     * project shows for a link it cannot open: a name, never an id.
+     */
+    labelOf(serviceId: number, workspaceId: number): Promise<string | null>;
+}
+
+/**
+ * Key under `FeatureClient.providers` for the Uptime pieces the app's Projects
+ * screens compose: the availability strip and ratios of a linked service, and
+ * the feature's own service dialog (declaring a service from a project goes
+ * through the real form, never a reduced copy). The contract types live in
+ * `@deveye/types/sdk/client` (they are React components).
+ */
+export const UPTIME_CLIENT_PROVIDER = 'uptime.client' as const;
+
+/**
+ * The client twin of the Devices module (`DevicesClientProvider`,
+ * `sdk/client.ts`): the workspace's devices as a store, one device's panel
+ * and tile. The app's home and topbar compose them; without the module they
+ * render nothing device-related.
+ */
+export const DEVICES_CLIENT_PROVIDER = 'devices.client' as const;
+
+/**
+ * Key under `FeatureService.providers` for what Sentinel contributes to the
+ * collection config the app pushes to an agent (`agent.config`): whether the
+ * security probes run, and at which cadence. Absent module: the app pushes the
+ * probes off.
+ */
+export const SENTINEL_AGENT_CONFIG_PROVIDER = 'sentinel.agentConfig' as const;
+
+/**
+ * Cadence du manifeste de persistance quand rien n'est réglé, en minutes.
+ * Vit ici et non dans le domaine du module parce que l'app l'applique
+ * elle-même : sans module installé, ou sans ligne de config pour l'appareil,
+ * la config poussée à l'agent porte ce défaut (sondes éteintes).
+ */
+export const DEFAULT_SENTINEL_INTEGRITY_MINUTES = 360;
+
+export interface SentinelAgentConfig {
+    enabled: boolean;
+    /** Cadence of the persistence manifest, in minutes. */
+    integrityMinutes: number;
+    /** Whether the agent reads the authentication journal. */
+    authEvents: boolean;
+}
+
+export interface SentinelAgentConfigProvider {
+    /** The device's contribution, or null when Sentinel knows nothing about it (probes off). */
+    configFor(deviceId: string): Promise<SentinelAgentConfig | null>;
+}