@camstack/types 1.2.586 → 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 (75) hide show
  1. package/CHANGELOG.md +27 -0
  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 +9 -5
  10. package/dist/capabilities/network-link.cap.d.ts +10 -0
  11. package/dist/capabilities/power-source.cap.d.ts +20 -0
  12. package/dist/capabilities/recording-export.cap.d.ts +1 -0
  13. package/dist/capabilities/siren-duration.d.ts +45 -7
  14. package/dist/capabilities/siren.cap.d.ts +45 -2
  15. package/dist/capabilities/switch-settable.d.ts +15 -0
  16. package/dist/capabilities/switch.cap.d.ts +71 -0
  17. package/dist/capabilities/terminal-session.cap.d.ts +3 -60
  18. package/dist/capabilities/videoclips.cap.d.ts +3 -0
  19. package/dist/capabilities/workload.cap.d.ts +655 -0
  20. package/dist/client.js +58 -5
  21. package/dist/client.mjs +58 -5
  22. package/dist/{composed-stable-id-RvQIEpqg.mjs → composed-stable-id-BBL71oUQ.mjs} +20 -0
  23. package/dist/{composed-stable-id-C3NfRTj8.js → composed-stable-id-CVbyajE5.js} +20 -0
  24. package/dist/composition/engine-hosted-blocks.d.ts +131 -0
  25. package/dist/composition/helpers/index.d.ts +1 -1
  26. package/dist/composition/helpers/spec.d.ts +56 -2
  27. package/dist/composition/index.d.ts +1 -0
  28. package/dist/device/base-device.d.ts +29 -0
  29. package/dist/device/cap-vocabulary/declaration.d.ts +12 -1
  30. package/dist/device/cap-vocabulary/index.d.ts +4 -4
  31. package/dist/device/cap-vocabulary/resolve.d.ts +47 -1
  32. package/dist/device/cap-vocabulary/types.d.ts +26 -1
  33. package/dist/device/declare-identifiers.d.ts +58 -0
  34. package/dist/device/device-control-resolution.d.ts +1 -1
  35. package/dist/device/device-icon.d.ts +7 -0
  36. package/dist/device/device-identifiers.d.ts +190 -0
  37. package/dist/device/device-management.d.ts +10 -0
  38. package/dist/device/device-type.d.ts +22 -2
  39. package/dist/device/hero/build-hero-model.d.ts +15 -0
  40. package/dist/device/hero/hero-fragment.d.ts +11 -0
  41. package/dist/device/hero/hero-layout.d.ts +1 -0
  42. package/dist/device/hero/hero-look.d.ts +12 -0
  43. package/dist/device/hero/hero-model.d.ts +4 -4
  44. package/dist/device/hero/hero-scene.d.ts +7 -0
  45. package/dist/device/index.d.ts +5 -1
  46. package/dist/enums/event-category.d.ts +8 -0
  47. package/dist/enums.js +1 -1
  48. package/dist/enums.mjs +1 -1
  49. package/dist/{event-category-d9kiqCqC.js → event-category-CE_VCE2G.js} +8 -0
  50. package/dist/{event-category-Dhcd0TRH.mjs → event-category-Hwx_JSCU.mjs} +8 -0
  51. package/dist/generated/addon-api.d.ts +92 -14
  52. package/dist/generated/addon-cap-facts.d.ts +1 -1
  53. package/dist/generated/cap-status-types.d.ts +3 -1
  54. package/dist/generated/cap-vocabulary.d.ts +1 -1
  55. package/dist/generated/capability-router-map.d.ts +5 -2
  56. package/dist/generated/collection-array-methods.d.ts +1 -1
  57. package/dist/generated/customize-catalog.d.ts +1 -1
  58. package/dist/generated/device-local-state.d.ts +3 -0
  59. package/dist/generated/device-proxy.d.ts +4 -1
  60. package/dist/generated/device-scoped-caps.d.ts +1 -1
  61. package/dist/generated/history-catalog.d.ts +2 -2
  62. package/dist/generated/method-access-map.d.ts +1 -1
  63. package/dist/generated/method-device-selectors.d.ts +2 -2
  64. package/dist/generated/runtime-state-durability.d.ts +1 -1
  65. package/dist/generated/system-proxy.d.ts +1 -1
  66. package/dist/{implemented-methods-C7ScGvEz.js → implemented-methods-ChtdIofW.js} +128 -1
  67. package/dist/{implemented-methods-C5FMXLGP.mjs → implemented-methods-u7ddjc-_.mjs} +57 -2
  68. package/dist/index.d.ts +7 -3
  69. package/dist/index.js +1979 -429
  70. package/dist/index.mjs +1923 -428
  71. package/dist/node.js +2 -2
  72. package/dist/node.mjs +2 -2
  73. package/dist/{sleep-DwRtgB2i.js → sleep-CsZJsb8n.js} +692 -35
  74. package/dist/{sleep-Ch7Q7UtE.mjs → sleep-D6Pih0Qt.mjs} +669 -36
  75. package/package.json +1 -1
@@ -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];
@@ -0,0 +1,190 @@
1
+ /**
2
+ * Provider-declared device identifiers (D1059, planning#590).
3
+ *
4
+ * What a device IS, as its owning provider read it from the hardware: the keys a
5
+ * later step matches across integrations to tell that two devices are the same
6
+ * physical object. Separate from `DeviceMetadata` on purpose — metadata is a
7
+ * free-form blob the operator can edit, identifiers are typed, normalised and
8
+ * written ONLY by the provider that owns the device (`device-manager.
9
+ * setIdentifiers`, owner-checked on the transport's caller stamp).
10
+ *
11
+ * | Key | Stored form | Strength |
12
+ * | -------------- | ----------------------------------- | -------- |
13
+ * | `mac` | `aa:bb:cc:dd:ee:ff`, several | strong |
14
+ * | `serial` | `<manufacturer>:<serial>` | strong |
15
+ * | `machine-uuid` | SMBIOS / VM / container uuid | strong |
16
+ * | `vendor-uid` | `<vendor>:<id>` | strong |
17
+ * | `hostname` | lower-case, no domain | weak |
18
+ * | `ip` | IPv4 / IPv6 | weak |
19
+ *
20
+ * Strength is a property of the KEY, derived by {@link identifierStrength} —
21
+ * never stored, so it cannot drift from the table above. A weak key never links
22
+ * two devices on its own.
23
+ *
24
+ * The schema refuses a value that is not in its stored form, so whatever is
25
+ * persisted is already normalised. Build a declaration with
26
+ * {@link normaliseIdentifiers}, which turns the raw values a driver read into
27
+ * that form and names every value it refused.
28
+ */
29
+ import { z } from 'zod';
30
+ export declare const DEVICE_IDENTIFIER_KEYS: readonly ['mac', 'serial', 'machine-uuid', 'vendor-uid', 'hostname', 'ip'];
31
+ export declare const DeviceIdentifierKeySchema: z.ZodEnum<{
32
+ hostname: "hostname";
33
+ ip: "ip";
34
+ mac: "mac";
35
+ "machine-uuid": "machine-uuid";
36
+ serial: "serial";
37
+ "vendor-uid": "vendor-uid";
38
+ }>;
39
+ export type DeviceIdentifierKey = z.infer<typeof DeviceIdentifierKeySchema>;
40
+ /** `read` — the provider read it from the device; `derived` — computed from something else it read. */
41
+ export declare const DeviceIdentifierOriginSchema: z.ZodEnum<{
42
+ derived: "derived";
43
+ read: "read";
44
+ }>;
45
+ export type DeviceIdentifierOrigin = z.infer<typeof DeviceIdentifierOriginSchema>;
46
+ export type DeviceIdentifierStrength = 'strong' | 'weak';
47
+ export declare const DeviceIdentifierEntrySchema: z.ZodObject<{
48
+ value: z.ZodString;
49
+ origin: z.ZodEnum<{
50
+ derived: "derived";
51
+ read: "read";
52
+ }>;
53
+ readAt: z.ZodNumber;
54
+ }, z.core.$strict>;
55
+ export type DeviceIdentifierEntry = z.infer<typeof DeviceIdentifierEntrySchema>;
56
+ /** The typed declaration. Every key optional; `mac` the only one that holds several. */
57
+ export declare const DeviceIdentifiersSchema: z.ZodObject<{
58
+ mac: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodObject<{
59
+ value: z.ZodString;
60
+ origin: z.ZodEnum<{
61
+ derived: "derived";
62
+ read: "read";
63
+ }>;
64
+ readAt: z.ZodNumber;
65
+ }, z.core.$strict>>>>;
66
+ serial: z.ZodOptional<z.ZodObject<{
67
+ value: z.ZodString;
68
+ origin: z.ZodEnum<{
69
+ derived: "derived";
70
+ read: "read";
71
+ }>;
72
+ readAt: z.ZodNumber;
73
+ }, z.core.$strict>>;
74
+ 'machine-uuid': z.ZodOptional<z.ZodObject<{
75
+ value: z.ZodString;
76
+ origin: z.ZodEnum<{
77
+ derived: "derived";
78
+ read: "read";
79
+ }>;
80
+ readAt: z.ZodNumber;
81
+ }, z.core.$strict>>;
82
+ 'vendor-uid': z.ZodOptional<z.ZodObject<{
83
+ value: z.ZodString;
84
+ origin: z.ZodEnum<{
85
+ derived: "derived";
86
+ read: "read";
87
+ }>;
88
+ readAt: z.ZodNumber;
89
+ }, z.core.$strict>>;
90
+ hostname: z.ZodOptional<z.ZodObject<{
91
+ value: z.ZodString;
92
+ origin: z.ZodEnum<{
93
+ derived: "derived";
94
+ read: "read";
95
+ }>;
96
+ readAt: z.ZodNumber;
97
+ }, z.core.$strict>>;
98
+ ip: z.ZodOptional<z.ZodObject<{
99
+ value: z.ZodUnion<readonly [z.ZodIPv4, z.ZodIPv6]>;
100
+ origin: z.ZodEnum<{
101
+ derived: "derived";
102
+ read: "read";
103
+ }>;
104
+ readAt: z.ZodNumber;
105
+ }, z.core.$strict>>;
106
+ }, z.core.$strict>;
107
+ export type DeviceIdentifiers = z.infer<typeof DeviceIdentifiersSchema>;
108
+ /** How much a match on this key says about two devices being the same object. */
109
+ export declare function identifierStrength(key: DeviceIdentifierKey): DeviceIdentifierStrength;
110
+ /** True when the declaration carries no key at all. */
111
+ export declare function isEmptyIdentifiers(identifiers: DeviceIdentifiers): boolean;
112
+ /** A `<manufacturer>:<serial>` pair as the driver read it. */
113
+ export interface RawSerialIdentifier {
114
+ readonly manufacturer: string;
115
+ readonly serial: string;
116
+ }
117
+ /** A `<vendor>:<id>` pair as the driver read it. */
118
+ export interface RawVendorUidIdentifier {
119
+ readonly vendor: string;
120
+ readonly id: string;
121
+ }
122
+ /**
123
+ * The values a driver read, in whatever spelling the device used. Absent,
124
+ * `null` and blank are all "not known".
125
+ */
126
+ export interface RawDeviceIdentifiers {
127
+ readonly mac?: string | readonly string[] | null;
128
+ readonly serial?: RawSerialIdentifier | null;
129
+ readonly machineUuid?: string | null;
130
+ readonly vendorUid?: RawVendorUidIdentifier | null;
131
+ readonly hostname?: string | null;
132
+ readonly ip?: string | null;
133
+ /** A connection host as the operator typed it (an address OR a name): it lands
134
+ * on `ip` or `hostname`, whichever it is. Ignored for a key given explicitly. */
135
+ readonly host?: string | null;
136
+ }
137
+ export interface NormaliseIdentifiersOptions {
138
+ /** Epoch ms of the read. Default: now. */
139
+ readonly readAt?: number;
140
+ /** Origin for every key. Default `read`. */
141
+ readonly origin?: DeviceIdentifierOrigin;
142
+ /** Per-key origin, over {@link origin}. */
143
+ readonly originByKey?: Readonly<Partial<Record<DeviceIdentifierKey, DeviceIdentifierOrigin>>>;
144
+ }
145
+ /** One value {@link normaliseIdentifiers} refused, and why — the caller logs it. */
146
+ export interface RejectedIdentifier {
147
+ readonly key: DeviceIdentifierKey;
148
+ readonly value: string;
149
+ readonly reason: string;
150
+ }
151
+ export interface NormalisedIdentifiers {
152
+ readonly identifiers: DeviceIdentifiers;
153
+ readonly rejected: readonly RejectedIdentifier[];
154
+ }
155
+ export interface AcceptedValue {
156
+ readonly ok: true;
157
+ readonly value: string;
158
+ }
159
+ export type NormaliseResult = AcceptedValue | RejectedReason;
160
+ export interface RejectedReason {
161
+ readonly ok: false;
162
+ readonly reason: string;
163
+ }
164
+ /** `AA-BB-CC-DD-EE-FF`, `aabb.ccdd.eeff`, `AABBCCDDEEFF` → `aa:bb:cc:dd:ee:ff`. */
165
+ export declare function normaliseMac(raw: string): NormaliseResult;
166
+ /**
167
+ * Turn what a driver read into a valid {@link DeviceIdentifiers}: MACs lower-case
168
+ * with colons and de-duplicated, a hostname without its domain, an IP validated,
169
+ * a serial prefixed by its manufacturer, a vendor uid by its vendor. A value that
170
+ * cannot be normalised is left out and listed in `rejected` — the caller logs it
171
+ * (with `tags: { deviceId }`), it is never dropped in silence.
172
+ */
173
+ export declare function normaliseIdentifiers(raw: RawDeviceIdentifiers, options?: NormaliseIdentifiersOptions): NormalisedIdentifiers;
174
+ /**
175
+ * The declaration to store when the owning provider declares `next` over
176
+ * `stored` (D1059).
177
+ *
178
+ * - A kind in `unread` — the provider TRIED to read it and the read failed —
179
+ * keeps its stored entry: a failed read changes nothing (D49).
180
+ * - Every other kind is what `next` says: a kind absent from `next` was read and
181
+ * found absent, so it is removed.
182
+ * - An entry whose value and origin are unchanged keeps its stored `readAt`:
183
+ * `readAt` is when that value was FIRST read, so a provider re-declaring on every
184
+ * boot writes nothing and emits nothing.
185
+ *
186
+ * Returns `null` when nothing is left.
187
+ */
188
+ export declare function mergeIdentifiers(stored: DeviceIdentifiers | null | undefined, next: DeviceIdentifiers | null, unread?: readonly DeviceIdentifierKey[]): DeviceIdentifiers | null;
189
+ /** True when two declarations hold the same entries, `readAt` included (key order ignored). */
190
+ export declare function sameIdentifiers(a: DeviceIdentifiers | null | undefined, b: DeviceIdentifiers | null | undefined): boolean;
@@ -1,3 +1,4 @@
1
+ import type { DeviceIdentifiers } from './device-identifiers.js';
1
2
  import type { z } from 'zod';
2
3
  import type { IDevice } from './device.js';
3
4
  import type { DeviceType } from './device-type.js';
@@ -78,6 +79,11 @@ export interface SavedDevice {
78
79
  *
79
80
  * Anything else the driver knows can land alongside (`onvifProfile`,
80
81
  * `ipAddress`, `apiPort`, …). All values must be JSON-serializable.
82
+ *
83
+ * Identity used to MATCH devices (MAC, serial, vendor uid, machine uuid,
84
+ * hostname, IP) is declared separately, typed and read-only for the operator:
85
+ * `DeviceMeta.identifiers` (D1059). The `mac` / `serialNumber` / `uid` keys
86
+ * above stay for display until a later step retires them.
81
87
  */
82
88
  export type DeviceMetadata = Record<string, unknown>;
83
89
  /** One child-placement directive on a container's `childLayout`. The child is
@@ -154,6 +160,10 @@ export interface DeviceMeta {
154
160
  readonly parentDeviceId: number | null;
155
161
  /** Hardware + identity blob; null when nothing has been populated yet. */
156
162
  readonly metadata: DeviceMetadata | null;
163
+ /** Provider-declared identifiers (D1059): typed, normalised, written only by
164
+ * the owning provider through `device-manager.setIdentifiers`, read-only for
165
+ * the operator. Absent ⇒ the provider declared none. */
166
+ readonly identifiers?: DeviceIdentifiers;
157
167
  /** Optional upstream-system identity + rendering envelope. See
158
168
  * `SourceInfo`. Persisted under `metadata.sourceInfo` — this field
159
169
  * is the typed projection callers consume directly. `BaseDevice`
@@ -118,7 +118,11 @@ export declare enum DeviceType {
118
118
  /** A home energy installation (any vendor): solar, grid, house, a metered heat pump
119
119
  * and the storage as branches of one bus. One read-only `energy-system` cap carries
120
120
  * every value; the storage is a field of it, never the `battery` cap (#513, #522). */
121
- EnergySystem = "energy-system"
121
+ EnergySystem = "energy-system",
122
+ /** Something that RUNS on a machine, or the machine itself (#585): a VM, an app
123
+ * container, an LXC, an app, or a host. The kind is the ROLE (D1033, D1056), never
124
+ * a field; one `workload` cap carries the state, the controls and the resources. */
125
+ Workload = "workload"
122
126
  }
123
127
  export declare enum DeviceFeature {
124
128
  BatteryOperated = "battery-operated",
@@ -349,6 +353,11 @@ export declare enum DeviceRole {
349
353
  * `light` type: the provider owns the type, and a light implies brightness
350
354
  * or colour this relay lacks. */
351
355
  SwitchLight = "switch-light",
356
+ /** One port of a network switch that powers the device behind it (PoE): on /
357
+ * off feeds or cuts that power. Its link is `network-link`, its draw
358
+ * `power-meter`. Restarting the powered device through the port is that
359
+ * device's `power-source` cap, never a reboot of the port. */
360
+ PoePort = "poe-port",
352
361
  /** Air conditioner / split unit: cooling, fan speed, louvres. */
353
362
  ClimateAc = "climate-ac",
354
363
  /** Room thermostat: a setpoint and a room temperature. The default. */
@@ -428,5 +437,16 @@ export declare enum DeviceRole {
428
437
  GenericNotifier = "generic-notifier",
429
438
  /** Emits a pulse train (infrared or RF) on request — the `ir-transmitter`
430
439
  * cap. A `DeviceType.Generic` device. */
431
- IrTransmitter = "ir-transmitter"
440
+ IrTransmitter = "ir-transmitter",
441
+ /** A virtual machine on a hypervisor. */
442
+ Vm = "vm",
443
+ /** An application container (Docker, Podman). */
444
+ AppContainer = "app-container",
445
+ /** A system container (LXC). */
446
+ Lxc = "lxc",
447
+ /** An application or service running on a host. */
448
+ App = "app",
449
+ /** A machine that runs workloads or is an appliance with its own OS: a
450
+ * server, a hypervisor, a gateway console, a CCU. */
451
+ Host = "host"
432
452
  }
@@ -1,3 +1,14 @@
1
+ /**
2
+ * `buildHeroModel` — the ONE pure function behind every device hero (D1023).
3
+ * The admin device page, the admin quick-detail dialog and the viewer's device
4
+ * screen all draw what it returns; none of them decides anything.
5
+ *
6
+ * Inputs are the device, the caps it is bound to (`getBindings`, per device —
7
+ * never the global cap list, D12), its features and one raw slice per cap. A
8
+ * slice that is missing or does not parse is "not answered": unknown is never
9
+ * off (D315/D393), a heater whose switch has not reported renders `unknown`.
10
+ */
11
+ import type { SwitchOptions } from '../../capabilities/switch.cap.js';
1
12
  import type { ReadingQuantity } from '../../units/quantity.js';
2
13
  import type { HeroModel } from './hero-model.js';
3
14
  export interface HeroModelInput {
@@ -24,5 +35,9 @@ export interface HeroModelInput {
24
35
  readonly access: {
25
36
  readonly canActuate: boolean;
26
37
  };
38
+ /** The `switch` provider's `getOptions` answer; absent = not asked (a plain on/off switch). */
39
+ readonly switchOptions?: SwitchOptions;
40
+ /** `power-source.getStatus().switchSettable`; absent or `null` = not known (on / off stay). */
41
+ readonly powerSupplySettable?: boolean | null;
27
42
  }
28
43
  export declare function buildHeroModel(input: HeroModelInput): HeroModel;
@@ -2,6 +2,7 @@
2
2
  * What ONE capability adds to a hero (D1023), and the context it reads.
3
3
  * Contributions return a fragment; `buildHeroModel` merges the fragments.
4
4
  */
5
+ import type { SwitchOptions } from '../../capabilities/switch.cap.js';
5
6
  import type { ReadingQuantity } from '../../units/quantity.js';
6
7
  import type { HeroBadge, HeroConsumablesSlot, HeroConsumptionSlot, HeroFact, HeroOwnPowerSlot, HeroPowerSupplySlot, HeroRemoteSlot, HeroRow, HeroSideTile, HeroTimedRunSlot } from './hero-model.js';
7
8
  import type { HeroMeasurement } from './hero-measurement.js';
@@ -36,6 +37,16 @@ export interface HeroContext {
36
37
  readonly caps: readonly string[];
37
38
  /** What a numeric-sensor measures (stored at adopt); `null`/absent = unknown, the number shows bare. */
38
39
  readonly quantity?: ReadingQuantity | null;
40
+ /**
41
+ * The `switch` provider's `getOptions` answer. Absent = not asked: a plain on/off switch.
42
+ * `supportsSetState: false` (a switch that only reports) offers no on/off.
43
+ */
44
+ readonly switchOptions?: SwitchOptions;
45
+ /**
46
+ * Whether the switch that powers the device can be set (`power-source.getStatus().switchSettable`).
47
+ * Absent or `null` = not known, on / off stay; `false` withdraws power on / off (D1058).
48
+ */
49
+ readonly powerSupplySettable?: boolean | null;
39
50
  }
40
51
  export interface HeroFragment {
41
52
  readonly reading?: StateReading;