@withgateway/sdk 0.9.1 → 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 (84) hide show
  1. package/dist/agents/index.d.mts +12 -4
  2. package/dist/agents/index.d.ts +12 -4
  3. package/dist/agents/index.js +30 -0
  4. package/dist/agents/index.js.map +1 -1
  5. package/dist/agents/index.mjs +30 -0
  6. package/dist/agents/index.mjs.map +1 -1
  7. package/dist/cli.js +2291 -945
  8. package/dist/cli.js.map +1 -1
  9. package/dist/cli.mjs +2290 -944
  10. package/dist/cli.mjs.map +1 -1
  11. package/dist/files/index.js.map +1 -1
  12. package/dist/files/index.mjs.map +1 -1
  13. package/dist/index.js +325 -184
  14. package/dist/index.js.map +1 -1
  15. package/dist/index.mjs +324 -183
  16. package/dist/index.mjs.map +1 -1
  17. package/dist/traces/index.js.map +1 -1
  18. package/dist/traces/index.mjs.map +1 -1
  19. package/dist/tracing/index.js +1 -1
  20. package/dist/tracing/index.js.map +1 -1
  21. package/dist/tracing/index.mjs +1 -1
  22. package/dist/tracing/index.mjs.map +1 -1
  23. package/dist/worlds/index.d.mts +3 -1
  24. package/dist/worlds/index.d.ts +3 -1
  25. package/dist/worlds/index.js +178 -67
  26. package/dist/worlds/index.js.map +1 -1
  27. package/dist/worlds/index.mjs +177 -66
  28. package/dist/worlds/index.mjs.map +1 -1
  29. package/package.json +1 -1
  30. package/runtime/gatewaysdk/environment/bundle_manifest.py +297 -9
  31. package/runtime/gatewaysdk/environment/factory_documents.py +670 -0
  32. package/runtime/gatewaysdk/environment/factory_rules.py +973 -0
  33. package/runtime/gatewaysdk/environment/factory_shapes.py +253 -0
  34. package/runtime/gatewaysdk/environment/factory_spine.py +1155 -0
  35. package/runtime/gatewaysdk/environment/factory_spine_shapes.py +480 -0
  36. package/runtime/gatewaysdk/environment/schema/admission.py +61 -59
  37. package/runtime/gatewaysdk/environment/schema/cast.py +133 -67
  38. package/runtime/gatewaysdk/environment/schema/compiler.py +16 -17
  39. package/runtime/gatewaysdk/environment/schema/handler_errors.py +58 -4
  40. package/runtime/gatewaysdk/environment/schema/host.py +21 -2
  41. package/runtime/gatewaysdk/environment/schema/host_control.py +3 -1
  42. package/runtime/gatewaysdk/environment/schema/host_loops.py +27 -4
  43. package/runtime/gatewaysdk/environment/schema/host_metrics.py +69 -0
  44. package/runtime/gatewaysdk/environment/schema/host_requests.py +21 -0
  45. package/runtime/gatewaysdk/environment/schema/host_session.py +7 -0
  46. package/runtime/gatewaysdk/environment/schema/host_versions.py +4 -0
  47. package/runtime/gatewaysdk/environment/schema/host_workers.py +172 -50
  48. package/runtime/gatewaysdk/environment/schema/ingest.py +12 -3
  49. package/runtime/gatewaysdk/environment/schema/mapping.py +1 -1
  50. package/runtime/gatewaysdk/environment/schema/measured_tests.py +187 -0
  51. package/runtime/gatewaysdk/environment/schema/platform.py +57 -3
  52. package/runtime/gatewaysdk/environment/schema/platform_query.py +4 -3
  53. package/runtime/gatewaysdk/environment/schema/platform_templates.py +105 -17
  54. package/runtime/gatewaysdk/environment/schema/process_memory.py +76 -0
  55. package/runtime/gatewaysdk/environment/schema/redaction.py +13 -0
  56. package/runtime/gatewaysdk/environment/schema/runtime.py +14 -0
  57. package/runtime/gatewaysdk/environment/schema/scaffold.py +21 -4
  58. package/runtime/gatewaysdk/environment/schema/shape_catalog.py +493 -0
  59. package/runtime/gatewaysdk/environment/schema/shape_declarations.py +219 -0
  60. package/runtime/gatewaysdk/environment/schema/skill.py +1 -0
  61. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +1 -0
  62. package/runtime/gatewaysdk/environment/schema/skills/factory-orchestrator/SKILL.md +147 -0
  63. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/ROWS.md +5 -1
  64. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +4 -4
  65. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +2 -2
  66. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +1 -0
  67. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/shape-catalog.md +59 -0
  68. package/runtime/gatewaysdk/environment/schema/validation.py +14 -0
  69. package/runtime/gatewaysdk/environment/schema/worker.py +7 -4
  70. package/runtime/gatewaysdk/environment/schema/worker_key.py +38 -0
  71. package/runtime/gatewaysdk/environment/schema/worker_peaks.py +38 -0
  72. package/runtime/gatewaysdk/environment/schema/worker_watch.py +50 -0
  73. package/runtime/gatewaysdk/environment/schema/workers.py +237 -68
  74. package/runtime/gatewaysdk/environment/schema/world_host.py +56 -62
  75. package/runtime/gatewaysdk/environment/schema/world_tests.py +3 -1
  76. package/skills/connector-schema-authoring/SKILL.md +1 -0
  77. package/skills/connector-schema-authoring/connector-worlds.md +1 -0
  78. package/skills/connector-schema-authoring/world-schema.md +7 -0
  79. package/skills/factory-orchestrator/SKILL.md +147 -0
  80. package/skills/world-data-ingestion/ROWS.md +5 -1
  81. package/skills/world-data-ingestion/SKILL.md +4 -4
  82. package/skills/worlds-getting-started/SKILL.md +2 -2
  83. package/skills/worlds-getting-started/references/cli-mcp-map.md +1 -0
  84. package/skills/worlds-getting-started/references/shape-catalog.md +59 -0
@@ -296,12 +296,13 @@ class WorldTemplate:
296
296
  ) -> Contract:
297
297
  tools = sorted(world["x-gateway"].get("tools") or {})
298
298
  entity = min(world["x-gateway"]["entities"])
299
- (destination / "schema").mkdir(parents=True)
300
- (destination / "schema/world.json").write_bytes(_pretty(world))
301
- shutil.copyfile(_resource(TEMPLATES / "base.json"), destination / "schema/base.json")
299
+ self._lay_out_schema(destination, world, placed)
302
300
  (destination / "tools").mkdir()
303
301
  (destination / "tools/handlers.py").write_bytes(self._handlers())
304
- _write(destination, {target: content for target, content in placed.items() if not _carried(target)})
302
+ _write(
303
+ destination,
304
+ {target: content for target, content in placed.items() if not _carried(target) and not _schema(target)},
305
+ )
305
306
  (destination / "gateway-env.toml").write_text(
306
307
  MANIFEST.format(name=name, connector=connector, serve=", ".join(f'"{t}"' for t in tools)),
307
308
  encoding="utf-8",
@@ -325,6 +326,22 @@ class WorldTemplate:
325
326
  TemplateRecord.of_world(destination, connector=connector, digest=self.digest).write(destination)
326
327
  return contract
327
328
 
329
+ def lay_out_schema(self, destination: Path) -> None:
330
+ """The schema documents :meth:`write` resolves (``world.json``, the packaged ``base.json`` and the
331
+ template's own), uncompiled; the package is not renamed and no rendered file is rendered."""
332
+ self._lay_out_schema(destination, self.world(), self._placed(CUSTOM))
333
+
334
+ @staticmethod
335
+ def _lay_out_schema(destination: Path, world: dict, placed: dict[str, bytes]) -> None:
336
+ (destination / "schema").mkdir(parents=True)
337
+ (destination / "schema/world.json").write_bytes(_pretty(world))
338
+ shutil.copyfile(_resource(TEMPLATES / "base.json"), destination / "schema/base.json")
339
+ _write(destination, {target: content for target, content in placed.items() if _schema(target)})
340
+
341
+
342
+ def _schema(target: str) -> bool:
343
+ return target.startswith("schema/")
344
+
328
345
 
329
346
  class TemplateWorld(WorldTemplate):
330
347
  """An official world's head as stored: a schema world built from a connector template, whose
@@ -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