@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
@@ -146,14 +146,25 @@ class ProvenTemplate:
146
146
  os.replace(record, self.proof_path)
147
147
 
148
148
 
149
+ def restore_vouches_pages(restore: object) -> bool:
150
+ """No restore, a worker's own recovery, or an export whose host named its page recorder: every earlier
151
+ life of the session recorded its pages."""
152
+ if not isinstance(restore, dict):
153
+ return True
154
+ return restore.get("recovered") is not None or isinstance(restore.get("recorder"), str)
155
+
156
+
149
157
  class ExportFile(NamedTuple):
150
- """A session export on this host's disk and the sha256 the platform recorded for it."""
158
+ """A session export on this host's disk, the sha256 the platform recorded for it, and the page
159
+ recorder the host that took it named."""
151
160
 
152
161
  path: Path
153
162
  sha256: str
163
+ recorder: object = None
154
164
 
155
165
  def for_worker(self) -> dict[str, str]:
156
- return {"path": str(self.path), "sha256": self.sha256}
166
+ named = {"recorder": self.recorder} if isinstance(self.recorder, str) else {}
167
+ return {"path": str(self.path), "sha256": self.sha256, **named}
157
168
 
158
169
  def checkpoint(self, engine: type[WorldDatabase], runtime: type[WorldRuntime]) -> SessionExport:
159
170
  return SessionExport.verified(self, engine)
@@ -0,0 +1,493 @@
1
+ """The shape catalog ``describe`` carries. The TypeScript reader is ``WorldShapeCatalog``
2
+ (``packages/shared/src/world/shapeCatalog``), pinned to this builder by
3
+ ``conformance/world-shape-catalogs.json``."""
4
+
5
+ from __future__ import annotations
6
+
7
+ from abc import ABC, abstractmethod
8
+ from dataclasses import dataclass, field, replace
9
+ from pathlib import Path
10
+ from typing import TYPE_CHECKING, Any
11
+
12
+ from .cast import FieldType, LocalDefinitions, allowed_values, schema_fields, schema_types
13
+ from .shape_declarations import AnswerDeclaration, dotted_pointer, json_pointer
14
+ from .tree_import import PUBLICATION_FILE_BYTES
15
+ from .validation import ContractError, InlineBudgetExceeded, Resolver, fail, local_references
16
+
17
+ if TYPE_CHECKING:
18
+ from .api import ApiSettings
19
+ from .connector import Operation, Spec
20
+
21
+ CATALOG_VERSION = 1
22
+ DESCRIBE_ENTITY = "describe_entity"
23
+ MAX_DEPTH = 12
24
+ ANNOTATIONS = frozenset(
25
+ {"description", "title", "examples", "example", "$comment", "default", "deprecated", "readOnly", "writeOnly"}
26
+ )
27
+ SCHEMA_MAPS = ("properties", "patternProperties", "$defs", "definitions", "dependentSchemas")
28
+ SCHEMA_ONE = ("items", "additionalProperties", "not", "contains", "propertyNames", "if", "then", "else")
29
+ SCHEMA_MANY = ("allOf", "anyOf", "oneOf", "prefixItems", "items")
30
+ LEGEND = {
31
+ "hash": 'sha256 of "<slug>:<value>", stored as sha256:<hex>; a lookup by plaintext computes the same form',
32
+ "preserve": "a digest that keeps the value's shape: same length, digits stay digits, letters stay letters",
33
+ "round": "the number rounded to n decimals (round:n)",
34
+ "drop": "never stored",
35
+ }
36
+ WRITES = (
37
+ "Capture stores these forms, and an import, seed or upload stores them only when it asks for "
38
+ "--redact apply; every other write, a factory write included, is stored as written."
39
+ )
40
+
41
+
42
+ def stripped(schema: Any) -> Any:
43
+ if not isinstance(schema, dict):
44
+ return schema
45
+ out: dict = {}
46
+ for key, value in schema.items():
47
+ if key in ANNOTATIONS or key.startswith("x-"):
48
+ continue
49
+ out[key] = _stripped_member(key, value)
50
+ return out
51
+
52
+
53
+ def _stripped_member(key: str, value: Any) -> Any:
54
+ if key in SCHEMA_MAPS and isinstance(value, dict):
55
+ return {name: stripped(child) for name, child in value.items()}
56
+ if key in SCHEMA_MANY and isinstance(value, list):
57
+ return [stripped(child) for child in value]
58
+ if key in SCHEMA_ONE and isinstance(value, dict):
59
+ return stripped(value)
60
+ return value
61
+
62
+
63
+ def local_refs(schema: Any) -> set[str]:
64
+ return {name for name in local_references(schema) if name} if isinstance(schema, dict) else set()
65
+
66
+
67
+ @dataclass(frozen=True)
68
+ class CatalogWorld:
69
+ document: dict
70
+ spec: "Spec | None" = None
71
+ settings: "ApiSettings | None" = None
72
+ answers: dict[str, AnswerDeclaration] = field(default_factory=dict)
73
+ redacted: bool = False
74
+ roots: dict[str, dict] = field(default_factory=dict)
75
+ defs: dict[str, dict] = field(default_factory=dict)
76
+ orders: dict[str, list[str]] = field(default_factory=dict)
77
+
78
+ @classmethod
79
+ def of_bundle(cls, root: Path, **connection: Any) -> "CatalogWorld":
80
+ """Through the compiler's shared resolver, so a type in a sibling file under ``schema/``
81
+ reads like one in ``world.json`` and every reference left is a local ``#/$defs/<key>``.
82
+ A world the shared form refuses, such as two definitions that share a name, is read
83
+ inlined, the form the compiler builds it in first."""
84
+ try:
85
+ return cls._read(Resolver(root, shared=True), connection)
86
+ except ContractError as refused:
87
+ return cls._inlined(root, connection, refused)
88
+
89
+ @classmethod
90
+ def _inlined(cls, root: Path, connection: dict, refused: ContractError) -> "CatalogWorld":
91
+ try:
92
+ return cls._read(Resolver(root, budget=PUBLICATION_FILE_BYTES), connection)
93
+ except InlineBudgetExceeded:
94
+ raise refused from None
95
+
96
+ @classmethod
97
+ def _read(cls, resolver: Resolver, connection: dict) -> "CatalogWorld":
98
+ document = resolver.load("world.json")
99
+ gateway = document.get("x-gateway") if isinstance(document.get("x-gateway"), dict) else {}
100
+ entities = gateway.get("entities") if isinstance(gateway.get("entities"), dict) else {}
101
+ roots = {
102
+ name: resolver.resolve(_schema_of(entity), "world.json", f"world.json#/x-gateway/entities/{name}/schema")
103
+ for name, entity in sorted(entities.items())
104
+ }
105
+ orders = {name: _authored_properties(resolver, _schema_of(entity)) for name, entity in entities.items()}
106
+ return cls(document, roots=roots, defs=dict(resolver.definitions), orders=orders, **connection)
107
+
108
+ @property
109
+ def entities(self) -> dict[str, dict]:
110
+ gateway = self.document.get("x-gateway")
111
+ entities = gateway.get("entities") if isinstance(gateway, dict) else None
112
+ return entities if isinstance(entities, dict) else {}
113
+
114
+ def resolved(self, schema: Any, seen: frozenset[str] = frozenset()) -> tuple[dict, frozenset[str]]:
115
+ return LocalDefinitions(self.defs)(schema, seen)
116
+
117
+ def root(self, entity: str) -> dict:
118
+ return self.roots.get(entity) or {}
119
+
120
+ def fields(self, entity: str) -> dict[str, Any]:
121
+ properties = self.root(entity).get("properties")
122
+ return properties if isinstance(properties, dict) else {}
123
+
124
+ def declared(self, entity: str, member: str) -> list[dict]:
125
+ listed = (self.entities.get(entity) or {}).get(member)
126
+ return listed if isinstance(listed, list) else []
127
+
128
+ def kinds(self, schema: Any) -> set[str]:
129
+ return set(schema_types(schema, self.resolved))
130
+
131
+ def entity_fields(self) -> dict[str, list[FieldType]]:
132
+ """In the order the entity's authored schema lists them; the resolver sorts ``properties``."""
133
+ return {
134
+ name: self._authored_order(name, schema_fields(self.root(name), self.resolved))
135
+ for name in sorted(self.entities)
136
+ }
137
+
138
+ def _authored_order(self, entity: str, fields: list[FieldType]) -> list[FieldType]:
139
+ order = {name: index for index, name in enumerate(self.orders.get(entity) or [])}
140
+ return sorted(fields, key=lambda item: order.get(item.name, len(order)))
141
+
142
+
143
+ def _schema_of(entity: Any) -> Any:
144
+ return entity.get("schema") if isinstance(entity, dict) else None
145
+
146
+
147
+ def _authored_properties(resolver: Resolver, schema: Any) -> list[str]:
148
+ name, seen = "world.json", set()
149
+ while isinstance(schema, dict) and isinstance(schema.get("$ref"), str) and "properties" not in schema:
150
+ schema, name, key = resolver.reference(schema["$ref"], name, f"{name}#")
151
+ if key in seen:
152
+ break
153
+ seen.add(key)
154
+ properties = schema.get("properties") if isinstance(schema, dict) else None
155
+ return list(properties) if isinstance(properties, dict) else []
156
+
157
+
158
+ class CatalogKind(ABC):
159
+ key: str
160
+
161
+ @abstractmethod
162
+ def read(self, world: CatalogWorld) -> Any: ...
163
+
164
+ def narrowed(self, value: Any, entity: str) -> Any:
165
+ return [entry for entry in value if entry.get("entity") == entity]
166
+
167
+
168
+ class Enumerations(CatalogKind):
169
+ key = "enumerations"
170
+
171
+ def read(self, world: CatalogWorld) -> list[dict]:
172
+ found: dict[tuple[str, str], dict] = {}
173
+ for entity in sorted(world.entities):
174
+ for name, schema in world.fields(entity).items():
175
+ self._walk(world, entity, schema, [name], frozenset(), found)
176
+ return list(found.values())
177
+
178
+ def _walk(
179
+ self, world: CatalogWorld, entity: str, schema: Any, at: list[str], seen, found: dict, quiet: bool = False
180
+ ) -> None:
181
+ """``quiet``: a branch of a union that also admits other values lists nothing at its own pointer."""
182
+ node, seen = world.resolved(schema, seen)
183
+ if len(at) > MAX_DEPTH:
184
+ return
185
+ allowed = allowed_values(node, world.resolved, seen)
186
+ if allowed is not None and not quiet:
187
+ self._record(found, entity, json_pointer(at), *allowed)
188
+ if allowed is not None:
189
+ return
190
+ for name, child in (node.get("properties") or {}).items():
191
+ self._walk(world, entity, child, [*at, name], seen, found)
192
+ for key in ("items", "additionalProperties"):
193
+ if isinstance(node.get(key), dict):
194
+ self._walk(world, entity, node[key], [*at, "*"], seen, found)
195
+ for key, branch_quiet in (("anyOf", True), ("oneOf", True), ("allOf", quiet)):
196
+ for branch in node.get(key) or []:
197
+ self._walk(world, entity, branch, at, seen, found, branch_quiet)
198
+
199
+ @staticmethod
200
+ def _record(found: dict, entity: str, at: str, values: list, labels: list[dict]) -> None:
201
+ entry = found.setdefault((entity, at), {"entity": entity, "pointer": at, "values": []})
202
+ entry["values"] += [value for value in values if value not in entry["values"]]
203
+ if labels:
204
+ entry.setdefault("labels", [])
205
+ entry["labels"] += [label for label in labels if label not in entry["labels"]]
206
+
207
+
208
+ class Columns(CatalogKind):
209
+ key = "columns"
210
+
211
+ def read(self, world: CatalogWorld) -> list[dict]:
212
+ return [
213
+ {"entity": entity, "field": name, "schema": stripped(schema)}
214
+ for entity in sorted(world.entities)
215
+ for name, schema in world.fields(entity).items()
216
+ if world.kinds(schema) & {"object", "array"}
217
+ ]
218
+
219
+
220
+ class CustomFields(CatalogKind):
221
+ key = "customFields"
222
+
223
+ def read(self, world: CatalogWorld) -> list[dict]:
224
+ return [
225
+ self._entry(world, entity, declared)
226
+ for entity in sorted(world.entities)
227
+ for declared in world.declared(entity, "custom_fields")
228
+ ]
229
+
230
+ @staticmethod
231
+ def _entry(world: CatalogWorld, entity: str, declared: dict) -> dict:
232
+ where = dict(declared.get("where") or {})
233
+ definitions = declared["definitions"]
234
+ required = world.root(definitions).get("required") or []
235
+ entry = {
236
+ "entity": entity,
237
+ "field": declared["field"],
238
+ "definitions": definitions,
239
+ "key": declared["key"],
240
+ "where": where,
241
+ }
242
+ if "pairs" in declared:
243
+ entry["pairs"] = dict(declared["pairs"])
244
+ entry["add"] = {
245
+ "entity": definitions,
246
+ "set": where,
247
+ "key": declared["key"],
248
+ "required": [name for name in required if name != declared["key"] and name not in where],
249
+ }
250
+ return entry
251
+
252
+
253
+ class Ids(CatalogKind):
254
+ key = "ids"
255
+
256
+ def read(self, world: CatalogWorld) -> list[dict]:
257
+ return [
258
+ self._entry(entity, declared)
259
+ for entity in sorted(world.entities)
260
+ for declared in world.declared(entity, "ids")
261
+ ]
262
+
263
+ @staticmethod
264
+ def _entry(entity: str, declared: dict) -> dict:
265
+ entry: dict = {"entity": entity, "pointer": declared["pointer"]}
266
+ if "values" in declared:
267
+ entry["values"] = [{"id": value["id"], "label": value["label"]} for value in declared["values"]]
268
+ return entry
269
+ entry["target"] = {
270
+ "entity": declared["entity"],
271
+ "key": declared["key"],
272
+ "where": dict(declared.get("where") or {}),
273
+ }
274
+ return entry
275
+
276
+
277
+ class Sequences(CatalogKind):
278
+ key = "sequences"
279
+
280
+ def read(self, world: CatalogWorld) -> list[dict]:
281
+ found: dict[tuple[str, str], dict] = {}
282
+ for entity, field_name, operation in self._generated(world):
283
+ entry = found.setdefault(
284
+ (entity, field_name),
285
+ {
286
+ "entity": entity,
287
+ "field": field_name,
288
+ "scope": [],
289
+ "start": 1,
290
+ "source": "generate",
291
+ "operations": [],
292
+ },
293
+ )
294
+ entry["operations"].append(operation)
295
+ for entity in sorted(world.entities):
296
+ for declared in world.declared(entity, "sequences"):
297
+ entry = found.setdefault((entity, declared["field"]), {"entity": entity, "field": declared["field"]})
298
+ entry.update(
299
+ scope=list(declared.get("scope") or []),
300
+ start=declared.get("start", 1),
301
+ source="declared",
302
+ operations=entry.get("operations", []),
303
+ )
304
+ return [found[key] for key in sorted(found)]
305
+
306
+ @staticmethod
307
+ def _generated(world: CatalogWorld) -> list[tuple[str, str, str]]:
308
+ if world.spec is None or world.settings is None:
309
+ return []
310
+ return [
311
+ (operation.entity, field_name, operation.name)
312
+ for operation in world.spec.operations.values()
313
+ if operation.entity
314
+ for field_name, generator in world.settings.for_operation(operation.name).generate.items()
315
+ if generator == "int"
316
+ ]
317
+
318
+
319
+ class Redaction(CatalogKind):
320
+ key = "redaction"
321
+
322
+ def read(self, world: CatalogWorld) -> dict | None:
323
+ return {"legend": dict(LEGEND), "writes": WRITES} if world.redacted else None
324
+
325
+ def narrowed(self, value: Any, entity: str) -> Any:
326
+ return value
327
+
328
+
329
+ class Answers(CatalogKind):
330
+ key = "answers"
331
+
332
+ def read(self, world: CatalogWorld) -> list[dict]:
333
+ if world.spec is None:
334
+ return []
335
+ return [RouteAnswer.of(world, operation).document() for operation in world.spec.operations.values()]
336
+
337
+ def narrowed(self, value: Any, entity: str) -> Any:
338
+ return value
339
+
340
+
341
+ @dataclass(frozen=True)
342
+ class RouteAnswer:
343
+ operation: str
344
+ methods: list[str]
345
+ path: str
346
+ params: list[str]
347
+ entity: str | None
348
+ single: bool
349
+ records: str | None = None
350
+ id: str | None = None
351
+ fields: list[str] = field(default_factory=list)
352
+ count: str | None = None
353
+ total: str | None = None
354
+ cursor: str | None = None
355
+ cursor_param: str | None = None
356
+ declared: list[str] = field(default_factory=list)
357
+
358
+ @classmethod
359
+ def of(cls, world: CatalogWorld, operation: "Operation") -> "RouteAnswer":
360
+ base = cls(
361
+ operation=operation.name,
362
+ methods=list(operation.methods),
363
+ path=operation.path,
364
+ params=list(operation.params),
365
+ entity=operation.entity,
366
+ single=False,
367
+ id=cls._id(world, operation.entity),
368
+ )
369
+ served = base if world.settings is None else base._served(world.settings, operation)
370
+ return served._declared(world.answers.get(operation.name))
371
+
372
+ @staticmethod
373
+ def _id(world: CatalogWorld, entity: str | None) -> str | None:
374
+ key = (world.entities.get(entity or "") or {}).get("primary_key") or []
375
+ return key[0] if len(key) == 1 and not key[0].startswith("/") else None
376
+
377
+ def _served(self, settings: "ApiSettings", operation: "Operation") -> "RouteAnswer":
378
+ op = settings.for_operation(operation.name)
379
+ shape = settings.answer_shape(op, operation)
380
+ if op.action == "delete" or (operation.entity is None and op.action != "handler"):
381
+ return self
382
+ if shape.single:
383
+ return replace(self, single=True, records=dotted_pointer(shape.envelope or shape.results))
384
+ if op.action == "handler":
385
+ return replace(self, records=dotted_pointer(shape.results) if shape.results else None)
386
+ if not shape.envelope:
387
+ return replace(self, records="")
388
+ return self._enveloped(settings, op, shape.envelope)
389
+
390
+ def _enveloped(self, settings: "ApiSettings", op: Any, envelope: str) -> "RouteAnswer":
391
+ outer = envelope.split(".")[:-1]
392
+ paged = (op.paging or settings.paging.style) == "cursor"
393
+ return replace(
394
+ self,
395
+ records=dotted_pointer(envelope),
396
+ total=json_pointer([*outer, settings.hits_key]) if settings.hits_key else None,
397
+ cursor=json_pointer([*outer, settings.cursor_key]) if paged else None,
398
+ cursor_param=settings.paging.cursor_param if paged and not settings.page_links else None,
399
+ )
400
+
401
+ def _declared(self, declaration: AnswerDeclaration | None) -> "RouteAnswer":
402
+ if declaration is None:
403
+ return self
404
+ values = declaration.values
405
+ return replace(
406
+ self,
407
+ **{
408
+ key: values[key]
409
+ for key in ("records", "id", "count", "total", "cursor", "cursor_param")
410
+ if key in values
411
+ },
412
+ fields=list(values.get("fields", self.fields)),
413
+ declared=declaration.declared,
414
+ )
415
+
416
+ def document(self) -> dict:
417
+ return {
418
+ "operation": self.operation,
419
+ "methods": self.methods,
420
+ "path": self.path,
421
+ "params": self.params,
422
+ "entity": self.entity,
423
+ "single": self.single,
424
+ "records": self.records,
425
+ "id": self.id,
426
+ "fields": self.fields,
427
+ "count": self.count,
428
+ "total": self.total,
429
+ "cursor": self.cursor,
430
+ "cursorParam": self.cursor_param,
431
+ "declared": self.declared,
432
+ }
433
+
434
+
435
+ KINDS: tuple[CatalogKind, ...] = (
436
+ Enumerations(),
437
+ Columns(),
438
+ CustomFields(),
439
+ Ids(),
440
+ Sequences(),
441
+ Redaction(),
442
+ Answers(),
443
+ )
444
+
445
+
446
+ @dataclass(frozen=True)
447
+ class ShapeCatalog:
448
+ parts: dict[str, Any]
449
+ defs: dict
450
+
451
+ @classmethod
452
+ def of(cls, world: CatalogWorld) -> "ShapeCatalog":
453
+ return cls({kind.key: kind.read(world) for kind in KINDS}, world.defs)
454
+
455
+ @classmethod
456
+ def from_document(cls, document: dict) -> "ShapeCatalog":
457
+ return cls({kind.key: document[kind.key] for kind in KINDS}, dict(document.get("types") or {}))
458
+
459
+ def narrowed(self, entity: str) -> "ShapeCatalog":
460
+ return replace(self, parts={kind.key: kind.narrowed(self.parts[kind.key], entity) for kind in KINDS})
461
+
462
+ def types(self) -> dict:
463
+ reached: set[str] = set()
464
+ pending = sorted({name for column in self.parts["columns"] for name in local_refs(column["schema"])})
465
+ while pending:
466
+ name = pending.pop()
467
+ if name in reached or not isinstance(self.defs.get(name), dict):
468
+ continue
469
+ reached.add(name)
470
+ pending += sorted(local_refs(self.defs[name]) - reached)
471
+ return {name: stripped(self.defs[name]) for name in sorted(reached)}
472
+
473
+ def document(self) -> dict:
474
+ return {"version": CATALOG_VERSION, **self.parts, "types": self.types()}
475
+
476
+
477
+ def narrowed_description(description: dict, entity: Any) -> dict:
478
+ """Answers stay whole: a request is routed among every route, whichever entity it lands on."""
479
+ if entity is None:
480
+ return description
481
+ entities = description.get("entities") or []
482
+ names = [item.get("name") for item in entities]
483
+ if not isinstance(entity, str) or entity not in names:
484
+ fail(
485
+ DESCRIBE_ENTITY,
486
+ f"{entity!r} is not an entity of this world; its entities are {', '.join(map(str, names)) or 'none'}",
487
+ "/entity",
488
+ )
489
+ narrowed = {**description, "entities": [item for item in entities if item.get("name") == entity]}
490
+ catalog = description.get("catalog")
491
+ if isinstance(catalog, dict):
492
+ narrowed["catalog"] = ShapeCatalog.from_document(catalog).narrowed(entity).document()
493
+ return narrowed