@deveye/types 0.15.2 → 0.16.0

package/src/sdk/client.ts

@@ -1,4 +1,4 @@
-import type { ComponentType } from 'react';
+import type { ComponentType, ReactNode } from 'react';
 
 /**
  * Client-side SDK contracts: what your package's `./client` entry exports and
@@ -10,12 +10,17 @@ import type { ComponentType } from 'react';
  * shapes both sides must agree on.
  */
 
-/** The scope a settings panel is opened for. */
-export type SdkSettingsScope =
-    { kind: 'feature' } | { kind: 'item'; itemId: number; itemLabel: string };
+/**
+ * The scope a settings panel is opened for. An item id is a number for every
+ * row-keyed feature (the default), a string for a device (a UUID): a module
+ * whose items are strings types its panels `SettingsPanelProps<string>`. The
+ * shell's own sections (sharing, permissions, notifications) key on the number.
+ */
+export type SdkSettingsScope<Id extends number | string = number> =
+    { kind: 'feature' } | { kind: 'item'; itemId: Id; itemLabel: string };
 
-export interface SettingsPanelProps {
-    scope: SdkSettingsScope;
+export interface SettingsPanelProps<Id extends number | string = number> {
+    scope: SdkSettingsScope<Id>;
     /** Caller has `write` on the feature. Render read-only when false. */
     canWrite: boolean;
 }
@@ -39,19 +44,18 @@ export interface FeatureClient {
     Full: ComponentType<FeatureViewProps>;
     /**
      * Panels for the manifest's settings tabs that need one: `'general'`,
-     * `'sources'`, and any custom tab id. Generic tabs (`'notifications'`,
-     * `'permissions'`) need no panel.
+     * `'sources'`, `'encryption'`, and any custom tab id. Generic tabs
+     * (`'notifications'`, `'permissions'`) need no panel.
      */
-    settingsPanels?: Readonly<Record<string, ComponentType<SettingsPanelProps>>>;
+    // `never` as the id: a panel typed for numbers and one typed for strings
+    // are both assignable here (props are contravariant), and the shell, which
+    // holds a `number | string`, casts once at that boundary.
+    settingsPanels?: Readonly<Record<string, ComponentType<SettingsPanelProps<never>>>>;
     /**
-     * The compact topbar widget declared by `manifest.topbarWidget`.
-     *
-     * Rendered with NO props, on purpose: that is the security contract. The
-     * host hands the component nothing (no user, no stores, no other feature's
-     * state); everything it shows must come through YOUR feature's commands
-     * (`featureApi`), which the server authorizes against the caller's grants
-     * like any other call. The host also only mounts it for members whose role
-     * grants your feature. Freedom inside the box, nothing outside it.
+     * The compact topbar widget declared by `manifest.topbarWidget`. Rendered
+     * with NO props: everything it shows must come through YOUR feature's
+     * commands, which the server authorizes against the caller's grants. The
+     * host mounts it only for members whose role grants your feature.
      */
     TopbarWidget?: ComponentType;
     /**
@@ -63,4 +67,260 @@ export interface FeatureClient {
     preload?: boolean;
     /** Hold the password-encryption unlock alive while the full view is open. */
     holdSecrecy?: boolean;
+    /**
+     * Named contracts offered to the host's screens (see `sdk/providers.ts`),
+     * the client twin of `FeatureService.providers`. The app looks a provider
+     * up at render time and degrades cleanly when the module is absent.
+     */
+    providers?: Readonly<Record<string, unknown>>;
+}
+
+/**
+ * A monitored service, as the Uptime client provider hands it to the host.
+ * Deliberately a subset of the module's own contract: what a linked-service
+ * block needs, and nothing the module may want to change later.
+ */
+export interface UptimeLinkedService {
+    id: number;
+    name: string;
+    url: string;
+    enabled: boolean;
+    status: string;
+    lastCheckedAt: number | null;
+    ratio24h: number | null;
+    ratio7d: number | null;
+    ratio30d: number | null;
+}
+
+/** One bucket of a service's availability history. */
+export interface UptimeHistoryPoint {
+    at: number;
+    checks: number;
+    upChecks: number;
+    avgMs: number | null;
+    minMs: number | null;
+    maxMs: number | null;
+}
+
+export type UptimeHistoryResolution = 'raw' | 'hour' | 'day';
+
+/**
+ * What the Devices module offers the app's own screens (`DEVICES_CLIENT_PROVIDER`):
+ * the workspace's devices as a live store, the panel of one device (the home
+ * renders one view per placed device), and its compact tile. Without the
+ * module the home places no device and the topbar counts none.
+ */
+export interface DevicesClientProvider {
+    /** The active workspace's devices, refreshed by the `devices` live topic. */
+    useDevices(): { devices: readonly SdkDeviceSummary[]; loading: boolean; error: string | null };
+    refreshDevices(): void;
+    /** Forgets every loaded device (the app calls it when the session ends). */
+    resetDevices(): void;
+    DevicePanel: ComponentType<{ deviceId: string }>;
+    DeviceWidget: ComponentType<{ deviceId: string; hideStatus?: boolean }>;
+}
+
+/** What the app's screens need of a device: identity and liveness, never the report. */
+export interface SdkDeviceSummary {
+    id: string;
+    name: string;
+    online: boolean;
+    status: string;
+    platform: string;
+}
+
+/**
+ * What the Uptime module offers the host's screens under
+ * `UPTIME_CLIENT_PROVIDER`: the availability strip, the ratios, the history
+ * hook feeding the strip, the workspace's services, and the feature's own
+ * service dialog.
+ */
+export interface UptimeClientProvider {
+    /** The workspace's services, as `uptime.list` returns them. */
+    listServices(): Promise<readonly UptimeLinkedService[]>;
+    /**
+     * A service's history for the strip. `stamp` is what re-reads it (pass
+     * `service.lastCheckedAt`); no timer.
+     */
+    useServiceHistory(
+        id: number,
+        stamp: number | null
+    ): {
+        points: UptimeHistoryPoint[];
+        resolution: UptimeHistoryResolution;
+        axis: { from: number; to: number };
+    };
+    /** The availability strip over a window. */
+    StatusBars: ComponentType<{
+        points: UptimeHistoryPoint[];
+        from: number;
+        to: number;
+        resolution: UptimeHistoryResolution;
+        /** Rendered facing the legend (the ratios, typically). */
+        trailing?: ReactNode;
+    }>;
+    /** The three-window availability ratios of a service. */
+    Ratios: ComponentType<{ service: UptimeLinkedService; compact?: boolean }>;
+    /** The feature's service form: `service: null` declares a new one. */
+    ServiceDialog: ComponentType<{
+        open: boolean;
+        service: UptimeLinkedService | null;
+        onClose: () => void;
+        onSaved: (service: UptimeLinkedService) => void;
+    }>;
+}
+
+/**
+ * A database of the workspace, as the Databases client provider lists it for
+ * a project's "add a database" picker. Deliberately a subset of the module's
+ * own contract: what a picker shows, and nothing the module may change later.
+ */
+export interface DatabaseLinkedCandidate {
+    id: number;
+    name: string;
+    /** The engine as the module labels it (« MySQL », « PostgreSQL »). */
+    engineLabel: string;
+    /** How many projects of the workspace already use it. */
+    projectCount: number;
+}
+
+/**
+ * What the Databases module offers the host's screens under
+ * `DATABASE_CLIENT_PROVIDER`: the workspace's databases, a linked database
+ * rendered in full inside a project's tab, and the feature's own dialog.
+ */
+export interface DatabaseClientProvider {
+    /** The workspace's databases, as `database.list` returns them. */
+    listDatabases(): Promise<readonly DatabaseLinkedCandidate[]>;
+    /**
+     * A database linked to a project, shown in full: header (name, address,
+     * actions, its own settings button), state, alerts, table explorer. Loads
+     * itself by `database.get`, follows the feature's invalidations, and
+     * renders the host's "unlink" as its trailing action. Handles the
+     * explorer's expanded mode on its own.
+     */
+    LinkedDatabase: ComponentType<{ databaseId: number; canWrite: boolean; onUnlink: () => void }>;
+    /** The feature's database form, to declare a new database from a project. */
+    DatabaseDialog: ComponentType<{
+        open: boolean;
+        onClose: () => void;
+        onSaved: (databaseId: number) => void;
+    }>;
+}
+
+/**
+ * A deploy target of the workspace, as the Deploy client provider lists it
+ * for a project's "add a target" picker.
+ */
+export interface DeployLinkedCandidate {
+    id: number;
+    name: string;
+    /** The instance host, as the module labels it (« dokploy.example.com »). */
+    host: string;
+}
+
+/**
+ * What the Deploy module offers the host's screens under
+ * `DEPLOY_CLIENT_PROVIDER`: the workspace's targets, a linked target rendered
+ * in full inside a project's tab, and the feature's own dialog.
+ */
+export interface DeployClientProvider {
+    /** The workspace's targets, as `deploy.list` returns them. */
+    listTargets(): Promise<readonly DeployLinkedCandidate[]>;
+    /**
+     * A target linked to a project, shown in full: identity, last deployment,
+     * trigger, its own settings button. Loads itself by `deploy.get`, follows
+     * the feature's invalidations, and renders the host's "unlink" as its
+     * trailing action. `projectId` files a trigger in that project's timeline.
+     */
+    LinkedTarget: ComponentType<{
+        targetId: number;
+        projectId: number;
+        canWrite: boolean;
+        onUnlink: () => void;
+    }>;
+    /** The feature's target form, to declare a new target from a project. */
+    TargetDialog: ComponentType<{
+        open: boolean;
+        onClose: () => void;
+        onSaved: (targetId: number) => void;
+    }>;
+}
+
+/**
+ * A git repository of the workspace, as the Git client provider lists it for
+ * a project's "add a repository" picker.
+ */
+export interface GitLinkedCandidate {
+    id: number;
+    owner: string;
+    repo: string;
+}
+
+/**
+ * What the Git module offers the host's screens under `GIT_CLIENT_PROVIDER`:
+ * the workspace's repositories, a linked repository rendered in full inside a
+ * project's tab, and the feature's own dialog.
+ */
+export interface GitClientProvider {
+    /** The workspace's repositories, as `git.repoList` returns them. */
+    listRepos(): Promise<readonly GitLinkedCandidate[]>;
+    /**
+     * A repository linked to a project, shown in full: header (name, sync
+     * state, actions, its own settings button), graph and panels. Loads
+     * itself by `git.repoGet`, follows the feature's invalidations and the
+     * sync progress, and renders the host's "unlink" as its trailing action.
+     */
+    LinkedRepo: ComponentType<{ repoId: number; canWrite: boolean; onUnlink: () => void }>;
+    /** The feature's repository form, to declare a new repository from a project. */
+    RepoDialog: ComponentType<{
+        open: boolean;
+        onClose: () => void;
+        onSaved: (repoId: number) => void;
+    }>;
+}
+
+/** A tracked site of the workspace, as the Audience client provider lists it for a project's picker. */
+export interface AudienceLinkedCandidate {
+    id: number;
+    name: string;
+}
+
+/**
+ * What the Audience module offers the host's screens under
+ * `AUDIENCE_CLIENT_PROVIDER`: the workspace's sites, a linked site rendered
+ * in full inside a project's tab, and the feature's own dialog.
+ */
+export interface AudienceClientProvider {
+    /** The workspace's sites, as `audience.list` returns them. */
+    listSites(): Promise<readonly AudienceLinkedCandidate[]>;
+    /**
+     * A site linked to a project, shown in full: its sticky heading, actions
+     * (install, its own settings button), stats, funnels. Loads itself by
+     * `audience.get`, follows the feature's invalidations and the live beat,
+     * and renders the host's "unlink" as its trailing action.
+     */
+    LinkedSite: ComponentType<{ siteId: number; canWrite: boolean; onUnlink: () => void }>;
+    /** The feature's site form, to declare a new site from a project. */
+    SiteDialog: ComponentType<{
+        open: boolean;
+        onClose: () => void;
+        onSaved: (siteId: number) => void;
+    }>;
+}
+
+/**
+ * What the Mail module offers the host's screens under `MAIL_CLIENT_PROVIDER`:
+ * the ready senders (open tier, enabled) an email notification channel picks
+ * from, and the feature's own account dialog.
+ */
+export interface MailClientProvider {
+    /** The workspace's ready senders, as the module lists them. */
+    listSenders(): Promise<readonly { id: number; label: string; address: string }[]>;
+    /**
+     * The feature's account form (manual connection or OAuth consent), to
+     * declare a mailbox from the channel form. `onSaved` fires when a mailbox
+     * came out of it; the host re-lists to find which.
+     */
+    AccountDialog: ComponentType<{ open: boolean; onClose: () => void; onSaved: () => void }>;
 }

package/src/sdk/devb.ts

@@ -0,0 +1,120 @@
+import crypto from 'crypto';
+
+/**
+ * `DEVB` : le conteneur chiffré que CloudSync (blobs) et Backup (archives)
+ * partagent. Une seule définition parce que le format est figé : un octet de
+ * divergence et une sauvegarde ne se rouvre plus. Ne s'occupe que du FORMAT ;
+ * la clé est l'affaire de chaque module (`scripts/restore-backup.mjs` côté app
+ * relit ce format sans DevEye).
+ *
+ * v1, flux unique (lu, plus jamais écrit) :
+ *   magic 'DEVB' (4) | 0x01 (1) | nonce (12) | ciphertext | tag GCM (16)
+ * Un seul AES-256-GCM ; irreprenable après redémarrage, l'état du cipher ne se
+ * sérialise pas.
+ *
+ * v2, scellé par blocs (format d'écriture) :
+ *   magic 'DEVB' (4) | 0x02 (1) | nonce de base (12) | bloc* | bloc final
+ *   bloc = ciphertext ({@link BLOB_CHUNK_BYTES} octets de clair) | tag (16)
+ * Nonce = nonce de base XOR compteur, AAD = compteur (8) + marqueur de fin (1) :
+ * le marqueur ferme la troncature, le compteur le réordonnancement. La reprise
+ * d'un partiel relit les blocs complets en local pour reconstituer le SHA-256
+ * courant, sans retransmettre un octet.
+ */
+
+const BLOB_MAGIC = Buffer.from('DEVB');
+const BLOB_V1 = 0x01;
+const BLOB_V2 = 0x02;
+
+/** Longueur de l'en-tête (magic + version + nonce) et d'un tag GCM. */
+export const BLOB_HEADER_LEN = BLOB_MAGIC.length + 1 + 12;
+export const BLOB_TAG_LEN = 16;
+
+/**
+ * Clair par bloc en v2. 1 Mio : assez grand pour que le surcoût des tags soit
+ * négligeable (16 octets par Mio, soit 0,0015 %), assez petit pour qu'une
+ * reprise ne reperde jamais plus d'un Mio de travail.
+ */
+export const BLOB_CHUNK_BYTES = 1024 * 1024;
+/** Taille d'un bloc v2 complet sur le disque. */
+export const BLOB_CHUNK_SEALED = BLOB_CHUNK_BYTES + BLOB_TAG_LEN;
+
+export const BLOB_VERSION_STREAM = BLOB_V1;
+export const BLOB_VERSION_CHUNKED = BLOB_V2;
+
+/** L'en-tête d'un nouveau blob v2 (magic + version + nonce de base aléatoire). */
+export function createBlobHeader(): Buffer {
+    return Buffer.concat([BLOB_MAGIC, Buffer.from([BLOB_V2]), crypto.randomBytes(12)]);
+}
+
+/** Valide un en-tête et rend sa version + son nonce de base. */
+export function parseBlobHeader(header: Buffer): { version: number; nonce: Buffer } {
+    if (header.length !== BLOB_HEADER_LEN || !header.subarray(0, 4).equals(BLOB_MAGIC)) {
+        throw new Error('DEVB : blob corrompu (en-tête invalide)');
+    }
+    const version = header[4];
+    if (version !== BLOB_V1 && version !== BLOB_V2) {
+        throw new Error(`DEVB : version de blob inconnue (${version})`);
+    }
+    return { version, nonce: header.subarray(5, 17) };
+}
+
+/**
+ * Le nonce du bloc `index` : nonce de base XOR le compteur en big-endian sur
+ * les 8 derniers octets. Deux blobs n'ont jamais le même nonce de base (12
+ * octets aléatoires), donc jamais la même paire (clé, nonce) — la règle d'or
+ * de GCM tient.
+ */
+function chunkNonce(base: Buffer, index: number): Buffer {
+    const nonce = Buffer.from(base);
+    const counter = Buffer.alloc(8);
+    counter.writeBigUInt64BE(BigInt(index));
+    for (let i = 0; i < 8; i += 1) nonce[4 + i] ^= counter[i];
+    return nonce;
+}
+
+/** L'AAD d'un bloc : son rang, et s'il termine le blob. */
+function chunkAad(index: number, final: boolean): Buffer {
+    const aad = Buffer.alloc(9);
+    aad.writeBigUInt64BE(BigInt(index));
+    aad[8] = final ? 1 : 0;
+    return aad;
+}
+
+/** Scelle un bloc de clair en `ciphertext | tag`. */
+export function sealChunk(
+    key: Buffer,
+    base: Buffer,
+    index: number,
+    plain: Buffer,
+    final: boolean
+): Buffer {
+    const cipher = crypto.createCipheriv('aes-256-gcm', key, chunkNonce(base, index));
+    cipher.setAAD(chunkAad(index, final));
+    const body = Buffer.concat([cipher.update(plain), cipher.final()]);
+    return Buffer.concat([body, cipher.getAuthTag()]);
+}
+
+/**
+ * Ouvre un bloc scellé. Lève si le tag ne colle pas — donc si le contenu, son
+ * rang ou son statut de dernier bloc ont bougé.
+ */
+export function openChunk(
+    key: Buffer,
+    base: Buffer,
+    index: number,
+    sealed: Buffer,
+    final: boolean
+): Buffer {
+    if (sealed.length < BLOB_TAG_LEN) throw new Error('DEVB : bloc de blob tronqué');
+    const body = sealed.subarray(0, sealed.length - BLOB_TAG_LEN);
+    const tag = sealed.subarray(sealed.length - BLOB_TAG_LEN);
+    const decipher = crypto.createDecipheriv('aes-256-gcm', key, chunkNonce(base, index));
+    decipher.setAAD(chunkAad(index, final));
+    decipher.setAuthTag(tag);
+    return Buffer.concat([decipher.update(body), decipher.final()]);
+}
+
+/** Ouvre le déchiffrement d'un blob v1 (flux unique) depuis son en-tête. */
+export function openStreamDecipher(key: Buffer, nonce: Buffer): crypto.DecipherGCM {
+    return crypto.createDecipheriv('aes-256-gcm', key, nonce);
+}

package/src/sdk/manifest.test.ts

@@ -31,7 +31,6 @@ test('validateManifest rejects the classic mistakes', () => {
         assert.throws(() => validateManifest({ ...base, ...patch }), new RegExp(fragment));
     rejects({ label: '  ' }, 'empty label');
     rejects({ hasItems: true }, 'itemNoun');
-    rejects({ itemSegment: (id) => `item:${id}` }, 'itemSegment');
     rejects({ shareTier: 'open' }, "shareTier 'never'");
     rejects({ commandPrefix: 'x-demo.' }, 'commandPrefix');
     rejects(

package/src/sdk/manifest.ts

@@ -9,13 +9,8 @@ import {
 
 /**
  * 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).
  */
 
 /**
@@ -78,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'
+    /**
+     * 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`.
      */
-    | 'agents';
+    | '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 {
@@ -127,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;
@@ -152,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
@@ -186,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:
@@ -202,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)[];
@@ -233,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");
     }
@@ -263,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');
@@ -275,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 ?? [];
@@ -315,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} »`);