@camstack/types 1.2.585 → 1.2.587

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (78) hide show
  1. package/CHANGELOG.md +38 -1
  2. package/dist/addon.d.ts +2 -0
  3. package/dist/addon.js +21 -5
  4. package/dist/addon.mjs +18 -6
  5. package/dist/capabilities/camera-grid-layout.cap.d.ts +3 -5
  6. package/dist/capabilities/cap-method-absent.d.ts +19 -0
  7. package/dist/capabilities/device-manager.cap.d.ts +422 -0
  8. package/dist/capabilities/hero-layout.cap.d.ts +2 -2
  9. package/dist/capabilities/index.d.ts +11 -7
  10. package/dist/capabilities/network-link.cap.d.ts +10 -0
  11. package/dist/capabilities/notification-rules.cap.d.ts +70 -0
  12. package/dist/capabilities/power-source.cap.d.ts +20 -0
  13. package/dist/capabilities/recording-export.cap.d.ts +1 -0
  14. package/dist/capabilities/siren-duration.d.ts +45 -7
  15. package/dist/capabilities/siren.cap.d.ts +45 -2
  16. package/dist/capabilities/switch-settable.d.ts +15 -0
  17. package/dist/capabilities/switch.cap.d.ts +71 -0
  18. package/dist/capabilities/tags.cap.d.ts +42 -16
  19. package/dist/capabilities/terminal-session.cap.d.ts +9 -60
  20. package/dist/capabilities/videoclips.cap.d.ts +3 -0
  21. package/dist/capabilities/workload.cap.d.ts +655 -0
  22. package/dist/client.js +119 -6
  23. package/dist/client.mjs +119 -6
  24. package/dist/{composed-stable-id-RvQIEpqg.mjs → composed-stable-id-BBL71oUQ.mjs} +20 -0
  25. package/dist/{composed-stable-id-C3NfRTj8.js → composed-stable-id-CVbyajE5.js} +20 -0
  26. package/dist/composition/engine-hosted-blocks.d.ts +131 -0
  27. package/dist/composition/helpers/index.d.ts +1 -1
  28. package/dist/composition/helpers/spec.d.ts +56 -2
  29. package/dist/composition/index.d.ts +1 -0
  30. package/dist/device/base-device.d.ts +29 -0
  31. package/dist/device/cap-vocabulary/declaration.d.ts +12 -1
  32. package/dist/device/cap-vocabulary/index.d.ts +4 -4
  33. package/dist/device/cap-vocabulary/resolve.d.ts +47 -1
  34. package/dist/device/cap-vocabulary/types.d.ts +26 -1
  35. package/dist/device/declare-identifiers.d.ts +58 -0
  36. package/dist/device/device-control-resolution.d.ts +1 -1
  37. package/dist/device/device-icon.d.ts +7 -0
  38. package/dist/device/device-identifiers.d.ts +190 -0
  39. package/dist/device/device-management.d.ts +10 -0
  40. package/dist/device/device-type.d.ts +22 -2
  41. package/dist/device/hero/build-hero-model.d.ts +15 -0
  42. package/dist/device/hero/hero-fragment.d.ts +11 -0
  43. package/dist/device/hero/hero-layout.d.ts +1 -0
  44. package/dist/device/hero/hero-look.d.ts +12 -0
  45. package/dist/device/hero/hero-model.d.ts +4 -4
  46. package/dist/device/hero/hero-scene.d.ts +7 -0
  47. package/dist/device/index.d.ts +5 -1
  48. package/dist/enums/event-category.d.ts +8 -0
  49. package/dist/enums.js +1 -1
  50. package/dist/enums.mjs +1 -1
  51. package/dist/{event-category-d9kiqCqC.js → event-category-CE_VCE2G.js} +8 -0
  52. package/dist/{event-category-Dhcd0TRH.mjs → event-category-Hwx_JSCU.mjs} +8 -0
  53. package/dist/generated/addon-api.d.ts +106 -14
  54. package/dist/generated/addon-cap-facts.d.ts +1 -1
  55. package/dist/generated/cap-status-types.d.ts +3 -1
  56. package/dist/generated/cap-vocabulary.d.ts +1 -1
  57. package/dist/generated/capability-router-map.d.ts +5 -2
  58. package/dist/generated/collection-array-methods.d.ts +1 -1
  59. package/dist/generated/customize-catalog.d.ts +1 -1
  60. package/dist/generated/device-local-state.d.ts +3 -0
  61. package/dist/generated/device-proxy.d.ts +4 -1
  62. package/dist/generated/device-scoped-caps.d.ts +1 -1
  63. package/dist/generated/history-catalog.d.ts +2 -2
  64. package/dist/generated/method-access-map.d.ts +1 -1
  65. package/dist/generated/method-device-selectors.d.ts +2 -2
  66. package/dist/generated/runtime-state-durability.d.ts +1 -1
  67. package/dist/generated/system-proxy.d.ts +2 -2
  68. package/dist/{implemented-methods-C7ScGvEz.js → implemented-methods-ChtdIofW.js} +128 -1
  69. package/dist/{implemented-methods-C5FMXLGP.mjs → implemented-methods-u7ddjc-_.mjs} +57 -2
  70. package/dist/index.d.ts +7 -3
  71. package/dist/index.js +2086 -439
  72. package/dist/index.mjs +2027 -438
  73. package/dist/node.js +2 -2
  74. package/dist/node.mjs +2 -2
  75. package/dist/notification/timelapse-rule.d.ts +3 -0
  76. package/dist/{sleep-DwRtgB2i.js → sleep-CsZJsb8n.js} +692 -35
  77. package/dist/{sleep-Ch7Q7UtE.mjs → sleep-D6Pih0Qt.mjs} +669 -36
  78. package/package.json +1 -1
@@ -0,0 +1,131 @@
1
+ /**
2
+ * Engine-hosted blocks (planning#580): a Camera grid or a Terminal camera is a
3
+ * core block whose camera row `(composer, composed-<blockId>)` the composer
4
+ * owns, and whose camera caps an ENGINE (the camera-grid builtin, the Terminal
5
+ * addon) serves as a cross-addon native on that row (D663). The engine keeps no
6
+ * list of its own (D3): every pass it reads the blocks (`listCompositions`) and
7
+ * the composer's rows, and hosts what both name.
8
+ *
9
+ * Three pieces, shared by both engines:
10
+ *
11
+ * - `selectEngineHostedBlocks` — the blocks of one helper kind whose row
12
+ * exists. `not-loaded` is UNTRUSTED, never an empty list (D315/D49).
13
+ * - `HostedWithdrawalGate` — a hosted block is withdrawn only after two
14
+ * consecutive trusted reads agree it is gone (D49).
15
+ * - `hostEngineDevice` — build the engine's device on the foreign row through
16
+ * `loadContext` (D677) and withdraw exactly the natives it registered.
17
+ * - `sweepLegacyEngineRows` — remove the camera rows the engine declared
18
+ * itself before its cameras were blocks (no migration: the operator
19
+ * recreates them as blocks).
20
+ */
21
+ import type { CompositionListRead } from '../capabilities/core-blocks.cap.js';
22
+ import { type DeclaredDeviceRow, type DeclaredIntegrationRow } from '../device/declared-device.js';
23
+ import type { IScopedLogger } from '../interfaces/logging.js';
24
+ import type { DeviceConstructor, DeviceManagerApi } from '../device/device-context.js';
25
+ import type { IDevice } from '../device/device.js';
26
+ import type { Composition } from './composition.js';
27
+ import type { EngineHostedHelperKind, EngineHostedHelperSpec } from './helpers/spec.js';
28
+ /** A composer device row, as `deviceManager.listAll({ addonId: 'composer' })` lists it. */
29
+ export interface ComposerDeviceRow {
30
+ readonly id: number;
31
+ readonly stableId: string;
32
+ }
33
+ /** The spec of one engine-hosted helper kind. */
34
+ export type EngineHostedSpecOf<K extends EngineHostedHelperKind> = Extract<EngineHostedHelperSpec, {
35
+ readonly kind: K;
36
+ }>;
37
+ /** One block an engine serves, joined with the composer row that carries its camera. */
38
+ export interface EngineHostedBlock<S extends EngineHostedHelperSpec> {
39
+ readonly blockId: string;
40
+ readonly deviceId: number;
41
+ readonly stableId: string;
42
+ readonly name: string;
43
+ readonly enabled: boolean;
44
+ /** What `updateComposition` needs as `expectedUpdatedAt`. */
45
+ readonly updatedAt: number;
46
+ readonly composition: Composition;
47
+ readonly spec: S;
48
+ }
49
+ export type EngineHostedBlocksRead<S extends EngineHostedHelperSpec> = {
50
+ readonly kind: 'trusted';
51
+ readonly blocks: readonly EngineHostedBlock<S>[];
52
+ } | {
53
+ readonly kind: 'untrusted';
54
+ readonly reason: string;
55
+ };
56
+ /**
57
+ * The blocks of `kind` whose composer row exists. A block whose row the
58
+ * composer has not declared yet is left out: nothing can be hosted on it until
59
+ * its next apply, and the next pass picks it up.
60
+ */
61
+ export declare function selectEngineHostedBlocks<K extends EngineHostedHelperKind>(kind: K, compositions: CompositionListRead, composerRows: readonly ComposerDeviceRow[]): EngineHostedBlocksRead<EngineHostedSpecOf<K>>;
62
+ /**
63
+ * D49 for an engine's hosted set: a block missing from ONE trusted read is
64
+ * kept; a second consecutive trusted read that agrees withdraws it. An
65
+ * untrusted read is never fed here, so it neither counts nor resets.
66
+ */
67
+ export declare class HostedWithdrawalGate {
68
+ private misses;
69
+ /**
70
+ * `hosted`: what the engine serves now; `present`: what this trusted read
71
+ * names. Returns the ids to withdraw now, and the ids kept on a first miss.
72
+ */
73
+ judge(hosted: Iterable<string>, present: ReadonlySet<string>): {
74
+ readonly withdraw: readonly string[];
75
+ readonly held: readonly string[];
76
+ };
77
+ }
78
+ /** A device an engine built on a row it does not own. */
79
+ export interface HostedEngineDevice<D extends IDevice> {
80
+ readonly device: D;
81
+ /** Run the device's own teardown, then unregister every native it registered. */
82
+ withdraw(): Promise<void>;
83
+ }
84
+ /**
85
+ * Build `DeviceClass` on the composer's row `(stableId, id)`. The context is
86
+ * `loadContext` (D677: a caller that BUILDS a device hydrates its stored
87
+ * runtime state first); a kernel without it is refused by name rather than
88
+ * building on an empty state. The device is never `register`ed and its config
89
+ * never persisted: the row, its name and its lifetime are the composer's.
90
+ */
91
+ export declare function hostEngineDevice<D extends IDevice>(devices: DeviceManagerApi, row: ComposerDeviceRow, config: Record<string, unknown>, DeviceClass: DeviceConstructor<D>): Promise<HostedEngineDevice<D>>;
92
+ /** What the legacy sweep reads and removes through. */
93
+ export interface LegacyEngineRowsPorts {
94
+ readonly logger: IScopedLogger;
95
+ /** The engine's BARE addon id: the owner of its old rows. */
96
+ readonly addonId: string;
97
+ readonly devices: DeviceManagerApi;
98
+ readonly localNodeId?: string | undefined;
99
+ /** The integration the old rows were declared under; `null` when there is none. */
100
+ readonly getIntegration: (addonId: string) => Promise<DeclaredIntegrationRow | null>;
101
+ /** Every row the addon owns (`deviceManager.listAll({ addonId })`). Fallible. */
102
+ readonly listAddonRows: (addonId: string) => Promise<readonly DeclaredDeviceRow[]>;
103
+ }
104
+ /** `none`: the addon never declared an integration. `drained`: no old row was left to remove. */
105
+ export type LegacyEngineSweep = {
106
+ readonly kind: 'none';
107
+ } | {
108
+ readonly kind: 'swept';
109
+ readonly removed: readonly number[];
110
+ readonly drained: boolean;
111
+ };
112
+ /**
113
+ * Whether an engine may stop sweeping: only once a pass found no old row left.
114
+ * `none` is not done — a registry that has not answered the integration yet
115
+ * reads as null too, and the sweep is one indexed read per pass.
116
+ */
117
+ export declare function legacySweepDone(sweep: LegacyEngineSweep): boolean;
118
+ /**
119
+ * The legacy rows, one bounded batch at a time: only the rows under the old
120
+ * integration, ordered by id, at most `DECLARED_DEVICE_SWEEP_LIMIT` — a large
121
+ * leftover set drains over passes instead of being refused whole by the
122
+ * sweep's own bound.
123
+ */
124
+ export declare function legacyEngineRowsIndex(rows: readonly DeclaredDeviceRow[], integrationId: string): readonly DeclaredDeviceRow[];
125
+ /**
126
+ * Remove every camera row an engine declared itself before its cameras were
127
+ * blocks, unconditionally, through the declared sweep (`removeDevice` →
128
+ * tombstone, D865). No integration means nothing was ever declared, and
129
+ * nothing is minted to find out. A failed read throws: the caller retries.
130
+ */
131
+ export declare function sweepLegacyEngineRows(ports: LegacyEngineRowsPorts, integrationName: string): Promise<LegacyEngineSweep>;
@@ -10,4 +10,4 @@ export { type HistoryValue, type IntegralScale, type SeriesBefore, type SeriesKi
10
10
  export { type CalendarPeriod, type CalendarWindow, type HistoryRetention, type HistoryTier, type HistoryTierPlan, type OpenRange, type ResetPeriod, type RollingSpan, type RollingWindow, type StatisticWindow, CALENDAR_PERIODS, CalendarWindowSchema, DAY_MS, DEFAULT_HISTORY_RETENTION, historyRetentionFromSettings, HISTORY_FAST_MS, HISTORY_SLOW_MS, HISTORY_TIERS, HOUR_MS, MINUTE_MS, MIN_CUSTOM_MINUTES, RESET_PERIODS, ROLLING_SPANS, RollingWindowSchema, StatisticWindowSchema, integralCadenceMs, maxDurationMs, nextLocalMidnight, openReset, openStatistic, planResetTier, planStatisticTier, rollingDurationMs, statisticCadenceMs, } from './history-window.js';
11
11
  export { type HelperMemberFact, helperSaveProblems, } from './save.js';
12
12
  export { type SourcePick, type SourcePickAccept, type SourcePickFieldChoice, type SourcePickHistory, type SourcePickRequest, type MathSourceKind, sourcePickForHistory, sourcePickForMath, sourcePickAcceptsDevice, sourcePickForTemplate, } from './source-pick.js';
13
- export { ACTIVE_CRITERIA, AGGREGATE_REDUCERS, ActiveCriterionSchema, AggregateReducerSchema, BINARY_AGGREGATES, GROUP_TEMPLATE_IDS, ARITHMETIC_OPS, ArithmeticHelperSpecSchema, DERIVATIVE_UNITS, DerivativeHelperSpecSchema, EXPRESSION_OUTPUTS, ExpressionHelperSpecSchema, ThresholdHelperSpecSchema, GroupHelperSpecSchema, GroupTemplateIdSchema, HelperMemberSchema, HelperSpecSchema, INTEGRAL_OUTPUTS, IntegralHelperSpecSchema, MAX_HELPER_MEMBERS, helperMembers, isHistoryHelper, NUMERIC_AGGREGATES, StatisticHelperSpecSchema, type ActiveCriterion, type AggregateReducer, type BinaryAggregate, type ArithmeticHelperSpec, type ArithmeticOp, type DerivativeHelperSpec, type DerivativeUnit, type ExpressionHelperSpec, type ExpressionInput, type ExpressionOutput, type ThresholdHelperSpec, type GroupHelperSpec, type GroupTemplateId, type HelperMember, type HelperSpec, type HistoryHelperSpec, type IntegralHelperSpec, type IntegralOutput, type NumericAggregate, type StatisticHelperSpec, type StatisticStat, } from './spec.js';
13
+ export { ACTIVE_CRITERIA, AGGREGATE_REDUCERS, ActiveCriterionSchema, AggregateReducerSchema, BINARY_AGGREGATES, GROUP_TEMPLATE_IDS, ARITHMETIC_OPS, ArithmeticHelperSpecSchema, DERIVATIVE_UNITS, DerivativeHelperSpecSchema, EXPRESSION_OUTPUTS, ExpressionHelperSpecSchema, ThresholdHelperSpecSchema, GroupHelperSpecSchema, GroupTemplateIdSchema, HelperMemberSchema, HelperSpecSchema, INTEGRAL_OUTPUTS, IntegralHelperSpecSchema, MAX_HELPER_MEMBERS, helperMembers, helperDeviceRefs, isEngineHostedHelper, isHistoryHelper, ENGINE_HOSTED_HELPER_KINDS, GRID_PROFILES, DEFAULT_GRID_FPS, DEFAULT_GRID_PROFILES, newGridHelperSpec, GridCellSpecSchema, GridHelperSpecSchema, MAX_GRID_CELLS, GridRectSchema, TerminalHelperSpecSchema, type EngineHostedHelperKind, type EngineHostedHelperSpec, type GridCellSpec, type GridHelperSpec, type GridProfile, type GridRect, type TerminalHelperSpec, NUMERIC_AGGREGATES, StatisticHelperSpecSchema, type ActiveCriterion, type AggregateReducer, type BinaryAggregate, type ArithmeticHelperSpec, type ArithmeticOp, type DerivativeHelperSpec, type DerivativeUnit, type ExpressionHelperSpec, type ExpressionInput, type ExpressionOutput, type ThresholdHelperSpec, type GroupHelperSpec, type GroupTemplateId, type HelperMember, type HelperSpec, type HistoryHelperSpec, type IntegralHelperSpec, type IntegralOutput, type NumericAggregate, type StatisticHelperSpec, type StatisticStat, } from './spec.js';
@@ -5,7 +5,7 @@
5
5
  import { z } from 'zod';
6
6
  import { STATISTIC_STATS } from './history-math.js';
7
7
  import { type ResetPeriod, type RollingWindow, type StatisticWindow } from './history-window.js';
8
- import { CompositionSourceRefSchema } from '../source-ref.js';
8
+ import { type CompositionSourceRef, CompositionSourceRefSchema } from '../source-ref.js';
9
9
  /** A group may name more members than an expression call (the 16-arg cap). */
10
10
  export declare const MAX_HELPER_MEMBERS: number;
11
11
  export declare const GROUP_TEMPLATE_IDS: readonly ['temperature', 'humidity', 'pressure', 'illuminance', 'power', 'energy', 'battery', 'numeric', 'motion', 'contact', 'leak', 'smoke', 'occupancy', 'binary', 'switch', 'light', 'fan', 'cover', 'valve', 'lock', 'media-player', 'climate'];
@@ -98,10 +98,64 @@ export type DerivativeHelperSpec = {
98
98
  readonly source: HelperMember;
99
99
  };
100
100
  export declare const DerivativeHelperSpecSchema: z.ZodType<DerivativeHelperSpec>;
101
- export type HelperSpec = GroupHelperSpec | StatisticHelperSpec | IntegralHelperSpec | ThresholdHelperSpec | ArithmeticHelperSpec | ExpressionHelperSpec | DerivativeHelperSpec;
101
+ /** The stream profiles a camera grid can publish. */
102
+ export declare const GRID_PROFILES: readonly ['high', 'mid', 'low'];
103
+ export type GridProfile = (typeof GRID_PROFILES)[number];
104
+ export declare const MAX_GRID_CELLS: number;
105
+ export type GridRect = {
106
+ readonly x: number;
107
+ readonly y: number;
108
+ readonly width: number;
109
+ readonly height: number;
110
+ };
111
+ /** A rectangle in normalized [0,1] coordinates of whatever contains it. */
112
+ export declare const GridRectSchema: z.ZodType<GridRect>;
113
+ /**
114
+ * One grid cell: a source camera (by its addon-facing identity, never a
115
+ * numeric id), the part of its picture taken, and where it lands on the canvas.
116
+ */
117
+ export type GridCellSpec = {
118
+ readonly source: CompositionSourceRef;
119
+ readonly region: GridRect;
120
+ readonly cell: GridRect;
121
+ };
122
+ export declare const GridCellSpecSchema: z.ZodType<GridCellSpec>;
123
+ /**
124
+ * A camera grid (planning#580). The composer declares its camera
125
+ * (`composed-<blockId>`); the camera-grid engine serves the camera caps on it.
126
+ * No canvas size: it is derived from the cells and the sources.
127
+ */
128
+ export type GridHelperSpec = {
129
+ readonly kind: 'grid';
130
+ readonly fps: number;
131
+ readonly publishedProfiles: readonly GridProfile[];
132
+ readonly cells: readonly GridCellSpec[];
133
+ };
134
+ export declare const GridHelperSpecSchema: z.ZodType<GridHelperSpec>;
135
+ /** A new grid: no cells yet, 10 fps, publishing the mid and low profiles. */
136
+ export declare const DEFAULT_GRID_FPS: number;
137
+ export declare const DEFAULT_GRID_PROFILES: readonly GridProfile[];
138
+ export declare function newGridHelperSpec(): GridHelperSpec;
139
+ /**
140
+ * A Terminal camera (planning#580): the camera of one Terminal, created on the
141
+ * Terminal page. The composer declares the camera; addon-terminal serves it.
142
+ */
143
+ export type TerminalHelperSpec = {
144
+ readonly kind: 'terminal';
145
+ readonly terminalId: string;
146
+ };
147
+ export declare const TerminalHelperSpecSchema: z.ZodType<TerminalHelperSpec>;
148
+ export type HelperSpec = GroupHelperSpec | StatisticHelperSpec | IntegralHelperSpec | ThresholdHelperSpec | ArithmeticHelperSpec | ExpressionHelperSpec | DerivativeHelperSpec | GridHelperSpec | TerminalHelperSpec;
102
149
  export declare const HelperSpecSchema: z.ZodType<HelperSpec>;
103
150
  /** The kinds the composer runs from device history, on a schedule. */
104
151
  export type HistoryHelperSpec = StatisticHelperSpec | IntegralHelperSpec | DerivativeHelperSpec;
105
152
  export declare function isHistoryHelper(spec: HelperSpec): spec is HistoryHelperSpec;
106
153
  /** Every member a helper reads. A group has many; the others have one. */
107
154
  export declare function helperMembers(spec: HelperSpec): readonly HelperMember[];
155
+ /** The kinds whose camera an engine serves on the composer's row (planning#580). */
156
+ export declare const ENGINE_HOSTED_HELPER_KINDS: readonly ['grid', 'terminal'];
157
+ export type EngineHostedHelperKind = (typeof ENGINE_HOSTED_HELPER_KINDS)[number];
158
+ export type EngineHostedHelperSpec = GridHelperSpec | TerminalHelperSpec;
159
+ export declare function isEngineHostedHelper(spec: HelperSpec): spec is EngineHostedHelperSpec;
160
+ /** The devices a helper depends on without reading a field of them: a grid's cell sources. */
161
+ export declare function helperDeviceRefs(spec: HelperSpec): readonly CompositionSourceRef[];
@@ -6,6 +6,7 @@ export * from './composable-caps.js';
6
6
  export * from './helpers/index.js';
7
7
  export * from './actuator-running.js';
8
8
  export * from './composition.js';
9
+ export * from './engine-hosted-blocks.js';
9
10
  export * from './composition-events.js';
10
11
  export * from './composition-graph.js';
11
12
  export * from './composition-items.js';
@@ -8,12 +8,21 @@ import type { ConfigUISchemaWithValues } from '../interfaces/config-ui.js';
8
8
  import type { CapabilityDefinition, InferRuntimeState } from '../capabilities/capability-definition.js';
9
9
  import { type DeviceLocalState } from '../generated/device-local-state.js';
10
10
  import { type SourceInfo } from './source-info.js';
11
+ import { type DeclareIdentifiersOptions, type DeclareIdentifiersResult } from './declare-identifiers.js';
12
+ import type { RawDeviceIdentifiers } from './device-identifiers.js';
11
13
  import { type ErrorStatus } from '../capabilities/error.cap.js';
12
14
  import type { CustomActionSpec } from '../capabilities/custom-actions.js';
15
+ /**
16
+ * Who writes a device's base slices (`device-status`, `feature-probe`): the
17
+ * device itself, or another process (planning#580).
18
+ */
19
+ export type DeviceStatusOwnership = 'own' | 'external';
13
20
  export declare abstract class BaseDevice<T extends z.ZodObject<z.core.$ZodLooseShape> = z.ZodObject<z.ZodRawShape>> implements IDevice {
14
21
  readonly id: number;
15
22
  readonly stableId: string;
16
23
  readonly type: DeviceType;
24
+ /** True when another process owns the base slices (`options.deviceStatus: 'external'`). */
25
+ private readonly statusIsExternal;
17
26
  readonly name: string;
18
27
  readonly parentDeviceId: number | null;
19
28
  readonly role?: DeviceRole;
@@ -102,6 +111,14 @@ export declare abstract class BaseDevice<T extends z.ZodObject<z.core.$ZodLooseS
102
111
  type: DeviceType;
103
112
  /** Optional semantic role within parent — see `DeviceRole`. */
104
113
  role?: DeviceRole;
114
+ /**
115
+ * `external`: another process serves this row's base slices,
116
+ * `device-status` and `feature-probe` (an engine hosting caps on a row
117
+ * it does not own, planning#580). This device then registers neither
118
+ * native, seeds nothing, and `markOnline` / the default `onProbe` are
119
+ * no-ops — one writer per slice.
120
+ */
121
+ deviceStatus?: DeviceStatusOwnership;
105
122
  });
106
123
  private readonly deviceActions;
107
124
  /** Declare a device custom action + its typed handler. Idempotent per name. */
@@ -154,6 +171,18 @@ export declare abstract class BaseDevice<T extends z.ZodObject<z.core.$ZodLooseS
154
171
  * via the `DeviceSourceInfoChanged` event without polling.
155
172
  */
156
173
  protected updateSourceInfo(patch: Partial<SourceInfo>): Promise<void>;
174
+ /**
175
+ * Declare this device's identifiers (D1059): MAC(s), serial, vendor uid,
176
+ * machine uuid, hostname, IP — what a later step matches across integrations.
177
+ * Normalises `raw` (`normaliseIdentifiers`), logs every refused value, and
178
+ * writes the result through `device-manager.setIdentifiers`, which accepts it
179
+ * only from the provider that owns this device. Each kind it carries replaces
180
+ * the stored one and each kind it lacks is removed — except the kinds listed in
181
+ * `options.unread` (reads that FAILED), which keep their stored value. Pass
182
+ * everything read in one call; a call where every kind is unread writes
183
+ * nothing. Best-effort: never throws.
184
+ */
185
+ protected declareIdentifiers(raw: RawDeviceIdentifiers, options?: DeclareIdentifiersOptions): Promise<DeclareIdentifiersResult>;
157
186
  /**
158
187
  * Re-publish the device's current `features` array to the persisted
159
188
  * meta blob. Drivers call this after a probe finishes when the live
@@ -24,7 +24,7 @@
24
24
  * every one of those names against the cap definition, and
25
25
  * `check-cap-vocabulary` checks values against the Zod schemas.
26
26
  */
27
- import type { L10n, LooseVocabEffect, LooseVocabOffer, LooseVocabOverrides, LooseVocabStateTrigger, VocabEffectValue, VocabEventTrigger, VocabIcon } from './types.js';
27
+ import type { LooseVocabActionGate, L10n, LooseVocabEffect, LooseVocabOffer, LooseVocabOverrides, LooseVocabStateTrigger, VocabEffectValue, VocabEventTrigger, VocabIcon } from './types.js';
28
28
  /** The operator-supplied keys of a method input (`deviceId` is the target). */
29
29
  export type MethodActionArgs<TInput> = TInput extends object ? Omit<TInput, 'deviceId'> : Record<never, never>;
30
30
  /** An open arg of a method action, keyed by the method's own input. */
@@ -43,6 +43,14 @@ export type MethodActionEffect<TKey extends string = string> = {
43
43
  readonly field: string;
44
44
  readonly fromArg: TKey;
45
45
  };
46
+ /**
47
+ * When a device is offered an action: a read method of the same cap, and the
48
+ * boolean field of its answer that must not be `false`. Only an ANSWERED
49
+ * `false` withdraws the action (D315) — a provider without the method, a read
50
+ * that failed or is still pending keeps it offered. `switch.on` reads
51
+ * `getOptions().supportsSetState`: a switch that only reports offers no on/off.
52
+ */
53
+ export type MethodActionGate = LooseVocabActionGate;
46
54
  /**
47
55
  * One operator-facing action declared on the method it calls. `TInput` is the
48
56
  * method's Zod input; the action's `method` is the key the method is declared
@@ -62,6 +70,8 @@ export interface MethodActionDecl<TInput = Readonly<Record<string, unknown>>> {
62
70
  readonly openArgs?: readonly MethodActionOpenArg<keyof MethodActionArgs<TInput> & string>[];
63
71
  /** The state this action leads to, when it is one. */
64
72
  readonly effect?: MethodActionEffect<keyof MethodActionArgs<TInput> & string>;
73
+ /** When the device is offered it at all — absent = always ({@link MethodActionGate}). */
74
+ readonly offeredWhen?: MethodActionGate;
65
75
  }
66
76
  /** A method action as codegen reads it off a method schema, string-keyed. */
67
77
  export interface LooseMethodActionDecl {
@@ -72,6 +82,7 @@ export interface LooseMethodActionDecl {
72
82
  readonly args?: Readonly<Record<string, unknown>>;
73
83
  readonly openArgs?: readonly MethodActionOpenArg[];
74
84
  readonly effect?: LooseVocabEffect;
85
+ readonly offeredWhen?: MethodActionGate;
75
86
  }
76
87
  /** What a declared cap event is to an automation: a trigger, or an excuse. */
77
88
  export type EventVocabularyDecl = {
@@ -2,14 +2,14 @@
2
2
  * The cap vocabulary (D920) — what every capability lets an operator DO to a
3
3
  * device and WATCH it for, in one cap-keyed map generated from the caps (D1050).
4
4
  */
5
- export type { ResolvedBooleanTrigger, ResolvedEnumTrigger, ResolvedEnumValue, ResolvedEventTrigger, ResolvedNumericTrigger, ResolvedValueTrigger, ResolvedVocabAction, ResolvedVocabTrigger, VocabBindingsInput, } from './resolve.js';
6
- export { actionsForDevice, deviceOffersActions, renderVocabPhrase, triggersForDevice, } from './resolve.js';
5
+ export type { ResolvedBooleanTrigger, ResolvedEnumTrigger, ResolvedEnumValue, ResolvedEventTrigger, ResolvedNumericTrigger, ResolvedValueTrigger, ActionGateAnswer, ActionGateAnswerOf, DynamicOfferAnswer, DynamicOfferAnswerOf, ResolvedVocabAction, ResolvedVocabTrigger, VocabBindingsInput, } from './resolve.js';
6
+ export { actionGateAnswerFrom, actionOfferedWith, actionsForDevice, deviceOffersActions, offeredActionsWith, renderVocabPhrase, triggersForDevice, } from './resolve.js';
7
7
  export type { ActionEffect, IndexedVocabAction, VocabActionRefusal, VocabCall, } from './action-index.js';
8
8
  export { actionEffect, allVocabActions, assertDeviceOffers, findVocabAction, VocabActionError, vocabActionIdFor, vocabCall, } from './action-index.js';
9
9
  export type { CommandEffect } from './command-catalog.js';
10
10
  export { auditedFields, commandEffect, isCommand } from './command-catalog.js';
11
11
  export { VOCAB_TEMPLATES } from './templates.js';
12
- export type { ActionArgKey, ActionArgs, BooleanOffer, CapEventName, CapMethodName, CapStatusField, CapVocabularyEntry, CapVocabularyMap, DeviceCapVocabulary, DeviceVocabCapName, DynamicOffer, EnumOffer, EnumStateValue, L10n, LooseCapVocabularyEntry, LooseDynamicOffer, LooseVocabAction, LooseVocabEffect, LooseVocabOffer, LooseVocabOpenArg, LooseVocabStateTrigger, NumberOffer, SystemCapVocabulary, SystemVocabCapName, TextOffer, VocabAction, VocabCapName, VocabChoice, VocabEffectFor, VocabEffectValue, VocabEventTrigger, VocabIcon, VocabLocale, VocabOffer, VocabOpenArg, VocabStateTrigger, } from './types.js';
12
+ export type { ActionArgKey, ActionArgs, BooleanOffer, CapEventName, CapMethodName, CapNestedNumericPath, CapStatusField, CapVocabularyEntry, CapVocabularyMap, DeviceCapVocabulary, DeviceVocabCapName, DynamicOffer, EnumOffer, EnumStateValue, L10n, LooseCapVocabularyEntry, LooseDynamicOffer, LooseVocabAction, LooseVocabActionGate, LooseVocabEffect, LooseVocabOffer, LooseVocabOpenArg, LooseVocabStateTrigger, NumberOffer, SystemCapVocabulary, SystemVocabCapName, TextOffer, VocabAction, VocabCapName, VocabChoice, VocabEffectFor, VocabEffectValue, VocabEventTrigger, VocabIcon, VocabLocale, VocabOffer, VocabOpenArg, VocabStateTrigger, } from './types.js';
13
13
  export { CAP_VOCABULARY, CAP_VOCABULARY_BY_NAME } from './vocabulary.js';
14
- export type { CapVocabularyDecl, DeviceCapVocabularyDecl, EventVocabularyDecl, LooseMethodActionDecl, MethodActionArgs, MethodActionDecl, MethodActionEffect, MethodActionOpenArg, SystemCapVocabularyDecl, } from './declaration.js';
14
+ export type { CapVocabularyDecl, DeviceCapVocabularyDecl, EventVocabularyDecl, LooseMethodActionDecl, MethodActionArgs, MethodActionDecl, MethodActionEffect, MethodActionGate, MethodActionOpenArg, SystemCapVocabularyDecl, } from './declaration.js';
15
15
  export { NOT_A_DEVICE } from './system-reasons.js';
@@ -11,7 +11,7 @@
11
11
  import type { CapabilityMethodAccess } from '../../capabilities/capability-definition.js';
12
12
  import type { EventCategory } from '../../enums/event-category.js';
13
13
  import type { DeviceBinding, DeviceBindingEntry } from '../device-binding.js';
14
- import type { L10n, LooseDynamicOffer, LooseVocabOpenArg, VocabIcon, VocabLocale } from './types.js';
14
+ import type { L10n, LooseDynamicOffer, LooseVocabActionGate, LooseVocabOpenArg, VocabIcon, VocabLocale } from './types.js';
15
15
  /** A device's caps, however the caller holds them. */
16
16
  export type VocabBindingsInput = DeviceBinding | readonly DeviceBindingEntry[] | readonly string[];
17
17
  /** One action a device can be made to do — the wire is `{ cap, method, args }`. */
@@ -28,6 +28,8 @@ export interface ResolvedVocabAction {
28
28
  readonly openArgs: readonly LooseVocabOpenArg[];
29
29
  /** The method's access tier (METHOD_ACCESS_MAP). */
30
30
  readonly access: CapabilityMethodAccess;
31
+ /** The read that decides whether a device is offered it at all; null = always. */
32
+ readonly offeredWhen: LooseVocabActionGate | null;
31
33
  }
32
34
  interface ResolvedTriggerBase {
33
35
  readonly id: string;
@@ -98,6 +100,50 @@ export declare function actionsForDevice(bindings: VocabBindingsInput, deviceTyp
98
100
  * device search and the command picker share.
99
101
  */
100
102
  export declare function deviceOffersActions(bindings: VocabBindingsInput, actionIds: readonly string[], mode?: 'any' | 'all', deviceType?: string): boolean;
103
+ /**
104
+ * What a device answered for the list a `dynamic` offer reads. `failed` and
105
+ * `pending` are unknown, never "none" (D315); only `answered` carries a count.
106
+ */
107
+ export type DynamicOfferAnswer = {
108
+ readonly kind: 'pending';
109
+ } | {
110
+ readonly kind: 'failed';
111
+ } | {
112
+ readonly kind: 'answered';
113
+ readonly choiceCount: number;
114
+ };
115
+ /** The answer for one dynamic offer of an action of `cap` on the device at hand. */
116
+ export type DynamicOfferAnswerOf = (cap: string, offer: LooseDynamicOffer) => DynamicOfferAnswer;
117
+ /**
118
+ * What a device answered for the read an action's `offeredWhen` names.
119
+ * `failed` and `pending` are unknown, never "closed" (D315).
120
+ */
121
+ export type ActionGateAnswer = {
122
+ readonly kind: 'pending';
123
+ } | {
124
+ readonly kind: 'failed';
125
+ } | {
126
+ readonly kind: 'answered';
127
+ readonly open: boolean;
128
+ };
129
+ /** The answer for one action gate of `cap` on the device at hand. */
130
+ export type ActionGateAnswerOf = (cap: string, gate: LooseVocabActionGate) => ActionGateAnswer;
131
+ /**
132
+ * A gate's answer from what its read returned: closed only when the answer is
133
+ * an object whose `field` is `false`. A shape that is not an object is not an
134
+ * answer — it reads as `failed` and keeps the action offered.
135
+ */
136
+ export declare function actionGateAnswerFrom(raw: unknown, gate: LooseVocabActionGate): ActionGateAnswer;
137
+ /**
138
+ * Whether one device is offered an action, given what it answered: withdrawn
139
+ * when its `offeredWhen` read ANSWERED `false` (a switch that only reports has
140
+ * no on/off), or when a dynamic list its arguments read ANSWERED empty (a
141
+ * siren that counts no plays has nothing to sound N times). A read that failed
142
+ * or is pending keeps it offered.
143
+ */
144
+ export declare function actionOfferedWith(action: Pick<ResolvedVocabAction, 'cap' | 'openArgs' | 'offeredWhen'>, answerOf: DynamicOfferAnswerOf, gateOf?: ActionGateAnswerOf): boolean;
145
+ /** One device's actions, minus those {@link actionOfferedWith} withdraws. */
146
+ export declare function offeredActionsWith<A extends Pick<ResolvedVocabAction, 'cap' | 'openArgs' | 'offeredWhen'>>(actions: readonly A[], answerOf: DynamicOfferAnswerOf, gateOf?: ActionGateAnswerOf): readonly A[];
101
147
  /**
102
148
  * The triggers a device can be watched for — its state fields, then the bus
103
149
  * events it emits — phrased for its type and role.
@@ -69,6 +69,19 @@ type StatusOf<C extends VocabCapName> = CapDef<C> extends {
69
69
  } ? z.output<R> : never;
70
70
  /** A top-level status field of cap `C`. */
71
71
  export type CapStatusField<C extends VocabCapName> = [StatusOf<C>] extends [never] ? never : keyof StatusOf<C> & string;
72
+ /** The keys of `T` whose value is a number (nullable / optional allowed). */
73
+ type NumericKeysOf<T> = {
74
+ [K in keyof T & string]-?: NonNullable<T[K]> extends number ? K : never;
75
+ }[keyof T & string];
76
+ /**
77
+ * A number one object below the top of cap `C`'s status, by its dotted path
78
+ * (`resources.cpuPercent`). The rule runtime reads dotted paths (`readField`,
79
+ * the condition mirror) and the unit resolver finds their quantity, so a
80
+ * reading grouped under an object is a threshold trigger like a top-level one.
81
+ */
82
+ export type CapNestedNumericPath<C extends VocabCapName> = [StatusOf<C>] extends [never] ? never : {
83
+ [K in keyof StatusOf<C> & string]-?: NonNullable<StatusOf<C>[K]> extends readonly unknown[] ? never : NonNullable<StatusOf<C>[K]> extends object ? `${K}.${NumericKeysOf<NonNullable<StatusOf<C>[K]>>}` : never;
84
+ }[keyof StatusOf<C> & string];
72
85
  /** An event name declared by cap `C`. */
73
86
  export type CapEventName<C extends VocabCapName> = CapDef<C> extends {
74
87
  readonly events: infer E;
@@ -203,6 +216,11 @@ export interface VocabActionFor<C extends VocabCapName, M extends CapMethodName<
203
216
  readonly openArgs?: readonly VocabOpenArg<C, ActionArgKey<C, M>>[];
204
217
  /** The state this action leads to, when it is one (see {@link VocabEffectFor}). */
205
218
  readonly effect?: VocabEffectFor<C, M>;
219
+ /** When a device is offered it at all: a read of this cap answering `false` at `field` withdraws it. */
220
+ readonly offeredWhen?: {
221
+ readonly method: CapMethodName<C>;
222
+ readonly field: string;
223
+ };
206
224
  }
207
225
  /** Any action of cap `C`, discriminated by `method`. */
208
226
  export type VocabAction<C extends VocabCapName> = {
@@ -221,7 +239,8 @@ export interface BooleanStateTrigger<C extends VocabCapName> {
221
239
  /** A number: rises above / falls below / changes by, with a unit. */
222
240
  export interface NumericStateTrigger<C extends VocabCapName> {
223
241
  readonly kind: 'numeric';
224
- readonly field: CapStatusField<C>;
242
+ /** A top-level field, or a number nested one object down ({@link CapNestedNumericPath}). */
243
+ readonly field: CapStatusField<C> | CapNestedNumericPath<C>;
225
244
  /** The quantity WITH its article, as it reads in a sentence ("the temperature" / "la temperatura"). */
226
245
  readonly quantity: L10n;
227
246
  readonly label: L10n;
@@ -397,6 +416,12 @@ export interface LooseVocabAction {
397
416
  readonly args?: Readonly<Record<string, unknown>>;
398
417
  readonly openArgs?: readonly LooseVocabOpenArg[];
399
418
  readonly effect?: LooseVocabEffect;
419
+ readonly offeredWhen?: LooseVocabActionGate;
420
+ }
421
+ /** When a device is offered an action, string-keyed (`MethodActionGate`). */
422
+ export interface LooseVocabActionGate {
423
+ readonly method: string;
424
+ readonly field: string;
400
425
  }
401
426
  /** A boolean state trigger, string-keyed. */
402
427
  export interface LooseBooleanStateTrigger {
@@ -0,0 +1,58 @@
1
+ /**
2
+ * The provider side of `device-manager.setIdentifiers` (D1059): normalise what a
3
+ * driver read, log what was refused, send the declaration. `BaseDevice.
4
+ * declareIdentifiers` calls it for a device; a provider module that holds only a
5
+ * device id (a metadata populator) calls it directly with `ctx.api`.
6
+ *
7
+ * Best-effort like every other device-meta write from a driver: a failure is
8
+ * logged with `tags: { deviceId }` and answered as an outcome, never thrown, so a
9
+ * device boot never fails on it.
10
+ */
11
+ import type { IScopedLogger } from '../interfaces/logging.js';
12
+ import { type DeviceIdentifierKey, type DeviceIdentifiers, type NormaliseIdentifiersOptions, type RawDeviceIdentifiers } from './device-identifiers.js';
13
+ /** The input `device-manager.setIdentifiers` takes. */
14
+ export interface SetIdentifiersInput {
15
+ readonly deviceId: number;
16
+ readonly identifiers: DeviceIdentifiers | null;
17
+ /** Kinds whose read FAILED this time: the stored value is kept. */
18
+ readonly unread?: readonly DeviceIdentifierKey[];
19
+ }
20
+ /** The slice of the generated `ctx.api.deviceManager.setIdentifiers` this helper uses. */
21
+ export interface IdentifiersWriter {
22
+ mutate(input: SetIdentifiersInput): Promise<unknown>;
23
+ }
24
+ export interface DeclareIdentifiersDeps {
25
+ readonly deviceId: number;
26
+ readonly logger: IScopedLogger;
27
+ /** `ctx.api.deviceManager?.setIdentifiers`; absent when the device-manager is not reachable. */
28
+ readonly writer: IdentifiersWriter | undefined;
29
+ }
30
+ /**
31
+ * - `declared` — written (or already equal to what is stored);
32
+ * - `nothing-to-declare` — every kind is `unread`; NOTHING is written, so a probe
33
+ * that read nothing never erases an earlier declaration. A declaration that
34
+ * carries no value but READ some kinds is still sent: those kinds were read and
35
+ * found absent, and are removed;
36
+ * - `unavailable` — no device-manager to write to;
37
+ * - `failed` — the write was refused or threw (logged).
38
+ */
39
+ export type DeclareIdentifiersOutcome = 'declared' | 'nothing-to-declare' | 'unavailable' | 'failed';
40
+ export interface DeclareIdentifiersResult {
41
+ readonly outcome: DeclareIdentifiersOutcome;
42
+ readonly identifiers: DeviceIdentifiers;
43
+ }
44
+ export interface DeclareIdentifiersOptions extends NormaliseIdentifiersOptions {
45
+ /**
46
+ * Kinds the provider TRIED to read and could not (a probe threw, a session has
47
+ * not answered yet). Their stored values are kept; every other kind is replaced
48
+ * by this declaration, and a kind absent from it is removed. Never list a kind
49
+ * that was read and found absent — that is what removes a stale value.
50
+ */
51
+ readonly unread?: readonly DeviceIdentifierKey[];
52
+ }
53
+ /**
54
+ * Normalise `raw` and declare it: every kind it carries replaces the stored one,
55
+ * every kind it lacks is removed, except the kinds in `options.unread` (a failed
56
+ * read keeps what was stored) — pass everything the provider read in one call.
57
+ */
58
+ export declare function declareDeviceIdentifiers(deps: DeclareIdentifiersDeps, raw: RawDeviceIdentifiers, options?: DeclareIdentifiersOptions): Promise<DeclareIdentifiersResult>;
@@ -5,7 +5,7 @@ import { DeviceType } from './device-type.js';
5
5
  * kind can back several device types (`'switch'` ← Switch + Siren, `'sensor'`
6
6
  * ← Sensor + Presence, `'dummy'` ← every placeholder/non-controllable type).
7
7
  */
8
- export type DeviceControlKind = 'cover' | 'valve' | 'humidifier' | 'water-heater' | 'switch' | 'light' | 'fan' | 'sensor' | 'thermostat' | 'climate' | 'button' | 'update' | 'lock' | 'media-player' | 'alarm' | 'control' | 'weather' | 'vacuum' | 'lawn-mower' | 'image' | 'pet-feeder' | 'pet-fountain' | 'heater' | 'dishwasher' | 'appliance' | 'script' | 'automation' | 'energy-system' | 'dummy';
8
+ export type DeviceControlKind = 'cover' | 'valve' | 'humidifier' | 'water-heater' | 'switch' | 'light' | 'fan' | 'sensor' | 'thermostat' | 'climate' | 'button' | 'update' | 'lock' | 'media-player' | 'alarm' | 'control' | 'weather' | 'vacuum' | 'lawn-mower' | 'image' | 'pet-feeder' | 'pet-fountain' | 'heater' | 'dishwasher' | 'appliance' | 'script' | 'automation' | 'energy-system' | 'workload' | 'dummy';
9
9
  /**
10
10
  * Exhaustive `DeviceType` → `DeviceControlKind` map. Omitting a new enum member
11
11
  * fails the build here (the single place the type→kind decision is encoded).
@@ -24,6 +24,7 @@ export declare const DEVICE_TYPE_ICON: {
24
24
  readonly climate: 'thermometer';
25
25
  readonly "heat-pump": 'flame';
26
26
  readonly "energy-system": 'solar-panel';
27
+ readonly workload: 'server';
27
28
  readonly button: 'circle-dot';
28
29
  readonly "event-emitter": 'zap';
29
30
  readonly update: 'refresh-cw';
@@ -78,6 +79,7 @@ export declare const DEVICE_ROLE_ICON: {
78
79
  readonly "switch-heater": 'flame';
79
80
  readonly "switch-fan": 'fan';
80
81
  readonly "switch-light": 'lightbulb';
82
+ readonly "poe-port": 'ethernet-port';
81
83
  readonly "climate-ac": 'air-vent';
82
84
  readonly "climate-thermostat": 'thermometer';
83
85
  readonly "climate-floor": 'waves';
@@ -123,6 +125,11 @@ export declare const DEVICE_ROLE_ICON: {
123
125
  readonly "email-notifier": 'mail';
124
126
  readonly "generic-notifier": 'bell';
125
127
  readonly "ir-transmitter": 'radio-tower';
128
+ readonly vm: 'monitor';
129
+ readonly "app-container": 'container';
130
+ readonly lxc: 'box';
131
+ readonly app: 'app-window';
132
+ readonly host: 'server';
126
133
  };
127
134
  /** Every icon a device can be drawn with — a subset of the catalog the glyph tables must cover. */
128
135
  export type DeviceIconKey = (typeof DEVICE_TYPE_ICON)[DeviceType] | (typeof DEVICE_ROLE_ICON)[DeviceRole];