dinkster-api 0.0.2__py3-none-any.whl

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 (238) hide show
  1. dinkster_api/__init__.py +9 -0
  2. dinkster_api/py.typed +0 -0
  3. dinkster_api/v1.py +935 -0
  4. dinkster_api-0.0.2.dist-info/METADATA +16 -0
  5. dinkster_api-0.0.2.dist-info/RECORD +238 -0
  6. dinkster_api-0.0.2.dist-info/WHEEL +4 -0
  7. dinkster_api-0.0.2.dist-info/entry_points.txt +2 -0
  8. dinkster_assets/__init__.py +337 -0
  9. dinkster_assets/acquire.py +226 -0
  10. dinkster_assets/acquisition_plan.py +145 -0
  11. dinkster_assets/audio.py +119 -0
  12. dinkster_assets/catalog.py +156 -0
  13. dinkster_assets/component_manifest.py +110 -0
  14. dinkster_assets/declared.py +218 -0
  15. dinkster_assets/fetch.py +495 -0
  16. dinkster_assets/guess.py +136 -0
  17. dinkster_assets/identity.py +72 -0
  18. dinkster_assets/integrity.py +310 -0
  19. dinkster_assets/json_metadata.py +41 -0
  20. dinkster_assets/kind.py +52 -0
  21. dinkster_assets/latent_format.py +346 -0
  22. dinkster_assets/library.py +816 -0
  23. dinkster_assets/media.py +1385 -0
  24. dinkster_assets/migrations/env.py +38 -0
  25. dinkster_assets/migrations/script.py.mako +28 -0
  26. dinkster_assets/migrations/versions/0001_asset_records_create_asset_record_catalog.py +109 -0
  27. dinkster_assets/migrations/versions/0002_asset_observations.py +36 -0
  28. dinkster_assets/model.py +242 -0
  29. dinkster_assets/mounts.py +1278 -0
  30. dinkster_assets/need.py +168 -0
  31. dinkster_assets/pack_assets.py +217 -0
  32. dinkster_assets/probe.py +118 -0
  33. dinkster_assets/provenance.py +254 -0
  34. dinkster_assets/public_acquisition.py +424 -0
  35. dinkster_assets/py.typed +0 -0
  36. dinkster_assets/records.py +899 -0
  37. dinkster_assets/resolution.py +778 -0
  38. dinkster_assets/resolver_index.py +364 -0
  39. dinkster_assets/resolver_subscription.py +1149 -0
  40. dinkster_assets/save_target.py +139 -0
  41. dinkster_assets/schema.py +73 -0
  42. dinkster_assets/selections.py +256 -0
  43. dinkster_assets/transport.py +243 -0
  44. dinkster_assets/value.py +258 -0
  45. dinkster_assets/vault.py +276 -0
  46. dinkster_assets/writer.py +765 -0
  47. dinkster_caches/__init__.py +19 -0
  48. dinkster_caches/cas.py +310 -0
  49. dinkster_caches/disk.py +330 -0
  50. dinkster_caches/layered.py +150 -0
  51. dinkster_caches/memory.py +208 -0
  52. dinkster_caches/py.typed +0 -0
  53. dinkster_caches/wire.py +346 -0
  54. dinkster_image_document/__init__.py +39 -0
  55. dinkster_image_document/blend.py +264 -0
  56. dinkster_image_document/compat.py +211 -0
  57. dinkster_image_document/document.py +374 -0
  58. dinkster_image_document/format.py +569 -0
  59. dinkster_image_document/interchange.py +572 -0
  60. dinkster_image_document/py.typed +1 -0
  61. dinkster_image_document/render.py +455 -0
  62. dinkster_inference_wire/__init__.py +141 -0
  63. dinkster_inference_wire/camera_wire.py +127 -0
  64. dinkster_inference_wire/conditioning.py +752 -0
  65. dinkster_inference_wire/conditioning_wire.py +1143 -0
  66. dinkster_inference_wire/devices.py +285 -0
  67. dinkster_inference_wire/generation.py +446 -0
  68. dinkster_inference_wire/hook_values.py +168 -0
  69. dinkster_inference_wire/ic_lora_parameters.py +69 -0
  70. dinkster_inference_wire/latents.py +244 -0
  71. dinkster_inference_wire/media_wire.py +169 -0
  72. dinkster_inference_wire/openai_generation.py +1035 -0
  73. dinkster_inference_wire/pose_keypoint.py +83 -0
  74. dinkster_inference_wire/process.py +33 -0
  75. dinkster_inference_wire/py.typed +0 -0
  76. dinkster_inference_wire/registry.py +116 -0
  77. dinkster_inference_wire/sam3_wire.py +68 -0
  78. dinkster_inference_wire/sampling_wire.py +279 -0
  79. dinkster_inference_wire/sources.py +399 -0
  80. dinkster_inference_wire/spaces.py +344 -0
  81. dinkster_inference_wire/sparse.py +372 -0
  82. dinkster_inference_wire/splat_wire.py +23 -0
  83. dinkster_inference_wire/types.py +256 -0
  84. dinkster_inference_wire/vision_wire.py +53 -0
  85. dinkster_inference_wire/voxel_wire.py +72 -0
  86. dinkster_inference_wire/wan_wire.py +93 -0
  87. dinkster_inference_wire/weights.py +219 -0
  88. dinkster_memory/__init__.py +92 -0
  89. dinkster_memory/accelerator.py +96 -0
  90. dinkster_memory/budgets.py +96 -0
  91. dinkster_memory/details.py +91 -0
  92. dinkster_memory/governor.py +554 -0
  93. dinkster_memory/leases.py +176 -0
  94. dinkster_memory/py.typed +0 -0
  95. dinkster_memory/release.py +131 -0
  96. dinkster_memory/reported.py +101 -0
  97. dinkster_memory/reservations.py +101 -0
  98. dinkster_memory/resident.py +600 -0
  99. dinkster_memory/system.py +614 -0
  100. dinkster_memory/tenants.py +67 -0
  101. dinkster_protocol/__init__.py +1008 -0
  102. dinkster_protocol/attention.py +652 -0
  103. dinkster_protocol/extension_contribution_kinds.json +21 -0
  104. dinkster_protocol/extension_contribution_kinds.py +43 -0
  105. dinkster_protocol/extensions.py +742 -0
  106. dinkster_protocol/frontend_modules.py +145 -0
  107. dinkster_protocol/multigpu.py +107 -0
  108. dinkster_protocol/pack_surfaces.py +489 -0
  109. dinkster_protocol/payload.py +63 -0
  110. dinkster_protocol/preview.py +86 -0
  111. dinkster_protocol/py.typed +0 -0
  112. dinkster_protocol/result_algebra.py +380 -0
  113. dinkster_protocol/result_document.py +244 -0
  114. dinkster_protocol/run_control.py +96 -0
  115. dinkster_protocol/training.py +399 -0
  116. dinkster_protocol/workgroup.py +1014 -0
  117. dinkster_registry/__init__.py +135 -0
  118. dinkster_registry/admission.py +372 -0
  119. dinkster_registry/artifact.py +128 -0
  120. dinkster_registry/composition.py +152 -0
  121. dinkster_registry/grants.py +206 -0
  122. dinkster_registry/install.py +1017 -0
  123. dinkster_registry/model.py +414 -0
  124. dinkster_registry/principals.py +494 -0
  125. dinkster_registry/py.typed +0 -0
  126. dinkster_schema/__init__.py +347 -0
  127. dinkster_schema/capture.py +240 -0
  128. dinkster_schema/coerce.py +186 -0
  129. dinkster_schema/comfy_alias.py +496 -0
  130. dinkster_schema/comfy_group.py +768 -0
  131. dinkster_schema/elaborate.py +676 -0
  132. dinkster_schema/execution.py +24 -0
  133. dinkster_schema/expansion.py +123 -0
  134. dinkster_schema/log.py +206 -0
  135. dinkster_schema/media.py +77 -0
  136. dinkster_schema/model.py +2920 -0
  137. dinkster_schema/names.py +25 -0
  138. dinkster_schema/node.py +137 -0
  139. dinkster_schema/output_descriptors.py +63 -0
  140. dinkster_schema/py.typed +0 -0
  141. dinkster_schema/replace.py +1853 -0
  142. dinkster_schema/reporting.py +441 -0
  143. dinkster_schema/solve.py +178 -0
  144. dinkster_schema/wire.py +1876 -0
  145. dinkster_values/__init__.py +625 -0
  146. dinkster_values/_media_array.py +7 -0
  147. dinkster_values/absent.py +77 -0
  148. dinkster_values/asset_folders.py +64 -0
  149. dinkster_values/assets.py +106 -0
  150. dinkster_values/audio_codec.py +594 -0
  151. dinkster_values/audio_lazy.py +871 -0
  152. dinkster_values/builtin_types.py +181 -0
  153. dinkster_values/curve.py +260 -0
  154. dinkster_values/detection_codec.py +286 -0
  155. dinkster_values/image_codec.py +691 -0
  156. dinkster_values/image_components.py +219 -0
  157. dinkster_values/latent_codec.py +514 -0
  158. dinkster_values/limits.py +52 -0
  159. dinkster_values/lists.py +216 -0
  160. dinkster_values/media_containers.py +70 -0
  161. dinkster_values/model.py +417 -0
  162. dinkster_values/model3d_codec.py +167 -0
  163. dinkster_values/names.py +168 -0
  164. dinkster_values/pins.py +77 -0
  165. dinkster_values/py.typed +0 -0
  166. dinkster_values/registry.py +1105 -0
  167. dinkster_values/resident.py +210 -0
  168. dinkster_values/resources.py +210 -0
  169. dinkster_values/splat_codec.py +477 -0
  170. dinkster_values/storage.py +133 -0
  171. dinkster_values/streams.py +241 -0
  172. dinkster_values/svg_codec.py +120 -0
  173. dinkster_values/timeline_video.py +68 -0
  174. dinkster_values/tuples.py +61 -0
  175. dinkster_values/video_codec.py +897 -0
  176. dinkster_values/video_document.py +315 -0
  177. dinkster_values/video_edits.py +253 -0
  178. dinkster_values/video_probe.py +221 -0
  179. dinkster_video/__init__.py +58 -0
  180. dinkster_video/document.py +352 -0
  181. dinkster_video/formats.py +722 -0
  182. dinkster_video/image_math.py +175 -0
  183. dinkster_video/preview/dinkster-pack.toml +36 -0
  184. dinkster_video/preview/src/dinkster_video_preview/__init__.py +84 -0
  185. dinkster_video/preview/src/dinkster_video_preview/preview.js +45 -0
  186. dinkster_video/py.typed +1 -0
  187. dinkster_video/runtime.py +1561 -0
  188. dinkster_video/timeline.py +576 -0
  189. dinkster_video/timeline_runtime.py +305 -0
  190. dinkster_video_preview/__init__.py +84 -0
  191. dinkster_video_preview/preview.js +45 -0
  192. dinkster_workers/__init__.py +207 -0
  193. dinkster_workers/_doctor_probe.py +359 -0
  194. dinkster_workers/accelerator.py +156 -0
  195. dinkster_workers/aimdo_bootstrap.py +81 -0
  196. dinkster_workers/backend_env.py +1485 -0
  197. dinkster_workers/blobs.py +402 -0
  198. dinkster_workers/boundary.py +1918 -0
  199. dinkster_workers/catalog.py +182 -0
  200. dinkster_workers/devices.py +164 -0
  201. dinkster_workers/diagnostics.py +64 -0
  202. dinkster_workers/dispatch.py +298 -0
  203. dinkster_workers/doctor.py +1382 -0
  204. dinkster_workers/egress.py +344 -0
  205. dinkster_workers/error_hints.py +175 -0
  206. dinkster_workers/execution.py +160 -0
  207. dinkster_workers/governed.py +123 -0
  208. dinkster_workers/headroom.py +156 -0
  209. dinkster_workers/host.py +3116 -0
  210. dinkster_workers/in_process.py +1325 -0
  211. dinkster_workers/interpreter.py +84 -0
  212. dinkster_workers/isolated.py +862 -0
  213. dinkster_workers/launch.py +72 -0
  214. dinkster_workers/manifest.py +3332 -0
  215. dinkster_workers/media.py +196 -0
  216. dinkster_workers/pack_environment.py +473 -0
  217. dinkster_workers/pack_lock.py +359 -0
  218. dinkster_workers/placement.py +215 -0
  219. dinkster_workers/preview_artifacts.py +233 -0
  220. dinkster_workers/produced_assets.py +218 -0
  221. dinkster_workers/provision.py +597 -0
  222. dinkster_workers/py.typed +0 -0
  223. dinkster_workers/relay.py +762 -0
  224. dinkster_workers/remote.py +921 -0
  225. dinkster_workers/resume.py +490 -0
  226. dinkster_workers/routing.py +134 -0
  227. dinkster_workers/run_control.py +275 -0
  228. dinkster_workers/sandbox.py +798 -0
  229. dinkster_workers/saved_artifacts.py +275 -0
  230. dinkster_workers/service.py +593 -0
  231. dinkster_workers/session.py +2605 -0
  232. dinkster_workers/single_job_multi_gpu.py +7 -0
  233. dinkster_workers/staging.py +230 -0
  234. dinkster_workers/transport.py +161 -0
  235. dinkster_workers/workgroup.py +729 -0
  236. dinkster_workers/workgroup_compose.py +135 -0
  237. dinkster_workers/workgroup_config.py +196 -0
  238. dinkster_workers/workgroup_session.py +340 -0
@@ -0,0 +1,1143 @@
1
+ """Canonical torch-free wire carrier for conditioning records."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import json
6
+ import math
7
+ import struct
8
+ from collections.abc import Callable, Iterable, Mapping, Sequence
9
+ from dataclasses import dataclass, field
10
+ from typing import Literal, TypeAlias, cast
11
+
12
+ from dinkster_values import (
13
+ CONDITIONING_HEADER_LIMIT_BYTES,
14
+ CONDITIONING_TYPE,
15
+ ResidencyTable,
16
+ ResidentCodec,
17
+ ResidentLookupError,
18
+ TypeRegistry,
19
+ TypeSpec,
20
+ resident_owners,
21
+ stable_hash,
22
+ )
23
+
24
+ from .conditioning import (
25
+ EMPTY_RANGE,
26
+ AreaDescriptor,
27
+ AreaUnits,
28
+ ConditioningChannel,
29
+ ConditioningRecord,
30
+ ConditioningSet,
31
+ ConditionScaleVector,
32
+ ExtensionInputValue,
33
+ ExtensionValue,
34
+ MaskDescriptor,
35
+ PayloadDescriptor,
36
+ PayloadReference,
37
+ PercentRange,
38
+ TokenLayoutDescriptor,
39
+ TokenSegmentDescriptor,
40
+ canonical_conditioning_set,
41
+ )
42
+ from .hook_values import normalize_hook_owners
43
+
44
+ CONDITIONING_TYPE_ID = CONDITIONING_TYPE
45
+ CONDITIONING_CARRIER_FORMAT = "dinkster-conditioning-carrier-v1"
46
+ RESIDENT_CONDITIONING_FORMAT = "dinkster-resident-conditioning-v1"
47
+
48
+ _MAGIC = b"DMFC"
49
+ _RESIDENT_MAGIC = b"DMFR\x01"
50
+ _VERSION = 1
51
+ _PREFIX_SIZE = len(_MAGIC) + 1 + 8
52
+ _MAX_HEADER_BYTES = CONDITIONING_HEADER_LIMIT_BYTES
53
+ _MAX_PAYLOADS = 4096
54
+ _DTYPE_WIDTHS = {
55
+ "F64": 8,
56
+ "F32": 4,
57
+ "F16": 2,
58
+ "BF16": 2,
59
+ "I64": 8,
60
+ "I32": 4,
61
+ "I16": 2,
62
+ "I8": 1,
63
+ "U64": 8,
64
+ "U32": 4,
65
+ "U16": 2,
66
+ "U8": 1,
67
+ "BOOL": 1,
68
+ }
69
+
70
+
71
+ class ConditioningWireError(ValueError):
72
+ """A deterministic carrier refusal with a stable machine-readable code."""
73
+
74
+ def __init__(self, code: str, detail: str = "") -> None:
75
+ self.code = code
76
+ message = f"conditioning-wire:{code}"
77
+ super().__init__(f"{message}: {detail}" if detail else message)
78
+
79
+
80
+ @dataclass(frozen=True)
81
+ class PayloadBinding:
82
+ """One byte-aligned payload; multi-byte values use little-endian order."""
83
+
84
+ reference_id: str
85
+ shape: tuple[int, ...]
86
+ dtype: str
87
+ space: str
88
+ data: bytes
89
+ kind: Literal["materialized"] = field(default="materialized", init=False)
90
+
91
+ def __post_init__(self) -> None:
92
+ reference_id = cast("object", self.reference_id)
93
+ shape = cast("object", self.shape)
94
+ dtype = cast("object", self.dtype)
95
+ space = cast("object", self.space)
96
+ data = cast("object", self.data)
97
+ if not isinstance(reference_id, str) or not reference_id:
98
+ raise ConditioningWireError("invalid-binding", "reference_id must be non-empty")
99
+ try:
100
+ reference_id.encode("utf-8")
101
+ except UnicodeEncodeError:
102
+ raise ConditioningWireError(
103
+ "invalid-binding", "reference_id must be valid Unicode"
104
+ ) from None
105
+ if (
106
+ not isinstance(shape, tuple)
107
+ or not shape
108
+ or any(type(dim) is not int or dim < 0 for dim in cast("tuple[object, ...]", shape))
109
+ ):
110
+ raise ConditioningWireError("invalid-binding", "shape must contain non-negative ints")
111
+ if not isinstance(dtype, str) or dtype not in _DTYPE_WIDTHS:
112
+ raise ConditioningWireError("unknown-dtype", repr(dtype))
113
+ if not isinstance(space, str) or not space:
114
+ raise ConditioningWireError("invalid-binding", "space must be non-empty")
115
+ try:
116
+ space.encode("utf-8")
117
+ except UnicodeEncodeError:
118
+ raise ConditioningWireError("invalid-binding", "space must be valid Unicode") from None
119
+ if not isinstance(data, bytes):
120
+ raise ConditioningWireError("invalid-binding", "data must be bytes")
121
+ expected = math.prod(self.shape) * _DTYPE_WIDTHS[self.dtype]
122
+ if len(self.data) != expected:
123
+ raise ConditioningWireError(
124
+ "payload-byte-length",
125
+ f"{self.reference_id!r} has {len(self.data)} bytes, expected {expected}",
126
+ )
127
+
128
+
129
+ def _validate_deferred_binding(
130
+ reference_id: object,
131
+ shape: object,
132
+ dtype: object,
133
+ space: object,
134
+ fingerprint: object,
135
+ ) -> None:
136
+ if not isinstance(reference_id, str) or not reference_id:
137
+ raise ConditioningWireError("invalid-binding", "reference_id must be non-empty")
138
+ if (
139
+ not isinstance(shape, tuple)
140
+ or not shape
141
+ or any(type(dim) is not int or dim < 0 for dim in cast("tuple[object, ...]", shape))
142
+ ):
143
+ raise ConditioningWireError("invalid-binding", "shape must contain non-negative ints")
144
+ if not isinstance(dtype, str) or dtype not in _DTYPE_WIDTHS:
145
+ raise ConditioningWireError("unknown-dtype", repr(dtype))
146
+ if not isinstance(space, str) or not space:
147
+ raise ConditioningWireError("invalid-binding", "space must be non-empty")
148
+ if not isinstance(fingerprint, str) or not fingerprint:
149
+ raise ConditioningWireError("invalid-binding", "fingerprint must be non-empty")
150
+
151
+
152
+ @dataclass(frozen=True)
153
+ class LivePayloadBinding:
154
+ """Same-process payload with stable producer identity and deferred bytes."""
155
+
156
+ reference_id: str
157
+ shape: tuple[int, ...]
158
+ dtype: str
159
+ space: str
160
+ payload: object
161
+ fingerprint: str
162
+ materialize: Callable[[object], bytes]
163
+ kind: Literal["live"] = field(default="live", init=False)
164
+
165
+ def __post_init__(self) -> None:
166
+ _validate_deferred_binding(
167
+ self.reference_id, self.shape, self.dtype, self.space, self.fingerprint
168
+ )
169
+ if self.payload is None:
170
+ raise ConditioningWireError("invalid-binding", "live payload must not be None")
171
+ if not callable(self.materialize):
172
+ raise ConditioningWireError("invalid-binding", "materialize must be callable")
173
+
174
+
175
+ @dataclass(frozen=True)
176
+ class ResidentPayloadBinding:
177
+ """Non-materializable payload retained by its owning worker process."""
178
+
179
+ reference_id: str
180
+ shape: tuple[int, ...]
181
+ dtype: str
182
+ space: str
183
+ payload: object
184
+ fingerprint: str
185
+ kind: Literal["resident"] = field(default="resident", init=False)
186
+
187
+ def __post_init__(self) -> None:
188
+ _validate_deferred_binding(
189
+ self.reference_id, self.shape, self.dtype, self.space, self.fingerprint
190
+ )
191
+ if self.payload is None:
192
+ raise ConditioningWireError("invalid-binding", "resident payload must not be None")
193
+
194
+
195
+ ConditioningPayloadBinding: TypeAlias = PayloadBinding | LivePayloadBinding | ResidentPayloadBinding
196
+
197
+
198
+ @dataclass(frozen=True)
199
+ class ConditioningCarrier:
200
+ """Canonical records plus materialized, live, or resident payloads."""
201
+
202
+ conditioning: ConditioningSet
203
+ bindings: tuple[ConditioningPayloadBinding, ...]
204
+ canonical_bytes: bytes | None = field(default=None, repr=False, compare=False)
205
+
206
+ @property
207
+ def has_resident_payloads(self) -> bool:
208
+ return any(binding.kind == "resident" for binding in self.bindings)
209
+
210
+ @property
211
+ def _dinkster_resident_payloads(self) -> tuple[object, ...]:
212
+ return tuple(binding.payload for binding in self.bindings if binding.kind == "resident")
213
+
214
+ @property
215
+ def _dinkster_resident_payload(self) -> object:
216
+ resident = self._dinkster_resident_payloads
217
+ if len(resident) != 1:
218
+ raise TypeError("conditioning carrier must contain exactly one resident payload")
219
+ return resident[0]
220
+
221
+ @property
222
+ def _dinkster_resident_owner(self) -> object:
223
+ owners = self._resident_owners()
224
+ if not owners:
225
+ raise TypeError("conditioning carrier has no resident payload owner")
226
+ return owners[0]
227
+
228
+ @property
229
+ def _dinkster_resident_refs(self) -> tuple[object, ...]:
230
+ return self._resident_owners()[1:]
231
+
232
+ @property
233
+ def _dinkster_resident_fingerprint(self) -> str:
234
+ if not self.has_resident_payloads:
235
+ raise TypeError("conditioning carrier has no resident payload fingerprint")
236
+ return _deferred_carrier_fingerprint(self)
237
+
238
+ def _resident_owners(self) -> tuple[object, ...]:
239
+ owners: list[object] = []
240
+ identities: set[int] = set()
241
+ for binding in self.bindings:
242
+ if binding.kind != "resident":
243
+ continue
244
+ payload = binding.payload
245
+ primary = cast("object", getattr(payload, "_dinkster_resident_owner", payload))
246
+ refs_value = cast("object", getattr(payload, "_dinkster_resident_refs", ()))
247
+ if not isinstance(refs_value, tuple):
248
+ raise TypeError("resident payload references must be a tuple")
249
+ refs = cast("tuple[object, ...]", refs_value)
250
+ for owner in (primary, *refs):
251
+ if owner is None:
252
+ raise TypeError("resident payload owners must not be None")
253
+ if id(owner) not in identities:
254
+ identities.add(id(owner))
255
+ owners.append(owner)
256
+ return tuple(owners)
257
+
258
+
259
+ def _conditioning_hooks(payload: object) -> tuple[object, ...]:
260
+ if type(payload) is not list:
261
+ return ()
262
+ hooks: list[object] = []
263
+ for entry in cast("list[object]", payload):
264
+ if not isinstance(entry, (list, tuple)):
265
+ continue
266
+ pair = cast("Sequence[object]", entry)
267
+ if len(pair) != 2:
268
+ continue
269
+ metadata = pair[1]
270
+ if isinstance(metadata, Mapping):
271
+ hook = cast("Mapping[str, object]", metadata).get("hooks")
272
+ if hook is not None:
273
+ normalize_hook_owners(hook)
274
+ for owner in (hook, *resident_owners(hook)):
275
+ if not any(owner is existing for existing in hooks):
276
+ hooks.append(owner)
277
+ return tuple(hooks)
278
+
279
+
280
+ def _conditioning_gligens(payload: object) -> tuple[object, ...]:
281
+ if type(payload) is not list:
282
+ return ()
283
+ models: list[object] = []
284
+ for entry in cast("list[object]", payload):
285
+ if not isinstance(entry, (list, tuple)):
286
+ continue
287
+ pair = cast("Sequence[object]", entry)
288
+ if len(pair) != 2 or not isinstance(pair[1], Mapping):
289
+ continue
290
+ gligen_value = cast("Mapping[str, object]", pair[1]).get("gligen")
291
+ gligen = cast("tuple[object, ...]", gligen_value)
292
+ if type(gligen_value) is not tuple or len(gligen) < 2:
293
+ continue
294
+ model = gligen[1]
295
+ for owner in (model, *resident_owners(model)):
296
+ if not any(owner is existing for existing in models):
297
+ models.append(owner)
298
+ return tuple(models)
299
+
300
+
301
+ @dataclass(frozen=True, slots=True)
302
+ class ResidentConditioningCarrier:
303
+ """Typed conditioning whose opaque payload remains in its worker process."""
304
+
305
+ payload: object
306
+
307
+ def __post_init__(self) -> None:
308
+ if self.payload is None:
309
+ raise TypeError("resident conditioning payload must not be None")
310
+
311
+ @property
312
+ def _dinkster_resident_payload(self) -> object:
313
+ return self.payload
314
+
315
+ @property
316
+ def _dinkster_resident_payloads(self) -> tuple[object, ...]:
317
+ return (self.payload,)
318
+
319
+ @property
320
+ def _dinkster_resident_owner(self) -> object:
321
+ return getattr(self.payload, "_dinkster_resident_owner", self.payload)
322
+
323
+ @property
324
+ def _dinkster_resident_refs(self) -> tuple[object, ...]:
325
+ refs = getattr(self.payload, "_dinkster_resident_refs", ())
326
+ if not isinstance(refs, tuple):
327
+ raise TypeError("resident conditioning payload references must be a tuple")
328
+ return (
329
+ *cast("tuple[object, ...]", refs),
330
+ *_conditioning_hooks(self.payload),
331
+ *_conditioning_gligens(self.payload),
332
+ )
333
+
334
+ @property
335
+ def _dinkster_resident_fingerprint(self) -> str | None:
336
+ if type(self.payload) is list:
337
+ return None
338
+ fingerprint = getattr(self.payload, "_dinkster_resident_fingerprint", None)
339
+ if not isinstance(fingerprint, str) or not fingerprint:
340
+ raise TypeError("resident conditioning payload requires a stable fingerprint")
341
+ return fingerprint
342
+
343
+
344
+ def conditioning(value: object, input_id: str) -> ConditioningCarrier:
345
+ """Admit the one native conditioning value form at a consumer boundary."""
346
+
347
+ if type(value) is not ConditioningCarrier:
348
+ raise TypeError(f"{input_id} must come from a Dinkster conditioning node")
349
+ return value
350
+
351
+
352
+ def _canonical_json(value: object) -> bytes:
353
+ return json.dumps(
354
+ value,
355
+ ensure_ascii=True,
356
+ separators=(",", ":"),
357
+ sort_keys=True,
358
+ allow_nan=False,
359
+ ).encode("utf-8")
360
+
361
+
362
+ def _binding_identity(binding: ConditioningPayloadBinding) -> bytes:
363
+ if binding.kind == "materialized":
364
+ return binding.data
365
+ return binding.fingerprint.encode("utf-8")
366
+
367
+
368
+ def _content_id(binding: ConditioningPayloadBinding) -> str:
369
+ identity = [
370
+ _canonical_json(list(binding.shape)),
371
+ binding.dtype.encode("utf-8"),
372
+ binding.space.encode("utf-8"),
373
+ ]
374
+ if binding.kind != "materialized":
375
+ identity.append(binding.kind.encode("ascii"))
376
+ identity.append(_binding_identity(binding))
377
+ return "pcid:" + stable_hash(identity)
378
+
379
+
380
+ def _binding_signature(binding: ConditioningPayloadBinding) -> tuple[object, ...]:
381
+ return (
382
+ binding.kind,
383
+ binding.shape,
384
+ binding.dtype,
385
+ binding.space,
386
+ _binding_identity(binding),
387
+ )
388
+
389
+
390
+ def _with_reference_id(
391
+ binding: ConditioningPayloadBinding, reference_id: str
392
+ ) -> ConditioningPayloadBinding:
393
+ if binding.kind == "materialized":
394
+ return PayloadBinding(
395
+ reference_id, binding.shape, binding.dtype, binding.space, binding.data
396
+ )
397
+ if binding.kind == "live":
398
+ return LivePayloadBinding(
399
+ reference_id,
400
+ binding.shape,
401
+ binding.dtype,
402
+ binding.space,
403
+ binding.payload,
404
+ binding.fingerprint,
405
+ binding.materialize,
406
+ )
407
+ return ResidentPayloadBinding(
408
+ reference_id,
409
+ binding.shape,
410
+ binding.dtype,
411
+ binding.space,
412
+ binding.payload,
413
+ binding.fingerprint,
414
+ )
415
+
416
+
417
+ def _materialized_binding(binding: ConditioningPayloadBinding) -> PayloadBinding:
418
+ if binding.kind == "materialized":
419
+ return binding
420
+ if binding.kind == "resident":
421
+ raise ConditioningWireError(
422
+ "resident-payload", f"{binding.reference_id!r} cannot materialize across workers"
423
+ )
424
+ try:
425
+ data = binding.materialize(binding.payload)
426
+ except Exception as error:
427
+ raise ConditioningWireError(
428
+ "materialize-payload", f"{binding.reference_id!r}: {error}"
429
+ ) from error
430
+ return PayloadBinding(binding.reference_id, binding.shape, binding.dtype, binding.space, data)
431
+
432
+
433
+ def _materialized_carrier(carrier: ConditioningCarrier) -> ConditioningCarrier:
434
+ if carrier.has_resident_payloads:
435
+ raise ConditioningWireError("resident-payload", "carrier cannot materialize across workers")
436
+ return make_conditioning_carrier(
437
+ carrier.conditioning,
438
+ tuple(_materialized_binding(binding) for binding in carrier.bindings),
439
+ )
440
+
441
+
442
+ def _deferred_carrier_fingerprint(carrier: ConditioningCarrier) -> str:
443
+ return stable_hash(
444
+ [
445
+ canonical_conditioning_set(carrier.conditioning).encode("utf-8"),
446
+ *(
447
+ _canonical_json(
448
+ {
449
+ "id": binding.reference_id,
450
+ "kind": binding.kind,
451
+ "fingerprint": (
452
+ _content_id(binding)
453
+ if binding.kind == "materialized"
454
+ else binding.fingerprint
455
+ ),
456
+ }
457
+ )
458
+ for binding in carrier.bindings
459
+ ),
460
+ ]
461
+ )
462
+
463
+
464
+ def _extension_references(value: ExtensionValue) -> Iterable[PayloadReference]:
465
+ if isinstance(value, PayloadReference):
466
+ yield value
467
+ elif isinstance(value, tuple):
468
+ for item in value:
469
+ yield from _extension_references(item)
470
+ elif isinstance(value, Mapping):
471
+ for item in value.values():
472
+ yield from _extension_references(item)
473
+
474
+
475
+ def _reachable_references(
476
+ value: ConditioningSet,
477
+ ) -> tuple[dict[str, list[tuple[tuple[int, ...], str, str]]], set[str]]:
478
+ described: dict[str, list[tuple[tuple[int, ...], str, str]]] = {}
479
+ reachable: set[str] = set()
480
+
481
+ def descriptor(payload: PayloadDescriptor) -> None:
482
+ reference_id = payload.reference.id
483
+ reachable.add(reference_id)
484
+ described.setdefault(reference_id, []).append((payload.shape, payload.dtype, payload.space))
485
+
486
+ for record in value.records:
487
+ for _, payload in record.channels:
488
+ descriptor(payload)
489
+ if record.mask is not None:
490
+ reachable.add(record.mask.payload.id)
491
+ if record.scale_vector is not None:
492
+ descriptor(record.scale_vector.values)
493
+ for _, metadata in record.extension_metadata:
494
+ for reference in _extension_references(cast("ExtensionValue", metadata)):
495
+ reachable.add(reference.id)
496
+ return described, reachable
497
+
498
+
499
+ def _rewrite_extension(value: ExtensionValue, ids: Mapping[str, str]) -> ExtensionInputValue:
500
+ if isinstance(value, PayloadReference):
501
+ return PayloadReference(ids[value.id])
502
+ if isinstance(value, tuple):
503
+ return tuple(_rewrite_extension(item, ids) for item in value)
504
+ if isinstance(value, Mapping):
505
+ return {key: _rewrite_extension(item, ids) for key, item in value.items()}
506
+ return value
507
+
508
+
509
+ def _rewrite_payload(value: PayloadDescriptor, ids: Mapping[str, str]) -> PayloadDescriptor:
510
+ return PayloadDescriptor(
511
+ PayloadReference(ids[value.reference.id]), value.shape, value.dtype, value.space
512
+ )
513
+
514
+
515
+ def _rewrite_conditioning(value: ConditioningSet, ids: Mapping[str, str]) -> ConditioningSet:
516
+ records: list[ConditioningRecord] = []
517
+ for record in value.records:
518
+ mask = record.mask
519
+ if mask is not None:
520
+ mask = MaskDescriptor(
521
+ PayloadReference(ids[mask.payload.id]),
522
+ mask.strength,
523
+ mask.set_area_to_bounds,
524
+ )
525
+ scale = record.scale_vector
526
+ if scale is not None:
527
+ scale = ConditionScaleVector(_rewrite_payload(scale.values, ids))
528
+ records.append(
529
+ ConditioningRecord(
530
+ channels=tuple(
531
+ (channel, _rewrite_payload(payload, ids))
532
+ for channel, payload in record.channels
533
+ ),
534
+ area=record.area,
535
+ mask=mask,
536
+ schedule=record.schedule,
537
+ scale_vector=scale,
538
+ token_layout=record.token_layout,
539
+ extension_metadata=tuple(
540
+ (key, _rewrite_extension(cast("ExtensionValue", metadata), ids))
541
+ for key, metadata in sorted(record.extension_metadata)
542
+ ),
543
+ )
544
+ )
545
+ return ConditioningSet(tuple(records))
546
+
547
+
548
+ def make_conditioning_carrier(
549
+ conditioning: ConditioningSet, bindings: Iterable[ConditioningPayloadBinding]
550
+ ) -> ConditioningCarrier:
551
+ """Bind every reference, rewrite it to content identity, and deduplicate."""
552
+
553
+ if not isinstance(cast("object", conditioning), ConditioningSet):
554
+ raise ConditioningWireError("invalid-conditioning", "expected ConditioningSet")
555
+ described, reachable = _reachable_references(conditioning)
556
+ if len(reachable) > _MAX_PAYLOADS:
557
+ raise ConditioningWireError("payload-count-limit")
558
+ by_reference: dict[str, ConditioningPayloadBinding] = {}
559
+ for binding in bindings:
560
+ if not isinstance(
561
+ cast("object", binding), (PayloadBinding, LivePayloadBinding, ResidentPayloadBinding)
562
+ ):
563
+ raise ConditioningWireError("invalid-binding", "unknown conditioning payload binding")
564
+ if binding.reference_id not in reachable:
565
+ raise ConditioningWireError("unknown-binding", repr(binding.reference_id))
566
+ previous = by_reference.get(binding.reference_id)
567
+ if previous is not None and _binding_signature(previous) != _binding_signature(binding):
568
+ raise ConditioningWireError("conflicting-binding", repr(binding.reference_id))
569
+ by_reference[binding.reference_id] = binding
570
+ missing = sorted(reachable - by_reference.keys())
571
+ if missing:
572
+ raise ConditioningWireError("unbound-reference", repr(missing[0]))
573
+
574
+ ids: dict[str, str] = {}
575
+ canonical_bindings: dict[str, ConditioningPayloadBinding] = {}
576
+ for reference_id in sorted(reachable):
577
+ binding = by_reference[reference_id]
578
+ for expected in described.get(reference_id, ()):
579
+ if (binding.shape, binding.dtype, binding.space) != expected:
580
+ raise ConditioningWireError("descriptor-mismatch", repr(reference_id))
581
+ content_id = _content_id(binding)
582
+ ids[reference_id] = content_id
583
+ canonical = _with_reference_id(binding, content_id)
584
+ previous = canonical_bindings.get(content_id)
585
+ if previous is not None and _binding_signature(previous) != _binding_signature(canonical):
586
+ raise ConditioningWireError("content-id-collision", content_id)
587
+ canonical_bindings.setdefault(content_id, canonical)
588
+
589
+ rewritten = _rewrite_conditioning(conditioning, ids)
590
+ return ConditioningCarrier(
591
+ rewritten, tuple(canonical_bindings[key] for key in sorted(canonical_bindings))
592
+ )
593
+
594
+
595
+ def _manifest(binding: PayloadBinding) -> dict[str, object]:
596
+ return {
597
+ "content_id": binding.reference_id,
598
+ "shape": list(binding.shape),
599
+ "dtype": binding.dtype,
600
+ "space": binding.space,
601
+ "byte_length": len(binding.data),
602
+ }
603
+
604
+
605
+ def _validate_canonical_carrier(carrier: ConditioningCarrier) -> None:
606
+ if len(carrier.bindings) > _MAX_PAYLOADS:
607
+ raise ConditioningWireError("payload-count-limit")
608
+ ids = [binding.reference_id for binding in carrier.bindings]
609
+ if len(set(ids)) != len(ids):
610
+ raise ConditioningWireError("duplicate-content-id")
611
+ if ids != sorted(ids):
612
+ raise ConditioningWireError("unsorted-content-ids")
613
+ described, reachable = _reachable_references(carrier.conditioning)
614
+ available = set(ids)
615
+ missing = sorted(reachable - available)
616
+ if missing:
617
+ raise ConditioningWireError("unbound-reference", repr(missing[0]))
618
+ unknown = sorted(available - reachable)
619
+ if unknown:
620
+ raise ConditioningWireError("unknown-binding", repr(unknown[0]))
621
+ for binding in carrier.bindings:
622
+ if binding.reference_id != _content_id(binding):
623
+ raise ConditioningWireError("content-id-mismatch", binding.reference_id)
624
+ if any(
625
+ (binding.shape, binding.dtype, binding.space) != requirement
626
+ for requirement in described.get(binding.reference_id, ())
627
+ ):
628
+ raise ConditioningWireError("descriptor-mismatch", repr(binding.reference_id))
629
+
630
+
631
+ def _build_carrier_bytes(carrier: ConditioningCarrier) -> bytes:
632
+ if not isinstance(cast("object", carrier), ConditioningCarrier):
633
+ raise ConditioningWireError("invalid-carrier", "expected ConditioningCarrier")
634
+ _validate_canonical_carrier(carrier)
635
+ materialized_carrier = _materialized_carrier(carrier)
636
+ materialized = cast("tuple[PayloadBinding, ...]", materialized_carrier.bindings)
637
+ header = {
638
+ "format": CONDITIONING_CARRIER_FORMAT,
639
+ "conditioning": json.loads(canonical_conditioning_set(materialized_carrier.conditioning)),
640
+ "payload_manifest": [_manifest(binding) for binding in materialized],
641
+ }
642
+ header_bytes = _canonical_json(header)
643
+ if len(header_bytes) > _MAX_HEADER_BYTES:
644
+ raise ConditioningWireError("header-too-large")
645
+ return b"".join(
646
+ (
647
+ _MAGIC,
648
+ bytes((_VERSION,)),
649
+ struct.pack("<Q", len(header_bytes)),
650
+ header_bytes,
651
+ *(binding.data for binding in materialized),
652
+ )
653
+ )
654
+
655
+
656
+ def encode_conditioning_carrier(carrier: ConditioningCarrier) -> bytes:
657
+ """Fully encode a carrier and retain the exact bytes for codec replay."""
658
+
659
+ encoded = _build_carrier_bytes(carrier)
660
+ object.__setattr__(carrier, "canonical_bytes", encoded)
661
+ return encoded
662
+
663
+
664
+ def _reject_duplicate_keys(pairs: list[tuple[str, object]]) -> dict[str, object]:
665
+ result: dict[str, object] = {}
666
+ for key, value in pairs:
667
+ if key in result:
668
+ raise ConditioningWireError("noncanonical-header", f"duplicate key {key!r}")
669
+ result[key] = value
670
+ return result
671
+
672
+
673
+ def _reject_nonfinite(constant: str) -> object:
674
+ raise ConditioningWireError("malformed-header-json", constant)
675
+
676
+
677
+ def _parse_finite_float(value: str) -> float:
678
+ number = float(value)
679
+ if not math.isfinite(number):
680
+ raise ConditioningWireError("malformed-header-json", "non-finite number")
681
+ return number
682
+
683
+
684
+ def _contains_negative_zero(value: object) -> bool:
685
+ if isinstance(value, float):
686
+ return value == 0.0 and math.copysign(1.0, value) < 0.0
687
+ if isinstance(value, list):
688
+ return any(_contains_negative_zero(item) for item in cast("Sequence[object]", value))
689
+ if isinstance(value, dict):
690
+ return any(
691
+ _contains_negative_zero(item)
692
+ for item in cast("Mapping[object, object]", value).values()
693
+ )
694
+ return False
695
+
696
+
697
+ def _contains_invalid_unicode(value: object) -> bool:
698
+ if isinstance(value, str):
699
+ try:
700
+ value.encode("utf-8")
701
+ except UnicodeEncodeError:
702
+ return True
703
+ return False
704
+ if isinstance(value, list):
705
+ return any(_contains_invalid_unicode(item) for item in cast("Sequence[object]", value))
706
+ if isinstance(value, dict):
707
+ mapping = cast("Mapping[object, object]", value)
708
+ return any(
709
+ _contains_invalid_unicode(key) or _contains_invalid_unicode(item)
710
+ for key, item in mapping.items()
711
+ )
712
+ return False
713
+
714
+
715
+ def _mapping(value: object, code: str) -> Mapping[str, object]:
716
+ if not isinstance(value, dict):
717
+ raise ConditioningWireError(code, "expected object")
718
+ return cast("Mapping[str, object]", value)
719
+
720
+
721
+ def _sequence(value: object, code: str) -> Sequence[object]:
722
+ if not isinstance(value, list):
723
+ raise ConditioningWireError(code, "expected array")
724
+ return cast("Sequence[object]", value)
725
+
726
+
727
+ def _exact_keys(value: Mapping[str, object], expected: set[str], code: str) -> None:
728
+ if set(value) != expected:
729
+ raise ConditioningWireError(code, f"keys are {sorted(value)!r}")
730
+
731
+
732
+ def _decode_payload(value: object) -> PayloadDescriptor:
733
+ payload = _mapping(value, "invalid-conditioning")
734
+ _exact_keys(payload, {"ref", "shape", "dtype", "space"}, "invalid-conditioning")
735
+ reference = payload["ref"]
736
+ shape = payload["shape"]
737
+ dtype = payload["dtype"]
738
+ space = payload["space"]
739
+ if not isinstance(reference, str) or not isinstance(dtype, str) or not isinstance(space, str):
740
+ raise ConditioningWireError("invalid-conditioning", "invalid payload strings")
741
+ dims = _sequence(shape, "invalid-conditioning")
742
+ return PayloadDescriptor(
743
+ PayloadReference(reference), tuple(cast("int", dim) for dim in dims), dtype, space
744
+ )
745
+
746
+
747
+ def _decode_extension(value: object) -> ExtensionInputValue:
748
+ item = _mapping(value, "invalid-conditioning")
749
+ kind = item.get("type")
750
+ if kind == "none":
751
+ _exact_keys(item, {"type"}, "invalid-conditioning")
752
+ return None
753
+ if kind in {"bool", "int", "float", "str"}:
754
+ _exact_keys(item, {"type", "value"}, "invalid-conditioning")
755
+ raw = item["value"]
756
+ expected = {"bool": bool, "int": int, "float": float, "str": str}[cast("str", kind)]
757
+ if type(raw) is not expected:
758
+ raise ConditioningWireError("invalid-conditioning", f"invalid {kind} value")
759
+ return raw
760
+ if kind == "payload-reference":
761
+ _exact_keys(item, {"type", "id"}, "invalid-conditioning")
762
+ if not isinstance(item["id"], str):
763
+ raise ConditioningWireError("invalid-conditioning", "invalid payload reference")
764
+ return PayloadReference(item["id"])
765
+ if kind == "sequence":
766
+ _exact_keys(item, {"type", "items"}, "invalid-conditioning")
767
+ return tuple(
768
+ _decode_extension(child) for child in _sequence(item["items"], "invalid-conditioning")
769
+ )
770
+ if kind == "mapping":
771
+ _exact_keys(item, {"type", "entries"}, "invalid-conditioning")
772
+ result: dict[str, ExtensionInputValue] = {}
773
+ for raw_entry in _sequence(item["entries"], "invalid-conditioning"):
774
+ entry = _sequence(raw_entry, "invalid-conditioning")
775
+ if len(entry) != 2 or not isinstance(entry[0], str) or entry[0] in result:
776
+ raise ConditioningWireError("invalid-conditioning", "invalid mapping entry")
777
+ result[entry[0]] = _decode_extension(entry[1])
778
+ return result
779
+ raise ConditioningWireError("invalid-conditioning", f"unknown extension type {kind!r}")
780
+
781
+
782
+ def _decode_conditioning(value: object) -> ConditioningSet:
783
+ root = _mapping(value, "invalid-conditioning")
784
+ _exact_keys(root, {"format", "records"}, "invalid-conditioning")
785
+ if root["format"] != "dinkster-conditioning-set-v1":
786
+ raise ConditioningWireError("invalid-conditioning", "unknown conditioning format")
787
+ records: list[ConditioningRecord] = []
788
+ for raw_record in _sequence(root["records"], "invalid-conditioning"):
789
+ record = _mapping(raw_record, "invalid-conditioning")
790
+ _exact_keys(
791
+ record,
792
+ {
793
+ "channels",
794
+ "area",
795
+ "mask",
796
+ "schedule",
797
+ "scale_vector",
798
+ "token_layout",
799
+ "extension_metadata",
800
+ },
801
+ "invalid-conditioning",
802
+ )
803
+ channels: list[tuple[ConditioningChannel, PayloadDescriptor]] = []
804
+ for raw_channel in _sequence(record["channels"], "invalid-conditioning"):
805
+ channel = _mapping(raw_channel, "invalid-conditioning")
806
+ _exact_keys(channel, {"id", "payload"}, "invalid-conditioning")
807
+ if not isinstance(channel["id"], str):
808
+ raise ConditioningWireError("invalid-conditioning", "invalid channel id")
809
+ channels.append(
810
+ (ConditioningChannel(channel["id"]), _decode_payload(channel["payload"]))
811
+ )
812
+
813
+ area = None
814
+ if record["area"] is not None:
815
+ raw_area = _mapping(record["area"], "invalid-conditioning")
816
+ area_keys = {"height", "width", "y", "x", "units", "strength"}
817
+ if set(raw_area) not in (area_keys, area_keys | {"temporal", "z"}):
818
+ raise ConditioningWireError(
819
+ "invalid-conditioning", f"keys are {sorted(raw_area)!r}"
820
+ )
821
+ area = AreaDescriptor(
822
+ cast("int | float", raw_area["height"]),
823
+ cast("int | float", raw_area["width"]),
824
+ cast("int | float", raw_area["y"]),
825
+ cast("int | float", raw_area["x"]),
826
+ AreaUnits(cast("str", raw_area["units"])),
827
+ cast("float", raw_area["strength"]),
828
+ cast("float | None", raw_area.get("temporal")),
829
+ cast("float | None", raw_area.get("z")),
830
+ )
831
+
832
+ mask = None
833
+ if record["mask"] is not None:
834
+ raw_mask = _mapping(record["mask"], "invalid-conditioning")
835
+ _exact_keys(
836
+ raw_mask,
837
+ {"payload_ref", "strength", "set_area_to_bounds"},
838
+ "invalid-conditioning",
839
+ )
840
+ mask = MaskDescriptor(
841
+ PayloadReference(cast("str", raw_mask["payload_ref"])),
842
+ cast("float", raw_mask["strength"]),
843
+ cast("bool", raw_mask["set_area_to_bounds"]),
844
+ )
845
+
846
+ raw_range = _mapping(record["schedule"], "invalid-conditioning")
847
+ if raw_range.get("kind") == "empty":
848
+ _exact_keys(raw_range, {"kind"}, "invalid-conditioning")
849
+ schedule = EMPTY_RANGE
850
+ elif raw_range.get("kind") == "percent":
851
+ _exact_keys(raw_range, {"kind", "start", "end"}, "invalid-conditioning")
852
+ schedule = PercentRange(
853
+ cast("float", raw_range["start"]), cast("float", raw_range["end"])
854
+ )
855
+ else:
856
+ raise ConditioningWireError("invalid-conditioning", "invalid schedule kind")
857
+
858
+ scale = None
859
+ if record["scale_vector"] is not None:
860
+ scale = ConditionScaleVector(_decode_payload(record["scale_vector"]))
861
+
862
+ layout = None
863
+ if record["token_layout"] is not None:
864
+ raw_layout = _mapping(record["token_layout"], "invalid-conditioning")
865
+ _exact_keys(
866
+ raw_layout,
867
+ {"family_id", "version", "text_streams", "segments"},
868
+ "invalid-conditioning",
869
+ )
870
+ segments: list[TokenSegmentDescriptor] = []
871
+ for raw_segment in _sequence(raw_layout["segments"], "invalid-conditioning"):
872
+ segment = _mapping(raw_segment, "invalid-conditioning")
873
+ _exact_keys(
874
+ segment,
875
+ {"name", "stream", "start_token", "token_count"},
876
+ "invalid-conditioning",
877
+ )
878
+ segments.append(
879
+ TokenSegmentDescriptor(
880
+ cast("str", segment["name"]),
881
+ cast("str", segment["stream"]),
882
+ cast("int", segment["start_token"]),
883
+ cast("int | None", segment["token_count"]),
884
+ )
885
+ )
886
+ layout = TokenLayoutDescriptor(
887
+ cast("str", raw_layout["family_id"]),
888
+ cast("int", raw_layout["version"]),
889
+ tuple(
890
+ cast("str", stream)
891
+ for stream in _sequence(raw_layout["text_streams"], "invalid-conditioning")
892
+ ),
893
+ tuple(segments),
894
+ )
895
+
896
+ metadata = _mapping(record["extension_metadata"], "invalid-conditioning")
897
+ records.append(
898
+ ConditioningRecord(
899
+ channels=tuple(channels),
900
+ area=area,
901
+ mask=mask,
902
+ schedule=schedule,
903
+ scale_vector=scale,
904
+ token_layout=layout,
905
+ extension_metadata=tuple(
906
+ (key, _decode_extension(raw)) for key, raw in metadata.items()
907
+ ),
908
+ )
909
+ )
910
+ result = ConditioningSet(tuple(records))
911
+ if json.loads(canonical_conditioning_set(result)) != value:
912
+ raise ConditioningWireError("noncanonical-conditioning")
913
+ return result
914
+
915
+
916
+ def decode_conditioning_carrier(
917
+ data: bytes, envelope_metadata: Mapping[str, object] | None = None
918
+ ) -> ConditioningCarrier:
919
+ """Parse, validate, and reconstruct a canonical conditioning carrier."""
920
+
921
+ if (
922
+ envelope_metadata is not None
923
+ and envelope_metadata.get("format") != CONDITIONING_CARRIER_FORMAT
924
+ ):
925
+ raise ConditioningWireError("metadata-format-mismatch")
926
+ if len(data) < _PREFIX_SIZE:
927
+ raise ConditioningWireError("truncated-prefix")
928
+ if data[:4] != _MAGIC:
929
+ raise ConditioningWireError("wrong-magic")
930
+ if data[4] != _VERSION:
931
+ raise ConditioningWireError("unknown-version", str(data[4]))
932
+ header_length = struct.unpack("<Q", data[5:13])[0]
933
+ if header_length > _MAX_HEADER_BYTES:
934
+ raise ConditioningWireError("header-too-large")
935
+ if header_length > len(data) - _PREFIX_SIZE:
936
+ raise ConditioningWireError("truncated-header")
937
+ header_bytes = data[_PREFIX_SIZE : _PREFIX_SIZE + header_length]
938
+ try:
939
+ header: object = json.loads(
940
+ header_bytes,
941
+ object_pairs_hook=_reject_duplicate_keys,
942
+ parse_constant=_reject_nonfinite,
943
+ parse_float=_parse_finite_float,
944
+ )
945
+ if _contains_invalid_unicode(header):
946
+ raise ConditioningWireError("malformed-header-json", "invalid Unicode scalar")
947
+ if _contains_negative_zero(header) or _canonical_json(header) != header_bytes:
948
+ raise ConditioningWireError("noncanonical-header")
949
+ except ConditioningWireError:
950
+ raise
951
+ except (UnicodeError, json.JSONDecodeError, RecursionError, ValueError) as error:
952
+ raise ConditioningWireError("malformed-header-json", str(error)) from None
953
+ root = _mapping(header, "malformed-header-json")
954
+ _exact_keys(root, {"format", "conditioning", "payload_manifest"}, "malformed-header-json")
955
+ if root["format"] != CONDITIONING_CARRIER_FORMAT:
956
+ raise ConditioningWireError("unknown-format-tag", repr(root["format"]))
957
+ raw_manifest = _sequence(root["payload_manifest"], "malformed-manifest")
958
+ if len(raw_manifest) > _MAX_PAYLOADS:
959
+ raise ConditioningWireError("payload-count-limit")
960
+
961
+ manifest: list[PayloadBinding] = []
962
+ offset = _PREFIX_SIZE + header_length
963
+ ids: list[str] = []
964
+ for raw_entry in raw_manifest:
965
+ entry = _mapping(raw_entry, "malformed-manifest")
966
+ _exact_keys(
967
+ entry,
968
+ {"content_id", "shape", "dtype", "space", "byte_length"},
969
+ "malformed-manifest",
970
+ )
971
+ content_id = entry["content_id"]
972
+ dtype = entry["dtype"]
973
+ space = entry["space"]
974
+ byte_length = entry["byte_length"]
975
+ if (
976
+ not isinstance(content_id, str)
977
+ or not isinstance(dtype, str)
978
+ or not isinstance(space, str)
979
+ ):
980
+ raise ConditioningWireError("malformed-manifest", "invalid string field")
981
+ if dtype not in _DTYPE_WIDTHS:
982
+ raise ConditioningWireError("unknown-dtype", repr(dtype))
983
+ if type(byte_length) is not int or byte_length < 0:
984
+ raise ConditioningWireError("malformed-manifest", "invalid byte_length")
985
+ dims = _sequence(entry["shape"], "malformed-manifest")
986
+ shape = tuple(cast("int", dim) for dim in dims)
987
+ if not shape or any(type(dim) is not int or dim < 0 for dim in shape):
988
+ raise ConditioningWireError("malformed-manifest", "invalid shape")
989
+ if byte_length != math.prod(shape) * _DTYPE_WIDTHS[dtype]:
990
+ raise ConditioningWireError("segment-length-mismatch", content_id)
991
+ end = offset + byte_length
992
+ if end > len(data):
993
+ raise ConditioningWireError("segment-length-mismatch", content_id)
994
+ binding = PayloadBinding(content_id, shape, dtype, space, data[offset:end])
995
+ ids.append(content_id)
996
+ manifest.append(binding)
997
+ offset = end
998
+ if len(set(ids)) != len(ids):
999
+ raise ConditioningWireError("duplicate-content-id")
1000
+ if ids != sorted(ids):
1001
+ raise ConditioningWireError("unsorted-content-ids")
1002
+ if offset != len(data):
1003
+ raise ConditioningWireError("trailing-bytes")
1004
+ for binding in manifest:
1005
+ if binding.reference_id != _content_id(binding):
1006
+ raise ConditioningWireError("content-id-mismatch", binding.reference_id)
1007
+
1008
+ try:
1009
+ conditioning = _decode_conditioning(root["conditioning"])
1010
+ except ConditioningWireError:
1011
+ raise
1012
+ except (TypeError, ValueError) as error:
1013
+ raise ConditioningWireError("invalid-conditioning", str(error)) from None
1014
+ described, reachable = _reachable_references(conditioning)
1015
+ manifest_by_id = {binding.reference_id: binding for binding in manifest}
1016
+ missing = sorted(reachable - manifest_by_id.keys())
1017
+ if missing:
1018
+ raise ConditioningWireError("unbound-reference", repr(missing[0]))
1019
+ unknown = sorted(manifest_by_id.keys() - reachable)
1020
+ if unknown:
1021
+ raise ConditioningWireError("unknown-binding", repr(unknown[0]))
1022
+ for reference_id, requirements in described.items():
1023
+ binding = manifest_by_id[reference_id]
1024
+ if any((binding.shape, binding.dtype, binding.space) != item for item in requirements):
1025
+ raise ConditioningWireError("descriptor-mismatch", repr(reference_id))
1026
+ carrier = ConditioningCarrier(conditioning, tuple(manifest), data)
1027
+ if _build_carrier_bytes(carrier) != data:
1028
+ raise ConditioningWireError("noncanonical-carrier")
1029
+ return carrier
1030
+
1031
+
1032
+ def register_conditioning_type(
1033
+ registry: TypeRegistry,
1034
+ *,
1035
+ resident_table: ResidencyTable | None = None,
1036
+ resident_meta: Callable[[object], Mapping[str, object]] | None = None,
1037
+ ) -> TypeSpec:
1038
+ """Register canonical and process-resident conditioning carriers."""
1039
+
1040
+ resident_codec = ResidentCodec(resident_table, resident_meta)
1041
+
1042
+ def coerce(obj: object) -> object:
1043
+ if type(obj) is list:
1044
+ payload = cast("list[object]", obj)
1045
+ return (
1046
+ ResidentConditioningCarrier(payload)
1047
+ if _conditioning_hooks(payload) or _conditioning_gligens(payload)
1048
+ else payload
1049
+ )
1050
+ if (
1051
+ not isinstance(obj, ConditioningCarrier)
1052
+ and type(obj) is not ResidentConditioningCarrier
1053
+ ):
1054
+ raise ConditioningWireError(
1055
+ "invalid-carrier", "expected canonical or resident conditioning carrier"
1056
+ )
1057
+ return obj
1058
+
1059
+ def fingerprint(obj: object) -> str:
1060
+ if type(obj) is list:
1061
+ return resident_codec.fingerprint(cast(object, obj))
1062
+ if type(obj) is ResidentConditioningCarrier:
1063
+ if type(obj.payload) is list:
1064
+ return stable_hash(
1065
+ [
1066
+ resident_codec.fingerprint(owner).encode("utf-8")
1067
+ for owner in resident_owners(obj)
1068
+ ]
1069
+ )
1070
+ return resident_codec.fingerprint(obj)
1071
+ carrier = cast("ConditioningCarrier", obj)
1072
+ if carrier.has_resident_payloads:
1073
+ return resident_codec.fingerprint(carrier)
1074
+ if any(binding.kind == "live" for binding in carrier.bindings):
1075
+ return _deferred_carrier_fingerprint(carrier)
1076
+ encoded = encode_conditioning_carrier(carrier)
1077
+ return stable_hash([encoded])
1078
+
1079
+ def encode(obj: object) -> bytes:
1080
+ if type(obj) is list:
1081
+ return _RESIDENT_MAGIC + resident_codec.encode(cast(object, obj))
1082
+ if type(obj) is ResidentConditioningCarrier:
1083
+ return _RESIDENT_MAGIC + resident_codec.encode(obj)
1084
+ carrier = cast("ConditioningCarrier", obj)
1085
+ if carrier.has_resident_payloads:
1086
+ return _RESIDENT_MAGIC + resident_codec.encode(carrier)
1087
+ if carrier.canonical_bytes is None:
1088
+ return encode_conditioning_carrier(carrier)
1089
+ return carrier.canonical_bytes
1090
+
1091
+ def decode(data: bytes) -> object:
1092
+ if data.startswith(_RESIDENT_MAGIC):
1093
+ value = resident_codec.decode(data[len(_RESIDENT_MAGIC) :])
1094
+ if type(value) not in (ConditioningCarrier, ResidentConditioningCarrier, list):
1095
+ raise ConditioningWireError("invalid-resident-carrier")
1096
+ return value
1097
+ return decode_conditioning_carrier(data)
1098
+
1099
+ def validate_encoded(data: bytes, metadata: Mapping[str, object]) -> None:
1100
+ if data.startswith(_RESIDENT_MAGIC):
1101
+ if metadata.get("format") != RESIDENT_CONDITIONING_FORMAT:
1102
+ raise ConditioningWireError("metadata-format")
1103
+ try:
1104
+ resident_codec.validate_encoded(data[len(_RESIDENT_MAGIC) :])
1105
+ except ResidentLookupError as error:
1106
+ raise ConditioningWireError("malformed-resident-stub", str(error)) from None
1107
+ return
1108
+ decode_conditioning_carrier(data, metadata)
1109
+
1110
+ def metadata(obj: object) -> Mapping[str, object]:
1111
+ if type(obj) is list:
1112
+ return {
1113
+ **resident_codec.metadata(cast(object, obj)),
1114
+ "format": RESIDENT_CONDITIONING_FORMAT,
1115
+ }
1116
+ if type(obj) is ResidentConditioningCarrier or (
1117
+ type(obj) is ConditioningCarrier and obj.has_resident_payloads
1118
+ ):
1119
+ return {
1120
+ **resident_codec.metadata(obj),
1121
+ "format": RESIDENT_CONDITIONING_FORMAT,
1122
+ }
1123
+ return {"format": CONDITIONING_CARRIER_FORMAT}
1124
+
1125
+ def input_convert(obj: object) -> object:
1126
+ if type(obj) is ResidentConditioningCarrier:
1127
+ payload = obj.payload
1128
+ return getattr(payload, "_dinkster_input_value", payload)
1129
+ return obj
1130
+
1131
+ spec = registry.register(
1132
+ CONDITIONING_TYPE_ID,
1133
+ encode=encode,
1134
+ decode=decode,
1135
+ fingerprint=fingerprint,
1136
+ meta=metadata,
1137
+ coerce=coerce,
1138
+ input_convert=input_convert,
1139
+ validate_encoded=validate_encoded,
1140
+ )
1141
+ if resident_table is not None:
1142
+ registry.register_resident_table(resident_table)
1143
+ return spec