@withgateway/sdk 0.6.0 → 0.9.3

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 (150) hide show
  1. package/dist/agents/index.d.mts +581 -0
  2. package/dist/agents/index.d.ts +581 -0
  3. package/dist/agents/index.js +1473 -0
  4. package/dist/agents/index.js.map +1 -0
  5. package/dist/agents/index.mjs +1424 -0
  6. package/dist/agents/index.mjs.map +1 -0
  7. package/dist/apiError-DHpfbmdx.d.mts +17 -0
  8. package/dist/apiError-DHpfbmdx.d.ts +17 -0
  9. package/dist/cli.js +11611 -6845
  10. package/dist/cli.js.map +1 -1
  11. package/dist/cli.mjs +10090 -5325
  12. package/dist/cli.mjs.map +1 -1
  13. package/dist/files/index.d.mts +3 -1
  14. package/dist/files/index.d.ts +3 -1
  15. package/dist/files/index.js +371 -102
  16. package/dist/files/index.js.map +1 -1
  17. package/dist/files/index.mjs +371 -102
  18. package/dist/files/index.mjs.map +1 -1
  19. package/dist/hooks/index.js +346 -136
  20. package/dist/hooks/index.js.map +1 -1
  21. package/dist/hooks/index.mjs +346 -136
  22. package/dist/hooks/index.mjs.map +1 -1
  23. package/dist/{index-LA-PMRJT.d.ts → index-DIN14Lhg.d.ts} +1 -1
  24. package/dist/{index-Di9nNqOY.d.mts → index-DuB-eQ0Z.d.mts} +1 -1
  25. package/dist/index.d.mts +7 -4
  26. package/dist/index.d.ts +7 -4
  27. package/dist/index.js +3177 -748
  28. package/dist/index.js.map +1 -1
  29. package/dist/index.mjs +2987 -590
  30. package/dist/index.mjs.map +1 -1
  31. package/dist/media-CQUC7TkS.d.mts +39 -0
  32. package/dist/media-DQnBloaX.d.ts +39 -0
  33. package/dist/traces/index.d.mts +3 -1
  34. package/dist/traces/index.d.ts +3 -1
  35. package/dist/traces/index.js +371 -102
  36. package/dist/traces/index.js.map +1 -1
  37. package/dist/traces/index.mjs +371 -102
  38. package/dist/traces/index.mjs.map +1 -1
  39. package/dist/tracing/index.d.mts +3 -2
  40. package/dist/tracing/index.d.ts +3 -2
  41. package/dist/tracing/index.js +257 -16
  42. package/dist/tracing/index.js.map +1 -1
  43. package/dist/tracing/index.mjs +257 -16
  44. package/dist/tracing/index.mjs.map +1 -1
  45. package/dist/transport-CpRe7zgd.d.mts +123 -0
  46. package/dist/transport-CpRe7zgd.d.ts +123 -0
  47. package/dist/worlds/index.d.mts +1986 -1746
  48. package/dist/worlds/index.d.ts +1986 -1746
  49. package/dist/worlds/index.js +1470 -290
  50. package/dist/worlds/index.js.map +1 -1
  51. package/dist/worlds/index.mjs +1465 -286
  52. package/dist/worlds/index.mjs.map +1 -1
  53. package/package.json +6 -1
  54. package/runtime/gatewaysdk/environment/bundle_manifest.py +531 -0
  55. package/runtime/gatewaysdk/environment/factory_documents.py +670 -0
  56. package/runtime/gatewaysdk/environment/factory_rules.py +973 -0
  57. package/runtime/gatewaysdk/environment/factory_shapes.py +253 -0
  58. package/runtime/gatewaysdk/environment/factory_spine.py +1155 -0
  59. package/runtime/gatewaysdk/environment/factory_spine_shapes.py +480 -0
  60. package/runtime/gatewaysdk/environment/schema/__main__.py +2 -2
  61. package/runtime/gatewaysdk/environment/schema/_slack_fidelity.py +8 -23
  62. package/runtime/gatewaysdk/environment/schema/admission.py +61 -59
  63. package/runtime/gatewaysdk/environment/schema/api.py +3 -4
  64. package/runtime/gatewaysdk/environment/schema/assertions.py +7 -1
  65. package/runtime/gatewaysdk/environment/schema/bundle_runtime.py +1 -0
  66. package/runtime/gatewaysdk/environment/schema/call_log.py +20 -0
  67. package/runtime/gatewaysdk/environment/schema/cast.py +133 -67
  68. package/runtime/gatewaysdk/environment/schema/compiler.py +16 -17
  69. package/runtime/gatewaysdk/environment/schema/database/base.py +2 -2
  70. package/runtime/gatewaysdk/environment/schema/handler_errors.py +58 -4
  71. package/runtime/gatewaysdk/environment/schema/host.py +94 -12
  72. package/runtime/gatewaysdk/environment/schema/host_browser.py +48 -0
  73. package/runtime/gatewaysdk/environment/schema/host_control.py +35 -2
  74. package/runtime/gatewaysdk/environment/schema/host_handoff.py +4 -1
  75. package/runtime/gatewaysdk/environment/schema/host_loops.py +27 -4
  76. package/runtime/gatewaysdk/environment/schema/host_metrics.py +69 -0
  77. package/runtime/gatewaysdk/environment/schema/host_requests.py +35 -0
  78. package/runtime/gatewaysdk/environment/schema/host_session.py +20 -2
  79. package/runtime/gatewaysdk/environment/schema/host_surfaces.py +6 -0
  80. package/runtime/gatewaysdk/environment/schema/host_versions.py +100 -19
  81. package/runtime/gatewaysdk/environment/schema/host_workers.py +172 -50
  82. package/runtime/gatewaysdk/environment/schema/ingest.py +12 -3
  83. package/runtime/gatewaysdk/environment/schema/journal.py +7 -2
  84. package/runtime/gatewaysdk/environment/schema/local.py +32 -7
  85. package/runtime/gatewaysdk/environment/schema/mapping.py +1 -1
  86. package/runtime/gatewaysdk/environment/schema/measured_tests.py +187 -0
  87. package/runtime/gatewaysdk/environment/schema/page_checks.py +123 -0
  88. package/runtime/gatewaysdk/environment/schema/platform.py +80 -270
  89. package/runtime/gatewaysdk/environment/schema/platform_query.py +4 -3
  90. package/runtime/gatewaysdk/environment/schema/platform_templates.py +420 -0
  91. package/runtime/gatewaysdk/environment/schema/process_memory.py +76 -0
  92. package/runtime/gatewaysdk/environment/schema/redaction.py +13 -0
  93. package/runtime/gatewaysdk/environment/schema/request_ledger.py +4 -1
  94. package/runtime/gatewaysdk/environment/schema/run_parameters.py +25 -0
  95. package/runtime/gatewaysdk/environment/schema/runtime.py +57 -5
  96. package/runtime/gatewaysdk/environment/schema/scaffold.py +386 -219
  97. package/runtime/gatewaysdk/environment/schema/session_files.py +13 -2
  98. package/runtime/gatewaysdk/environment/schema/shape_catalog.py +493 -0
  99. package/runtime/gatewaysdk/environment/schema/shape_declarations.py +219 -0
  100. package/runtime/gatewaysdk/environment/schema/skill.py +1 -0
  101. package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +1 -1
  102. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +2 -2
  103. package/runtime/gatewaysdk/environment/schema/skills/factory-orchestrator/SKILL.md +147 -0
  104. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/ROWS.md +5 -1
  105. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +8 -6
  106. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +9 -9
  107. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +33 -2
  108. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +6 -6
  109. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/journal-checks.md +17 -2
  110. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/new-world-sandbox.md +1 -1
  111. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/shape-catalog.md +59 -0
  112. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/ui-map.md +3 -2
  113. package/runtime/gatewaysdk/environment/schema/slack.py +55 -10
  114. package/runtime/gatewaysdk/environment/schema/snapshot.py +28 -2
  115. package/runtime/gatewaysdk/environment/schema/tasks.py +25 -2
  116. package/runtime/gatewaysdk/environment/schema/template_record.py +131 -0
  117. package/runtime/gatewaysdk/environment/schema/tools_world.py +7 -5
  118. package/runtime/gatewaysdk/environment/schema/ui.py +54 -33
  119. package/runtime/gatewaysdk/environment/schema/ui_interactions.py +419 -0
  120. package/runtime/gatewaysdk/environment/schema/ui_recorder.js +895 -0
  121. package/runtime/gatewaysdk/environment/schema/ui_replay.py +366 -0
  122. package/runtime/gatewaysdk/environment/schema/ui_replay_record.LICENSE +25 -0
  123. package/runtime/gatewaysdk/environment/schema/ui_replay_record.js +109 -0
  124. package/runtime/gatewaysdk/environment/schema/validation.py +24 -1
  125. package/runtime/gatewaysdk/environment/schema/worker.py +12 -5
  126. package/runtime/gatewaysdk/environment/schema/worker_key.py +38 -0
  127. package/runtime/gatewaysdk/environment/schema/worker_peaks.py +38 -0
  128. package/runtime/gatewaysdk/environment/schema/worker_watch.py +50 -0
  129. package/runtime/gatewaysdk/environment/schema/workers.py +245 -69
  130. package/runtime/gatewaysdk/environment/schema/world_host.py +96 -73
  131. package/runtime/gatewaysdk/environment/schema/world_tests.py +3 -1
  132. package/runtime/gatewaysdk/environment/secret_values.py +1 -1
  133. package/runtime/gatewaysdk/environment/world.py +34 -43
  134. package/runtime/gatewaysdk/environment/world_session_contract.py +7 -34
  135. package/skills/benchmarks-getting-started/SKILL.md +1 -1
  136. package/skills/connector-schema-authoring/SKILL.md +2 -2
  137. package/skills/connector-schema-authoring/connector-worlds.md +3 -2
  138. package/skills/connector-schema-authoring/world-schema.md +36 -23
  139. package/skills/factory-orchestrator/SKILL.md +147 -0
  140. package/skills/world-data-ingestion/ROWS.md +5 -1
  141. package/skills/world-data-ingestion/SKILL.md +8 -6
  142. package/skills/worlds-getting-started/SKILL.md +9 -9
  143. package/skills/worlds-getting-started/references/cli-mcp-map.md +33 -2
  144. package/skills/worlds-getting-started/references/gotchas.md +6 -6
  145. package/skills/worlds-getting-started/references/journal-checks.md +17 -2
  146. package/skills/worlds-getting-started/references/new-world-sandbox.md +1 -1
  147. package/skills/worlds-getting-started/references/shape-catalog.md +59 -0
  148. package/skills/worlds-getting-started/references/ui-map.md +3 -2
  149. package/dist/media-BIApiPzS.d.mts +0 -102
  150. package/dist/media-BIApiPzS.d.ts +0 -102
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@withgateway/sdk",
3
- "version": "0.6.0",
3
+ "version": "0.9.3",
4
4
  "description": "Gateway SDK for TypeScript - A/B experiments, tracing, and observability",
5
5
  "main": "./dist/index.js",
6
6
  "module": "./dist/index.mjs",
@@ -81,6 +81,11 @@
81
81
  "import": "./dist/hooks/index.mjs",
82
82
  "require": "./dist/hooks/index.js"
83
83
  },
84
+ "./agents": {
85
+ "types": "./dist/agents/index.d.ts",
86
+ "import": "./dist/agents/index.mjs",
87
+ "require": "./dist/agents/index.js"
88
+ },
84
89
  "./cli": {
85
90
  "types": "./dist/cli.d.ts",
86
91
  "import": "./dist/cli.mjs",
@@ -0,0 +1,531 @@
1
+ """Stdlib only: the runner vendors this package."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import json
6
+ import re
7
+ from dataclasses import dataclass, field
8
+ from typing import Any
9
+
10
+ from ._toml import tomllib
11
+
12
+ BUNDLE_MANIFEST = "gateway-bundle.toml"
13
+ MIN_BUNDLE_MEMBERS = 1
14
+ MAX_BUNDLE_MEMBERS = 48
15
+ BUNDLE_NOT_A_WORLD = (
16
+ "A world bundle is not itself a world, its members are: drop gateway-env.toml from the bundle, or push it "
17
+ "as its own world."
18
+ )
19
+ BUNDLE_PUSH_ACTIONS = ("tests",)
20
+ BUNDLE_RESERVED_TABLES = ("integrations",)
21
+ LINK_TRANSFORMS = (
22
+ "lower",
23
+ "upper",
24
+ "trim",
25
+ "collapse_ws",
26
+ "nfkc",
27
+ "digits",
28
+ "email_local_part",
29
+ "email_domain",
30
+ "sha1",
31
+ "sha256",
32
+ )
33
+ STRIP_PREFIX = "strip_prefix:"
34
+
35
+ _TABLES = ("bundle", "members", "actions", "identities", "references", *BUNDLE_RESERVED_TABLES)
36
+ _BUNDLE_KEYS = ("name", "test_state")
37
+ _MEMBER_ALIAS = re.compile(r"^[a-z][a-z0-9_]{0,31}$")
38
+ _RESERVED_ALIASES = ("constructor", "prototype")
39
+ _MEMBER_PIN = re.compile(r"^(?:([^/@]+)/)?([^/@]+)@([^/@]+)$")
40
+ _MEMBER_REF = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$")
41
+ _WORLD_SLUG = re.compile(r"^(?!(?:migrate|runtime|templates)$)[a-z0-9][a-z0-9\-_]*$")
42
+ _MAX_SLUG_LENGTH = 128
43
+ _MAX_TEST_STATE_LENGTH = 120
44
+ _ENTITY = re.compile(r"[A-Za-z][A-Za-z0-9_]{0,63}")
45
+ _FIELD_NAME = re.compile(r"[A-Za-z_][A-Za-z0-9_-]*")
46
+ _FIELD_POINTER = re.compile(r"(?:/(?:[^/~]|~[01])+)+")
47
+ _IDENTITY_KEYS = ("created_in", "in", "key", "name")
48
+ _IDENTITY_MEMBER_KEYS = ("carry", "entity", "field", "transform")
49
+ _REFERENCE_KEYS = ("from", "to")
50
+ _REFERENCE_END_KEYS = ("entity", "field", "world")
51
+ _TRANSFORM_RULE = f"{', '.join(LINK_TRANSFORMS)} or strip_prefix:<prefix>"
52
+
53
+
54
+ def _utf16_length(value: str) -> int:
55
+ return len(value.encode("utf-16-le", "surrogatepass")) // 2
56
+
57
+
58
+ def _world_slug(value: str) -> bool:
59
+ return len(value) <= _MAX_SLUG_LENGTH and _WORLD_SLUG.fullmatch(value) is not None
60
+
61
+
62
+ def is_link_transform(name: str) -> bool:
63
+ return name in LINK_TRANSFORMS or (name.startswith(STRIP_PREFIX) and len(name) > len(STRIP_PREFIX))
64
+
65
+
66
+ def _transform_names(value: Any) -> list[Any] | None:
67
+ if value is None:
68
+ return []
69
+ if isinstance(value, str):
70
+ return [value]
71
+ return value if isinstance(value, list) else None
72
+
73
+
74
+ def _is_field(value: Any) -> bool:
75
+ return isinstance(value, str) and bool(_FIELD_NAME.fullmatch(value) or _FIELD_POINTER.fullmatch(value))
76
+
77
+
78
+ @dataclass(frozen=True)
79
+ class BundleMember:
80
+ alias: str
81
+ slug: str
82
+ ref: str
83
+
84
+ def to_json(self) -> dict[str, str]:
85
+ return {"alias": self.alias, "slug": self.slug, "ref": self.ref}
86
+
87
+
88
+ @dataclass(frozen=True)
89
+ class BundleIdentityMember:
90
+ alias: str
91
+ entity: str
92
+ field: str
93
+ transform: tuple[str, ...] = ()
94
+ carry: tuple[tuple[str, str], ...] = ()
95
+
96
+ def to_json(self) -> dict[str, Any]:
97
+ return {
98
+ "alias": self.alias,
99
+ "entity": self.entity,
100
+ "field": self.field,
101
+ "transform": list(self.transform),
102
+ "carry": dict(self.carry),
103
+ }
104
+
105
+
106
+ @dataclass(frozen=True)
107
+ class BundleIdentity:
108
+ name: str
109
+ key: str
110
+ created_in: str | None
111
+ members: tuple[BundleIdentityMember, ...]
112
+
113
+ def to_json(self) -> dict[str, Any]:
114
+ return {
115
+ "name": self.name,
116
+ "key": self.key,
117
+ "createdIn": self.created_in,
118
+ "in": [member.to_json() for member in self.members],
119
+ }
120
+
121
+
122
+ @dataclass(frozen=True)
123
+ class BundleReferenceEnd:
124
+ world: str
125
+ entity: str
126
+ field: str
127
+
128
+ def to_json(self) -> dict[str, str]:
129
+ return {"world": self.world, "entity": self.entity, "field": self.field}
130
+
131
+
132
+ @dataclass(frozen=True)
133
+ class BundleReference:
134
+ source: BundleReferenceEnd
135
+ target: BundleReferenceEnd
136
+
137
+ def to_json(self) -> dict[str, Any]:
138
+ return {"from": self.source.to_json(), "to": self.target.to_json()}
139
+
140
+
141
+ @dataclass(frozen=True)
142
+ class BundleManifest:
143
+ name: str
144
+ test_state: str | None
145
+ members: tuple[BundleMember, ...]
146
+ on_push: tuple[str, ...] = ()
147
+ reserved: tuple[str, ...] = field(default_factory=tuple)
148
+ identities: tuple[BundleIdentity, ...] = ()
149
+ references: tuple[BundleReference, ...] = ()
150
+
151
+ @classmethod
152
+ def read(cls, text: str) -> BundleManifest | list[str]:
153
+ """The manifest, or the list of issues that refuse it."""
154
+ try:
155
+ root = tomllib.loads(text.replace("\r\n", "\n"))
156
+ except tomllib.TOMLDecodeError as error:
157
+ return [f"gateway-bundle.toml is not valid TOML: {error}"]
158
+ return _Reader(root).read()
159
+
160
+ @staticmethod
161
+ def compose(
162
+ name: str,
163
+ members: list[BundleMember],
164
+ test_state: str | None = None,
165
+ on_push: tuple[str, ...] = (),
166
+ ) -> str:
167
+ def quoted(value: object) -> str:
168
+ return json.dumps(value, ensure_ascii=False, separators=(",", ":"))
169
+
170
+ lines = ["[bundle]", f"name = {quoted(name)}"]
171
+ if test_state:
172
+ lines.append(f"test_state = {quoted(test_state)}")
173
+ if on_push:
174
+ lines += ["", "[actions]", f"on_push = {quoted(list(on_push))}"]
175
+ for member in sorted(members, key=lambda m: m.alias):
176
+ lines += ["", f"[members.{member.alias}]", f"pin = {quoted(f'{member.slug}@{member.ref}')}"]
177
+ return "\n".join(lines) + "\n"
178
+
179
+ def to_json(self) -> dict[str, Any]:
180
+ return {
181
+ "name": self.name,
182
+ "testState": self.test_state,
183
+ "members": [member.to_json() for member in sorted(self.members, key=lambda m: m.alias)],
184
+ "onPush": list(self.on_push),
185
+ "identities": [identity.to_json() for identity in self.identities],
186
+ "references": [reference.to_json() for reference in self.references],
187
+ "reserved": list(self.reserved),
188
+ }
189
+
190
+
191
+ class _Reader:
192
+ def __init__(self, root: dict[str, Any]) -> None:
193
+ self.root = root
194
+ self.issues: list[str] = []
195
+ self.members: list[BundleMember] = []
196
+
197
+ def read(self) -> BundleManifest | list[str]:
198
+ self._unknown_tables()
199
+ bundle = self._bundle()
200
+ self._member_tables()
201
+ on_push = self._actions()
202
+ members = self.root.get("members")
203
+ relationships = _RelationshipReader(self.issues, set(members) if isinstance(members, dict) else set())
204
+ relationships.read_identities(self.root.get("identities"))
205
+ relationships.read_references(self.root.get("references"))
206
+ if self.issues or bundle is None:
207
+ return self.issues
208
+ return BundleManifest(
209
+ name=bundle[0],
210
+ test_state=bundle[1],
211
+ members=tuple(self.members),
212
+ on_push=tuple(on_push),
213
+ reserved=tuple(sorted(t for t in BUNDLE_RESERVED_TABLES if t in self.root)),
214
+ identities=tuple(relationships.identities),
215
+ references=tuple(relationships.references),
216
+ )
217
+
218
+ def _unknown_tables(self) -> None:
219
+ for key in sorted(self.root):
220
+ if key not in _TABLES:
221
+ self.issues.append(
222
+ f"gateway-bundle.toml has no table `{key}`; it takes bundle, members, actions, identities, "
223
+ "references and integrations."
224
+ )
225
+
226
+ def _bundle(self) -> tuple[str, str | None] | None:
227
+ bundle = self.root.get("bundle")
228
+ if not isinstance(bundle, dict):
229
+ self.issues.append("gateway-bundle.toml needs a [bundle] table with the bundle's name.")
230
+ return None
231
+ for key in sorted(bundle):
232
+ if key not in _BUNDLE_KEYS:
233
+ self.issues.append(f"[bundle] has no key `{key}`; it takes name and test_state.")
234
+ name = bundle.get("name")
235
+ named = isinstance(name, str) and _world_slug(name)
236
+ if not named:
237
+ self.issues.append("[bundle] name must be a world slug: lowercase letters, digits, '-' or '_'.")
238
+ test_state = bundle.get("test_state")
239
+ stated = test_state is None or (
240
+ isinstance(test_state, str) and 1 <= _utf16_length(test_state) <= _MAX_TEST_STATE_LENGTH
241
+ )
242
+ if not stated:
243
+ self.issues.append(
244
+ "[bundle] test_state names a world state of every member: a name of 1 to "
245
+ f"{_MAX_TEST_STATE_LENGTH} characters."
246
+ )
247
+ if not named or not stated:
248
+ return None
249
+ return str(name), test_state
250
+
251
+ def _member_tables(self) -> None:
252
+ members = self.root.get("members")
253
+ if not isinstance(members, dict):
254
+ self.issues.append("gateway-bundle.toml needs [members.<alias>] tables, one per member world.")
255
+ return
256
+ count = len(members)
257
+ if count < MIN_BUNDLE_MEMBERS:
258
+ self.issues.append(f"gateway-bundle.toml names {count} members; a bundle names at least one member.")
259
+ if count > MAX_BUNDLE_MEMBERS:
260
+ self.issues.append(
261
+ f"gateway-bundle.toml names {count} members; a bundle holds at most {MAX_BUNDLE_MEMBERS}."
262
+ )
263
+ pinned_by: dict[str, str] = {}
264
+ for alias in sorted(members):
265
+ self._member(alias, members[alias], pinned_by)
266
+
267
+ def _member(self, alias: str, table: Any, pinned_by: dict[str, str]) -> None:
268
+ if alias in _RESERVED_ALIASES:
269
+ self.issues.append(f"member alias `{alias}` is reserved; name the member another way.")
270
+ return
271
+ if not _MEMBER_ALIAS.fullmatch(alias):
272
+ self.issues.append(
273
+ f"member alias `{alias}` must be lowercase letters, digits or '_', start with a letter and be at "
274
+ "most 32 characters."
275
+ )
276
+ if not isinstance(table, dict):
277
+ self.issues.append(f"[members.{alias}] must be a table with a pin.")
278
+ return
279
+ for key in sorted(table):
280
+ if key != "pin":
281
+ self.issues.append(f"[members.{alias}] has no key `{key}`; it takes pin.")
282
+ member = self._pin(alias, table.get("pin"))
283
+ if member is None:
284
+ return
285
+ first = pinned_by.get(member.slug)
286
+ if first is not None:
287
+ self.issues.append(
288
+ f"[members.{alias}] pins {member.slug}, which [members.{first}] already pins; a world is a member once."
289
+ )
290
+ return
291
+ pinned_by[member.slug] = alias
292
+ self.members.append(member)
293
+
294
+ def _pin(self, alias: str, pin: Any) -> BundleMember | None:
295
+ parsed = _MEMBER_PIN.fullmatch(pin.strip(" \t")) if isinstance(pin, str) else None
296
+ if parsed is None or not _MEMBER_REF.fullmatch(parsed.group(3)):
297
+ self.issues.append(f"[members.{alias}] pin must be `<slug>@<ref>`.")
298
+ return None
299
+ project, slug, ref = parsed.groups()
300
+ if project is not None:
301
+ self.issues.append(
302
+ f"[members.{alias}] pin names a project; a member is a world of the bundle's own project, so drop "
303
+ f"the `{project}/` prefix."
304
+ )
305
+ return None
306
+ if not _world_slug(slug):
307
+ self.issues.append(
308
+ f"[members.{alias}] pin's slug `{slug}` must be a world slug: lowercase letters, digits, '-' or '_'."
309
+ )
310
+ return None
311
+ return BundleMember(alias, slug, ref)
312
+
313
+ def _actions(self) -> list[str]:
314
+ actions = self.root.get("actions")
315
+ if actions is None:
316
+ return []
317
+ if not isinstance(actions, dict):
318
+ self.issues.append("[actions] must be a table.")
319
+ return []
320
+ for key in sorted(actions):
321
+ if key != "on_push":
322
+ self.issues.append(f"[actions] has no key `{key}`; it takes on_push.")
323
+ on_push = actions.get("on_push", [])
324
+ known = isinstance(on_push, list) and all(
325
+ isinstance(action, str) and action in BUNDLE_PUSH_ACTIONS for action in on_push
326
+ )
327
+ if not known:
328
+ self.issues.append(f"[actions] on_push lists what runs on push: {', '.join(BUNDLE_PUSH_ACTIONS)}.")
329
+ return []
330
+ return list(on_push)
331
+
332
+
333
+ class _RelationshipReader:
334
+ def __init__(self, issues: list[str], members: set[str]) -> None:
335
+ self.issues = issues
336
+ self.members = members
337
+ self.identities: list[BundleIdentity] = []
338
+ self.references: list[BundleReference] = []
339
+ self._named: set[str] = set()
340
+ self._declared: dict[tuple[str, ...], int] = {}
341
+
342
+ def read_identities(self, value: Any) -> None:
343
+ if value is None:
344
+ return
345
+ if not isinstance(value, list):
346
+ self.issues.append("`identities` must be an array of tables, one [[identities]] per identity.")
347
+ return
348
+ for position, entry in enumerate(value, start=1):
349
+ self._identity(entry, position)
350
+
351
+ def read_references(self, value: Any) -> None:
352
+ if value is None:
353
+ return
354
+ if not isinstance(value, list):
355
+ self.issues.append("`references` must be an array of tables, one [[references]] per reference.")
356
+ return
357
+ for position, entry in enumerate(value, start=1):
358
+ self._reference(entry, position)
359
+
360
+ def _identity(self, entry: Any, position: int) -> None:
361
+ if not isinstance(entry, dict):
362
+ self.issues.append(f"identity #{position} must be a table with a name, a key and in.<alias> tables.")
363
+ return
364
+ before = len(self.issues)
365
+ name = entry.get("name")
366
+ named = isinstance(name, str) and _MEMBER_ALIAS.fullmatch(name) is not None
367
+ at = f"identity `{name}`" if named else f"identity #{position}"
368
+ self._unknown_keys(entry, _IDENTITY_KEYS, at, "name, key, created_in and in")
369
+ if not named:
370
+ self.issues.append(
371
+ f"{at} name must be lowercase letters, digits or '_', start with a letter and be at most 32 characters."
372
+ )
373
+ if named and name in self._named:
374
+ self.issues.append(f"{at} is declared twice; an identity's name is unique in the bundle.")
375
+ if named:
376
+ self._named.add(str(name))
377
+ key = entry.get("key")
378
+ if not isinstance(key, str) or not _FIELD_NAME.fullmatch(key):
379
+ self.issues.append(
380
+ f"{at} key must be a field name: letters, digits, '_' or '-', starting with a letter or '_'."
381
+ )
382
+ spans = self._spans(entry.get("in"), at)
383
+ self._carried_once(spans, at)
384
+ created_in = self._created_in(entry.get("created_in"), spans, at)
385
+ if len(self.issues) > before:
386
+ return
387
+ self.identities.append(BundleIdentity(str(name), str(key), created_in, tuple(spans)))
388
+
389
+ def _spans(self, value: Any, at: str) -> list[BundleIdentityMember]:
390
+ if not isinstance(value, dict) or not value:
391
+ self.issues.append(
392
+ f'{at} needs in.<alias> = {{ entity = "...", field = "..." }}, one per member world it spans.'
393
+ )
394
+ return []
395
+ return [self._span(alias, value[alias], f"{at} in.{alias}") for alias in sorted(value)]
396
+
397
+ def _span(self, alias: str, value: Any, where: str) -> BundleIdentityMember:
398
+ self._member(alias, where)
399
+ if not isinstance(value, dict):
400
+ self.issues.append(f'{where} must be a table: {{ entity = "...", field = "..." }}.')
401
+ return BundleIdentityMember(alias, "", "")
402
+ self._unknown_keys(value, _IDENTITY_MEMBER_KEYS, where, "entity, field, transform and carry")
403
+ entity, field_ = self._endpoint(value, where)
404
+ transform = tuple(self._transform(value.get("transform"), where))
405
+ return BundleIdentityMember(alias, entity, field_, transform, self._carry(value.get("carry"), field_, where))
406
+
407
+ def _carry(self, value: Any, key_field: Any, where: str) -> tuple[tuple[str, str], ...]:
408
+ if value is None:
409
+ return ()
410
+ if not isinstance(value, dict):
411
+ self.issues.append(
412
+ f'{where}.carry must be a table: {{ <name> = "<field>" }}, the fields this span carries to its '
413
+ "counterparts."
414
+ )
415
+ return ()
416
+ carried: list[tuple[str, str]] = []
417
+ held: set[Any] = set()
418
+ for name in sorted(value):
419
+ target = value[name]
420
+ if not _FIELD_NAME.fullmatch(name):
421
+ self.issues.append(
422
+ f"{where}.carry name `{name}` must be a field name: letters, digits, '_' or '-', starting with a "
423
+ "letter or '_'."
424
+ )
425
+ if not _is_field(target):
426
+ self.issues.append(
427
+ f"{where}.carry.{name} must be a field name or a JSON pointer such as /profile/name."
428
+ )
429
+ continue
430
+ if target == key_field:
431
+ self.issues.append(f"{where}.carry.{name} names the span's own field; the key is carried already.")
432
+ if target in held:
433
+ self.issues.append(f"{where}.carry names `{target}` twice; a field carries one value.")
434
+ held.add(target)
435
+ carried.append((name, target))
436
+ return tuple(carried)
437
+
438
+ def _carried_once(self, spans: list[BundleIdentityMember], at: str) -> None:
439
+ aliases: dict[str, list[str]] = {}
440
+ for span in spans:
441
+ for name, _ in span.carry:
442
+ aliases.setdefault(name, []).append(span.alias)
443
+ for name in sorted(aliases):
444
+ if len(aliases[name]) == 1:
445
+ self.issues.append(
446
+ f"{at} carries `{name}` only in.{aliases[name][0]}; name it in another span too, or drop it."
447
+ )
448
+
449
+ def _created_in(self, value: Any, spans: list[BundleIdentityMember], at: str) -> str | None:
450
+ if value is None:
451
+ return None
452
+ if isinstance(value, str) and any(span.alias == value for span in spans):
453
+ return value
454
+ self.issues.append(f"{at} created_in must name one of the identity's members (in.<alias>).")
455
+ return None
456
+
457
+ def _reference(self, entry: Any, position: int) -> None:
458
+ at = f"reference #{position}"
459
+ if not isinstance(entry, dict):
460
+ self.issues.append(f"{at} must be a table with from and to.")
461
+ return
462
+ before = len(self.issues)
463
+ self._unknown_keys(entry, _REFERENCE_KEYS, at, "from and to")
464
+ source = self._end(entry.get("from"), f"{at} from")
465
+ target = self._end(entry.get("to"), f"{at} to")
466
+ if len(self.issues) > before:
467
+ return
468
+ signature = (source.world, source.entity, source.field, target.world, target.entity, target.field)
469
+ first = self._declared.get(signature)
470
+ if first is not None:
471
+ self.issues.append(f"{at} repeats reference #{first}; a reference is declared once.")
472
+ return
473
+ self._declared[signature] = position
474
+ self.references.append(BundleReference(source, target))
475
+
476
+ def _end(self, value: Any, where: str) -> BundleReferenceEnd:
477
+ if not isinstance(value, dict):
478
+ self.issues.append(f'{where} must be a table: {{ world = "<alias>", entity = "...", field = "..." }}.')
479
+ return BundleReferenceEnd("", "", "")
480
+ self._unknown_keys(value, _REFERENCE_END_KEYS, where, "world, entity and field")
481
+ self._member(value.get("world"), f"{where}.world")
482
+ entity, field_ = self._endpoint(value, where)
483
+ return BundleReferenceEnd(str(value.get("world")), entity, field_)
484
+
485
+ def _member(self, alias: Any, where: str) -> None:
486
+ if isinstance(alias, str) and alias in self.members:
487
+ return
488
+ self.issues.append(f"{where} must name a member of this bundle.")
489
+
490
+ def _endpoint(self, table: dict[str, Any], where: str) -> tuple[Any, Any]:
491
+ entity = table.get("entity")
492
+ field_ = table.get("field")
493
+ if not isinstance(entity, str) or not _ENTITY.fullmatch(entity):
494
+ self.issues.append(
495
+ f"{where}.entity must be an entity name: letters, digits or '_', a letter first, at most 64 characters."
496
+ )
497
+ if not _is_field(field_):
498
+ self.issues.append(f"{where}.field must be a field name or a JSON pointer such as /owner/email.")
499
+ return entity, field_
500
+
501
+ def _transform(self, value: Any, where: str) -> list[str]:
502
+ names = _transform_names(value)
503
+ if names is None or not all(isinstance(name, str) for name in names):
504
+ self.issues.append(f"{where}.transform must be a transform name or a list of them.")
505
+ return []
506
+ for name in names:
507
+ if not is_link_transform(name):
508
+ self.issues.append(f"{where}.transform `{name}` is not one of {_TRANSFORM_RULE}.")
509
+ return names
510
+
511
+ def _unknown_keys(self, table: dict[str, Any], allowed: tuple[str, ...], at: str, takes: str) -> None:
512
+ for key in sorted(table):
513
+ if key not in allowed:
514
+ self.issues.append(f"{at} has no key `{key}`; it takes {takes}.")
515
+
516
+
517
+ __all__ = [
518
+ "BUNDLE_MANIFEST",
519
+ "BUNDLE_PUSH_ACTIONS",
520
+ "BUNDLE_RESERVED_TABLES",
521
+ "LINK_TRANSFORMS",
522
+ "MAX_BUNDLE_MEMBERS",
523
+ "MIN_BUNDLE_MEMBERS",
524
+ "BundleIdentity",
525
+ "BundleIdentityMember",
526
+ "BundleManifest",
527
+ "BundleMember",
528
+ "BundleReference",
529
+ "BundleReferenceEnd",
530
+ "is_link_transform",
531
+ ]