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,210 @@
1
+ """Process-resident values: the objects never cross the boundary, stubs do.
2
+
3
+ A loaded model, text encoder, or codec is gigabytes of device state -
4
+ encoding it with the default pickle codec would be a catastrophe (huge
5
+ transfer, and unpicklable on a torch-less parent). Instead, resident types
6
+ register a codec that encodes a *resident id*: the object stays in the
7
+ holding process's residency table, other processes carry an interrogable
8
+ stub, and when the stub comes back as a later invocation's input the codec
9
+ resolves it from the table.
10
+
11
+ This is the engine-level ResourceHandle's identity-crosses/content-stays
12
+ shape, implemented entirely with the public TypeRegistry codec hooks - any
13
+ pack or package can register a resident type without touching engine or
14
+ worker code. One limit is deliberate:
15
+
16
+ - fingerprints are per-process resident ids, so cross-run caches will not
17
+ hit on resident values (the loader's own cache key still hits because it
18
+ is built from the loader's inputs).
19
+
20
+ A bare ResidencyTable holds strong references until the process exits. A
21
+ production residency pool may coordinate reference invalidation and remove
22
+ an owner together with all resident values that depend on it.
23
+ """
24
+
25
+ from __future__ import annotations
26
+
27
+ import json
28
+ import uuid
29
+ from collections.abc import Callable, Mapping
30
+ from typing import cast
31
+
32
+ from .model import (
33
+ RESOURCE_ID_META_KEY,
34
+ RESOURCE_OWNER_META_KEY,
35
+ RESOURCE_REFS_META_KEY,
36
+ process_instance_token,
37
+ )
38
+ from .registry import TypeRegistry, TypeSpec
39
+
40
+
41
+ class ResidentLookupError(Exception):
42
+ """A resident stub arrived in a process that does not hold the value."""
43
+
44
+
45
+ def resident_resource_id(rid: str) -> str:
46
+ """The resident's identity as holders see it: the codec fingerprint,
47
+ the envelope's RESOURCE_ID_META_KEY, and the ID caches invalidate by
48
+ are all this one string."""
49
+ return "resident:" + rid
50
+
51
+
52
+ class ResidencyTable:
53
+ """One per holding process: resident id -> live object.
54
+
55
+ Idempotent per object (same object, same id), so fingerprinting and
56
+ payload encoding agree, and re-sending the same value re-uses the id.
57
+ """
58
+
59
+ def __init__(self) -> None:
60
+ self._objects: dict[str, object] = {}
61
+ self._ids_by_identity: dict[int, str] = {}
62
+
63
+ def rid_for(self, obj: object) -> str:
64
+ rid = self._ids_by_identity.get(id(obj))
65
+ if rid is None or self._objects.get(rid) is not obj:
66
+ rid = uuid.uuid4().hex
67
+ self._objects[rid] = obj
68
+ self._ids_by_identity[id(obj)] = rid
69
+ return rid
70
+
71
+ def get(self, rid: str) -> object:
72
+ try:
73
+ return self._objects[rid]
74
+ except KeyError:
75
+ raise ResidentLookupError(
76
+ f"resident value {rid!r} is not held by this process; it "
77
+ "belongs to another worker or an earlier worker lifetime"
78
+ ) from None
79
+
80
+ def remove(self, rid: str) -> object | None:
81
+ """Drop the table's strong reference; None when already gone.
82
+
83
+ Only for coordinated release (invalidate references first, then
84
+ remove): a stub for a removed resident raises ResidentLookupError
85
+ from then on.
86
+ """
87
+ obj = self._objects.pop(rid, None)
88
+ if obj is not None:
89
+ self._ids_by_identity.pop(id(obj), None)
90
+ return obj
91
+
92
+ def __len__(self) -> int:
93
+ return len(self._objects)
94
+
95
+
96
+ _TABLE = ResidencyTable()
97
+ """Module-level: the holding process's single default residency table."""
98
+
99
+
100
+ def resident_owners(obj: object) -> tuple[object, ...]:
101
+ """The primary resident owner followed by additional referenced owners."""
102
+ primary = cast("object", getattr(obj, "_dinkster_resident_owner", obj))
103
+ refs_value = cast("object", getattr(obj, "_dinkster_resident_refs", ()))
104
+ if not isinstance(refs_value, tuple):
105
+ raise TypeError("_dinkster_resident_refs must be a tuple")
106
+ refs = cast("tuple[object, ...]", refs_value)
107
+ owners: list[object] = []
108
+ identities: set[int] = set()
109
+ for owner in (primary, *refs):
110
+ if owner is None:
111
+ raise TypeError("resident owners must not be None")
112
+ if id(owner) in identities:
113
+ continue
114
+ identities.add(id(owner))
115
+ owners.append(owner)
116
+ return tuple(owners)
117
+
118
+
119
+ class ResidentCodec:
120
+ """Reusable codec functions for a type that admits resident values."""
121
+
122
+ def __init__(
123
+ self,
124
+ table: ResidencyTable | None = None,
125
+ meta: Callable[[object], Mapping[str, object]] | None = None,
126
+ ) -> None:
127
+ self._table = table if table is not None else _TABLE
128
+ self._meta = meta
129
+
130
+ def metadata(self, obj: object) -> Mapping[str, object]:
131
+ owners = resident_owners(obj)
132
+ owner = owners[0]
133
+ enriched: dict[str, object] = dict(self._meta(owner)) if self._meta is not None else {}
134
+ enriched[RESOURCE_ID_META_KEY] = resident_resource_id(self._table.rid_for(owner))
135
+ additional = tuple(
136
+ resident_resource_id(self._table.rid_for(reference)) for reference in owners[1:]
137
+ )
138
+ if additional:
139
+ enriched[RESOURCE_REFS_META_KEY] = additional
140
+ enriched[RESOURCE_OWNER_META_KEY] = process_instance_token()
141
+ return enriched
142
+
143
+ def encode(self, obj: object) -> bytes:
144
+ return json.dumps({"residentId": self._table.rid_for(obj)}).encode("utf-8")
145
+
146
+ def decode(self, data: bytes) -> object:
147
+ wire = cast("dict[str, object]", json.loads(data))
148
+ rid = wire.get("residentId")
149
+ if not isinstance(rid, str):
150
+ raise ResidentLookupError(f"malformed resident stub: {data!r}")
151
+ return self._table.get(rid)
152
+
153
+ def validate_encoded(self, data: bytes) -> None:
154
+ try:
155
+ parsed: object = json.loads(data)
156
+ except (UnicodeDecodeError, json.JSONDecodeError):
157
+ raise ResidentLookupError(f"malformed resident stub: {data!r}") from None
158
+ if not isinstance(parsed, dict):
159
+ raise ResidentLookupError(f"malformed resident stub: {data!r}")
160
+ wire = cast("dict[object, object]", parsed)
161
+ if set(wire) != {"residentId"}:
162
+ raise ResidentLookupError(f"malformed resident stub: {data!r}")
163
+ if not isinstance(wire["residentId"], str) or not wire["residentId"]:
164
+ raise ResidentLookupError(f"malformed resident stub: {data!r}")
165
+
166
+ def fingerprint(self, obj: object) -> str:
167
+ declared = getattr(obj, "_dinkster_resident_fingerprint", None)
168
+ if declared is not None:
169
+ if not isinstance(declared, str) or not declared:
170
+ raise TypeError("_dinkster_resident_fingerprint must be a non-empty string")
171
+ return declared
172
+ return resident_resource_id(self._table.rid_for(obj))
173
+
174
+
175
+ def register_resident_type(
176
+ registry: TypeRegistry,
177
+ type_id: str,
178
+ table: ResidencyTable | None = None,
179
+ meta: Callable[[object], Mapping[str, object]] | None = None,
180
+ *,
181
+ coerce: Callable[[object], object] | None = None,
182
+ ) -> TypeSpec:
183
+ """``meta`` publishes residency/cost for the live object (device lanes,
184
+ VRAM cost) - it rides the envelope across the boundary even though the
185
+ object itself never does. Every resident envelope additionally carries
186
+ RESOURCE_ID_META_KEY: the value is a *reference* to owner-resolved
187
+ state, so holders exclude its cost from their accounting and can be
188
+ asked to drop entries referencing it (invalidate-then-release)."""
189
+ codec = ResidentCodec(table, meta)
190
+
191
+ spec = registry.register(
192
+ type_id,
193
+ encode=codec.encode,
194
+ decode=codec.decode,
195
+ fingerprint=codec.fingerprint,
196
+ meta=codec.metadata,
197
+ coerce=coerce,
198
+ )
199
+ registry.register_resident_table(table if table is not None else _TABLE)
200
+ return spec
201
+
202
+
203
+ __all__ = [
204
+ "ResidencyTable",
205
+ "ResidentCodec",
206
+ "ResidentLookupError",
207
+ "register_resident_type",
208
+ "resident_owners",
209
+ "resident_resource_id",
210
+ ]
@@ -0,0 +1,210 @@
1
+ """ResourceHandle: envelope values for things that cannot cross a wire raw.
2
+
3
+ Models/VAE/CLIP are not data - they are loaded hardware state. A
4
+ ResourceHandle is the envelope-shaped truth about one: a stable identity
5
+ (the basis of cache keys), residency (which concrete devices hold it),
6
+ cost (bytes by residency class, what the MemoryGovernor accounts), and -
7
+ only where the resource actually lives - the runtime object itself.
8
+
9
+ Crossing a boundary carries identity + residency + cost and drops the
10
+ object: the receiving side gets an interrogable, schedulable handle it
11
+ cannot resolve. Placement routes consumers to the owner (or consciously
12
+ transfers); a worker that hits ``require_obj()`` on a non-local handle
13
+ has been mis-scheduled, and the error says so.
14
+ """
15
+
16
+ from __future__ import annotations
17
+
18
+ import json
19
+ from collections.abc import Mapping
20
+ from dataclasses import dataclass, field
21
+ from typing import cast
22
+
23
+ from .builtin_types import RESOURCE_HANDLE_TYPE
24
+
25
+ # RESOURCE_ID_META_KEY's canonical home is model.py (the traversal helpers
26
+ # in lists.py need it below the registry layer); re-exported here where the
27
+ # resource docs live.
28
+ from .model import (
29
+ RESOURCE_ID_META_KEY,
30
+ RESOURCE_OWNER_META_KEY,
31
+ RESOURCES_META_KEY,
32
+ process_instance_token,
33
+ )
34
+ from .registry import TypeRegistry
35
+
36
+ COST_META_KEY = "cost"
37
+ """Well-known ValueMeta entry: mapping of residency class -> bytes.
38
+
39
+ Residency classes are ``"ram"``, ``"disk"``, and ``"vram:<device>"``
40
+ (device-qualified, because budgets are per device: ``"vram:cuda:0"``).
41
+ Cost is scheduling/accounting metadata only - never part of the
42
+ fingerprint, for the same reason residency is not: the same computation
43
+ on different hardware is the same computation.
44
+ """
45
+
46
+
47
+ def unqualified_cost(cost: object) -> dict[str, int]:
48
+ """Compare codec byte counts independently of remote residency qualifiers."""
49
+ if not isinstance(cost, Mapping):
50
+ raise ValueError("cost must be a residency mapping")
51
+ result: dict[str, int] = {}
52
+ for residency, nbytes in cast("Mapping[object, object]", cost).items():
53
+ if not isinstance(residency, str) or type(nbytes) is not int or nbytes < 0:
54
+ raise ValueError("cost requires residency names and nonnegative integer bytes")
55
+ name = residency.partition("@")[0]
56
+ if name in result:
57
+ raise ValueError("cost contains duplicate unqualified residencies")
58
+ result[name] = nbytes
59
+ return result
60
+
61
+
62
+ class ResourceError(Exception):
63
+ """A resource handle was used somewhere its resource does not live."""
64
+
65
+
66
+ @dataclass(frozen=True)
67
+ class ResourceHandle:
68
+ """Identity + residency + cost for a non-serializable resource.
69
+
70
+ resource_id is the stable identity: derive it from content identity
71
+ plus load parameters (e.g. ``blake3:<hex>?dtype=fp16``), never from
72
+ id(), paths, or load order - it is the fingerprint, so it decides
73
+ cache hits.
74
+
75
+ residency uses the RESOURCES_META_KEY shape: resource kind -> concrete
76
+ instance id(s), one (``{"gpu": "cuda:1"}``) or a tuple for a resource
77
+ spanning devices (``{"gpu": ("cuda:0", "cuda:1")}``, the multigpu
78
+ case).
79
+
80
+ cost uses the COST_META_KEY shape: residency class -> bytes.
81
+ """
82
+
83
+ resource_id: str
84
+ kind: str
85
+ residency: Mapping[str, str | tuple[str, ...]] = field(
86
+ default_factory=dict[str, str | tuple[str, ...]]
87
+ )
88
+ cost: Mapping[str, int] = field(default_factory=dict[str, int])
89
+ obj: object | None = None
90
+ owner: str | None = None
91
+ """Producer-stamped owner provenance for a NON-LOCAL handle: the
92
+ process-instance token of the worker holding the object, carried so a
93
+ relay re-wrapping this handle preserves provenance it did not create
94
+ (RESOURCE_OWNER_META_KEY). Ignored when the handle is local - the
95
+ holding process always stamps its own live token, never a remembered
96
+ one. None means the producer predates owner stamping."""
97
+
98
+ def __post_init__(self) -> None:
99
+ residency = {
100
+ key: tuple(value) if not isinstance(value, str) else value
101
+ for key, value in self.residency.items()
102
+ }
103
+ # Private copies preserve boundary serialization (mapping proxies
104
+ # are neither JSON serializable nor pickleable).
105
+ object.__setattr__(self, "residency", residency)
106
+ object.__setattr__(self, "cost", dict(self.cost))
107
+
108
+ @property
109
+ def is_local(self) -> bool:
110
+ return self.obj is not None
111
+
112
+ def require_obj(self) -> object:
113
+ if self.obj is None:
114
+ raise ResourceError(
115
+ f"resource {self.resource_id!r} ({self.kind}) is not local to "
116
+ "this worker; the scheduler must route its consumers to the "
117
+ "owner or transfer it explicitly"
118
+ )
119
+ return self.obj
120
+
121
+
122
+ def _encode_handle(obj: object) -> bytes:
123
+ handle = _require_handle(obj)
124
+ wire = {
125
+ "resourceId": handle.resource_id,
126
+ "kind": handle.kind,
127
+ "residency": {
128
+ k: list(v) if isinstance(v, tuple) else v for k, v in handle.residency.items()
129
+ },
130
+ "cost": dict(handle.cost),
131
+ }
132
+ # Owner provenance crosses the wire so the receiving side can keep
133
+ # relaying it: a local handle is owned HERE (stamp this lifetime's
134
+ # token), a non-local one keeps whatever its producer stamped.
135
+ owner = process_instance_token() if handle.is_local else handle.owner
136
+ if owner is not None:
137
+ wire["owner"] = owner
138
+ return json.dumps(wire, sort_keys=True, separators=(",", ":")).encode("utf-8")
139
+
140
+
141
+ def _decode_handle(data: bytes) -> object:
142
+ wire = cast(Mapping[str, object], json.loads(data))
143
+ residency_raw = cast(Mapping[str, object], wire.get("residency") or {})
144
+ residency: dict[str, str | tuple[str, ...]] = {}
145
+ for k, v in residency_raw.items():
146
+ if isinstance(v, list):
147
+ residency[k] = tuple(cast(list[str], v))
148
+ else:
149
+ residency[k] = cast(str, v)
150
+ cost = {
151
+ k: int(cast(int, v)) for k, v in cast(Mapping[str, object], wire.get("cost") or {}).items()
152
+ }
153
+ owner_raw = wire.get("owner")
154
+ return ResourceHandle(
155
+ resource_id=cast(str, wire["resourceId"]),
156
+ kind=cast(str, wire["kind"]),
157
+ residency=residency,
158
+ cost=cost,
159
+ obj=None, # crossing the wire drops locality by construction
160
+ # Carried, not minted: whatever the producing side stamped rides
161
+ # along so a further relay preserves it (malformed means absent).
162
+ owner=owner_raw if isinstance(owner_raw, str) and owner_raw else None,
163
+ )
164
+
165
+
166
+ def _require_handle(obj: object) -> ResourceHandle:
167
+ if not isinstance(obj, ResourceHandle):
168
+ raise TypeError(
169
+ f"{RESOURCE_HANDLE_TYPE} values must be ResourceHandle, got {type(obj).__name__}"
170
+ )
171
+ return obj
172
+
173
+
174
+ def _handle_meta(obj: object) -> Mapping[str, object]:
175
+ handle = _require_handle(obj)
176
+ meta: dict[str, object] = {
177
+ RESOURCE_ID_META_KEY: handle.resource_id,
178
+ "kind": handle.kind,
179
+ }
180
+ if handle.is_local:
181
+ # Owner provenance is stamped where the object actually lives
182
+ # (RESOURCE_OWNER_META_KEY): the holding process stamps its own
183
+ # live token, never a remembered one.
184
+ meta[RESOURCE_OWNER_META_KEY] = process_instance_token()
185
+ elif handle.owner is not None:
186
+ # A decoded non-local handle relaying through this process keeps
187
+ # whatever owner its producer stamped - rewriting provenance we
188
+ # did not create would misroute dispatch.
189
+ meta[RESOURCE_OWNER_META_KEY] = handle.owner
190
+ if handle.residency:
191
+ meta[RESOURCES_META_KEY] = dict(handle.residency)
192
+ if handle.cost:
193
+ meta[COST_META_KEY] = dict(handle.cost)
194
+ return meta
195
+
196
+
197
+ def _handle_fingerprint(obj: object) -> str:
198
+ # Identity is the declared resource_id alone: residency and cost are
199
+ # scheduling facts, so the same model on another device stays a hit.
200
+ return _require_handle(obj).resource_id
201
+
202
+
203
+ def register_resource_handle_type(registry: TypeRegistry) -> None:
204
+ registry.register(
205
+ RESOURCE_HANDLE_TYPE,
206
+ encode=_encode_handle,
207
+ decode=_decode_handle,
208
+ fingerprint=_handle_fingerprint,
209
+ meta=_handle_meta,
210
+ )