@withgateway/sdk 0.3.0 → 0.3.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 (130) hide show
  1. package/README.md +6 -1
  2. package/dist/cli.js +3971 -2338
  3. package/dist/cli.js.map +1 -1
  4. package/dist/cli.mjs +3950 -2318
  5. package/dist/cli.mjs.map +1 -1
  6. package/dist/files/index.d.mts +1 -1
  7. package/dist/files/index.d.ts +1 -1
  8. package/dist/files/index.js +214 -41
  9. package/dist/files/index.js.map +1 -1
  10. package/dist/files/index.mjs +206 -35
  11. package/dist/files/index.mjs.map +1 -1
  12. package/dist/{index-DAb-FCMg.d.ts → index-DUHmS74p.d.ts} +3 -13
  13. package/dist/{index-D6oi1TWE.d.mts → index-mJhG3vZU.d.mts} +3 -13
  14. package/dist/index.d.mts +4 -4
  15. package/dist/index.d.ts +4 -4
  16. package/dist/index.js +1456 -564
  17. package/dist/index.js.map +1 -1
  18. package/dist/index.mjs +1433 -557
  19. package/dist/index.mjs.map +1 -1
  20. package/dist/{media-CbcAfQvd.d.mts → media-BIApiPzS.d.mts} +21 -2
  21. package/dist/{media-CbcAfQvd.d.ts → media-BIApiPzS.d.ts} +21 -2
  22. package/dist/traces/index.d.mts +1 -1
  23. package/dist/traces/index.d.ts +1 -1
  24. package/dist/traces/index.js +211 -38
  25. package/dist/traces/index.js.map +1 -1
  26. package/dist/traces/index.mjs +203 -32
  27. package/dist/traces/index.mjs.map +1 -1
  28. package/dist/tracing/index.d.mts +2 -2
  29. package/dist/tracing/index.d.ts +2 -2
  30. package/dist/tracing/index.js +96 -21
  31. package/dist/tracing/index.js.map +1 -1
  32. package/dist/tracing/index.mjs +96 -21
  33. package/dist/tracing/index.mjs.map +1 -1
  34. package/dist/worlds/index.d.mts +300 -123
  35. package/dist/worlds/index.d.ts +300 -123
  36. package/dist/worlds/index.js +1385 -508
  37. package/dist/worlds/index.js.map +1 -1
  38. package/dist/worlds/index.mjs +1377 -501
  39. package/dist/worlds/index.mjs.map +1 -1
  40. package/package.json +1 -1
  41. package/runtime/gatewaysdk/environment/_bundle.py +2 -27
  42. package/runtime/gatewaysdk/environment/_materialize.py +49 -69
  43. package/runtime/gatewaysdk/environment/_world.py +122 -197
  44. package/runtime/gatewaysdk/environment/backing.py +137 -0
  45. package/runtime/gatewaysdk/environment/core.py +1 -1
  46. package/runtime/gatewaysdk/environment/legacy_sqlite.py +301 -0
  47. package/runtime/gatewaysdk/environment/reward_keys.py +25 -0
  48. package/runtime/gatewaysdk/environment/runtime.py +8 -13
  49. package/runtime/gatewaysdk/environment/schema/__init__.py +4 -4
  50. package/runtime/gatewaysdk/environment/schema/admin_routes.py +86 -0
  51. package/runtime/gatewaysdk/environment/schema/api.py +266 -515
  52. package/runtime/gatewaysdk/environment/schema/batch.py +42 -37
  53. package/runtime/gatewaysdk/environment/schema/bundle_runtime.py +17 -5
  54. package/runtime/gatewaysdk/environment/schema/call_log.py +291 -0
  55. package/runtime/gatewaysdk/environment/schema/call_redaction.py +344 -0
  56. package/runtime/gatewaysdk/environment/schema/cast.py +31 -4
  57. package/runtime/gatewaysdk/environment/schema/compiler.py +334 -158
  58. package/runtime/gatewaysdk/environment/schema/conform.py +8 -12
  59. package/runtime/gatewaysdk/environment/schema/connector.py +27 -62
  60. package/runtime/gatewaysdk/environment/schema/data.py +50 -207
  61. package/runtime/gatewaysdk/environment/schema/database/__init__.py +24 -0
  62. package/runtime/gatewaysdk/environment/schema/database/audit.py +121 -0
  63. package/runtime/gatewaysdk/environment/schema/database/base.py +995 -0
  64. package/runtime/gatewaysdk/environment/schema/database/budget.py +33 -0
  65. package/runtime/gatewaysdk/environment/schema/database/connections.py +101 -0
  66. package/runtime/gatewaysdk/environment/schema/database/engines.py +8 -0
  67. package/runtime/gatewaysdk/environment/schema/database/guard.py +208 -0
  68. package/runtime/gatewaysdk/environment/schema/database/ingest.py +154 -0
  69. package/runtime/gatewaysdk/environment/schema/database/matching.py +58 -0
  70. package/runtime/gatewaysdk/environment/schema/database/provenance.py +30 -0
  71. package/runtime/gatewaysdk/environment/schema/database/rows.py +53 -0
  72. package/runtime/gatewaysdk/environment/schema/database/runtime_rows.py +39 -0
  73. package/runtime/gatewaysdk/environment/schema/database/sqlite.py +367 -0
  74. package/runtime/gatewaysdk/environment/schema/domain_migration.py +236 -0
  75. package/runtime/gatewaysdk/environment/schema/envelope.py +169 -0
  76. package/runtime/gatewaysdk/environment/schema/extract.py +6 -13
  77. package/runtime/gatewaysdk/environment/schema/grading.py +45 -30
  78. package/runtime/gatewaysdk/environment/schema/handler_errors.py +142 -12
  79. package/runtime/gatewaysdk/environment/schema/host.py +158 -250
  80. package/runtime/gatewaysdk/environment/schema/lanes.py +53 -0
  81. package/runtime/gatewaysdk/environment/schema/local.py +44 -71
  82. package/runtime/gatewaysdk/environment/schema/mapping.py +5 -25
  83. package/runtime/gatewaysdk/environment/schema/openapi_import.py +112 -73
  84. package/runtime/gatewaysdk/environment/schema/openapi_paging.py +147 -0
  85. package/runtime/gatewaysdk/environment/schema/openapi_payloads.py +288 -0
  86. package/runtime/gatewaysdk/environment/schema/openapi_routes.py +97 -102
  87. package/runtime/gatewaysdk/environment/schema/openapi_schemas.py +113 -30
  88. package/runtime/gatewaysdk/environment/schema/platform.py +124 -178
  89. package/runtime/gatewaysdk/environment/schema/platform_import.py +2 -3
  90. package/runtime/gatewaysdk/environment/schema/platform_query.py +61 -5
  91. package/runtime/gatewaysdk/environment/schema/primary_key.py +61 -0
  92. package/runtime/gatewaysdk/environment/schema/proof.py +19 -12
  93. package/runtime/gatewaysdk/environment/schema/runtime.py +77 -160
  94. package/runtime/gatewaysdk/environment/schema/served_names.py +58 -0
  95. package/runtime/gatewaysdk/environment/schema/session_files.py +166 -0
  96. package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +2 -2
  97. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +22 -14
  98. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/ROWS.md +29 -3
  99. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +16 -16
  100. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +18 -18
  101. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +3 -2
  102. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +15 -0
  103. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/openapi-import.md +50 -21
  104. package/runtime/gatewaysdk/environment/schema/slack.py +4 -8
  105. package/runtime/gatewaysdk/environment/schema/snapshot.py +385 -129
  106. package/runtime/gatewaysdk/environment/schema/store_contract.py +8 -14
  107. package/runtime/gatewaysdk/environment/schema/tasks.py +140 -55
  108. package/runtime/gatewaysdk/environment/schema/tools_world.py +110 -87
  109. package/runtime/gatewaysdk/environment/schema/ui.py +24 -5
  110. package/runtime/gatewaysdk/environment/schema/ui_static/app.js +100 -130
  111. package/runtime/gatewaysdk/environment/schema/ui_static/index.html +1 -8
  112. package/runtime/gatewaysdk/environment/schema/validation.py +166 -40
  113. package/runtime/gatewaysdk/environment/schema/workers.py +142 -57
  114. package/runtime/gatewaysdk/environment/schema/world_sql.py +81 -0
  115. package/runtime/gatewaysdk/environment/schema/world_tests.py +71 -39
  116. package/runtime/gatewaysdk/environment/score.py +57 -0
  117. package/runtime/gatewaysdk/environment/secret_values.py +36 -0
  118. package/runtime/gatewaysdk/environment/world.py +42 -3
  119. package/runtime/gatewaysdk/environment/world_session_contract.py +32 -5
  120. package/skills/benchmarks-getting-started/SKILL.md +2 -2
  121. package/skills/connector-schema-authoring/SKILL.md +22 -14
  122. package/skills/connector-schema-authoring/connector-worlds.md +26 -10
  123. package/skills/connector-schema-authoring/world-schema.md +111 -51
  124. package/skills/world-data-ingestion/ROWS.md +29 -3
  125. package/skills/world-data-ingestion/SKILL.md +16 -16
  126. package/skills/worlds-getting-started/SKILL.md +18 -18
  127. package/skills/worlds-getting-started/references/cli-mcp-map.md +3 -2
  128. package/skills/worlds-getting-started/references/gotchas.md +15 -0
  129. package/skills/worlds-getting-started/references/openapi-import.md +50 -21
  130. package/runtime/gatewaysdk/environment/schema/store.py +0 -1013
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@withgateway/sdk",
3
- "version": "0.3.0",
3
+ "version": "0.3.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",
@@ -43,18 +43,13 @@ def detect_kind(bundle_path: Path) -> str:
43
43
  return world.kind
44
44
 
45
45
 
46
- # ---------------------------------------------------------------------------
47
- # mock-tools: manifest + handlers
48
- # ---------------------------------------------------------------------------
49
-
50
-
51
46
  @dataclass
52
47
  class EnvManifest:
53
48
  """Parsed ``gateway-env.toml``."""
54
49
 
55
50
  name: str
56
51
  serve: List[str]
57
- db_engine: str = "sqlite"
52
+ db_engine: str
58
53
  raw: Dict[str, Any] = field(default_factory=dict)
59
54
 
60
55
 
@@ -79,18 +74,7 @@ def parse_manifest(bundle_path: Path) -> EnvManifest:
79
74
  if not isinstance(serve, list):
80
75
  raise EnvironmentNotReady(f"{manifest_path}: [tools] serve must be a list of tool names")
81
76
 
82
- db_value = data.get("db")
83
- if isinstance(db_value, dict):
84
- engine = db_value.get("engine") or env_table.get("db") or "sqlite"
85
- elif isinstance(db_value, str):
86
- engine = db_value
87
- else:
88
- engine = env_table.get("db") or "sqlite"
89
- if engine != "sqlite":
90
- raise WorldStartError(
91
- f"db engine {engine!r} is not supported in local mode — P1 runs "
92
- "sqlite in-process (Postgres arrives with hosted worlds, spec §4.9)."
93
- )
77
+ engine = World.from_dir(bundle_path).db_engine(data)
94
78
  return EnvManifest(name=str(name), serve=[str(s) for s in serve], db_engine=engine, raw=data)
95
79
 
96
80
 
@@ -183,7 +167,6 @@ def load_handlers(bundle_path: Path, manifest: EnvManifest) -> Dict[str, Callabl
183
167
  sys.path.remove(bundle_root)
184
168
  except ValueError:
185
169
  pass
186
- # Drop bundle-local "tools" modules and restore anything shadowed.
187
170
  for name in [
188
171
  n for n in sys.modules if n == "tools" or n.startswith("tools.")
189
172
  ]:
@@ -194,18 +177,15 @@ def load_handlers(bundle_path: Path, manifest: EnvManifest) -> Dict[str, Callabl
194
177
  runtime._load_registry.reset(load_token)
195
178
  runtime._strict_registration.reset(strict_token)
196
179
 
197
- # Fallbacks for undecorated bundles.
198
180
  for tool_name in manifest.serve:
199
181
  if tool_name in registry:
200
182
  continue
201
- # (2) a plain module-level function named exactly like the tool.
202
183
  for module in modules:
203
184
  candidate = getattr(module, tool_name, None)
204
185
  if callable(candidate) and getattr(candidate, "__module__", None) == module.__name__:
205
186
  registry[tool_name] = candidate
206
187
  break
207
188
  else:
208
- # (3) run(input, conn=None) in tools/<tool_name>.py.
209
189
  stem_module = modules_by_stem.get(tool_name)
210
190
  run_fn = getattr(stem_module, "run", None) if stem_module else None
211
191
  if callable(run_fn):
@@ -217,11 +197,6 @@ def load_handlers(bundle_path: Path, manifest: EnvManifest) -> Dict[str, Callabl
217
197
  return registry
218
198
 
219
199
 
220
- # ---------------------------------------------------------------------------
221
- # harbor: task enumeration
222
- # ---------------------------------------------------------------------------
223
-
224
-
225
200
  @dataclass
226
201
  class HarborTask:
227
202
  """One Harbor task dir (``task.toml`` + ``instruction.md`` + ``tests/``)."""
@@ -2,77 +2,68 @@
2
2
 
3
3
  from __future__ import annotations
4
4
 
5
- import shutil
6
- import sqlite3
7
5
  import sys
8
6
  from pathlib import Path
9
7
  from tempfile import TemporaryDirectory
10
8
 
11
9
  from ._bundle import load_handlers, parse_manifest
12
10
  from .errors import WorldStartError
13
- from .schema import SQLiteStore, bundle_mode, check_bundle
14
- from .schema.batch import shape_refusal
11
+ from .legacy_sqlite import materialize
12
+ from .schema import WorldDatabase, bundle_mode, check_bundle
13
+ from .schema.batch import raise_shape_refusal, shape_refusal
15
14
  from .schema.compiler import Contract
16
- from .schema.validation import ContractError, fail, read_json, validate
15
+ from .schema.validation import ContractError, read_json
17
16
 
18
17
 
19
- def materialize_template(bundle: Path, destination: Path, *, require_sql: bool = False) -> None:
18
+ def materialize_template(bundle: Path, destination: Path, *, require_sql: bool = False) -> dict | None:
19
+ """The template at ``destination``. Answers the sidecar of the compiled snapshot it
20
+ copied, or None when it applied the data files (or ran a mock-tools world's SQL)."""
20
21
  bundle, destination = Path(bundle), Path(destination)
21
22
  if bundle_mode(bundle) is not None:
22
- contract = check_bundle(bundle)
23
- if destination.exists():
24
- raise ContractError("state_exists", "Refusing to overwrite an existing template")
25
- from .schema.snapshot import current_default, default_snapshot, pin_path
26
-
27
- if current_default(bundle, contract) is not None:
28
- # The compiled snapshot is this exact data through this exact contract,
29
- # already audited: a copy is the materialized template.
30
- destination.parent.mkdir(parents=True, exist_ok=True)
31
- shutil.copyfile(default_snapshot(bundle), destination)
32
- return
33
- if pin_path(bundle).is_file():
34
- # A pinned tree's data is the hosted snapshot; its data files cannot
35
- # stand in for it, so a missing or stale snapshot is refused, not rebuilt.
36
- raise ContractError(
37
- "snapshot_pinned",
38
- "db/snapshot.json pins a hosted snapshot that is not in the tree: run the world on "
39
- "the platform (`gateway worlds session open <slug>`, load_world_to_sandbox), which "
40
- "serves that snapshot, or remove db/snapshot.json to rebuild from the data files",
41
- schema_path="/db/state.sqlite",
42
- )
43
- initial = read_json(bundle / "data/initial.json")
44
- refuse_initial_rows(contract, initial)
45
- try:
46
- with SQLiteStore.create(destination, contract) as store:
47
- store.apply_batch(initial)
48
- # Immutable refresh journals retain each mapping/source contribution.
49
- # Coverage never prunes: every change is an explicit store mutation.
50
- batches = bundle / "data/batches"
51
- if batches.is_symlink():
52
- raise ContractError("path", "Refresh batches cannot be symlinks")
53
- if batches.exists():
54
- for batch in sorted(batches.iterdir()):
55
- if batch.is_symlink() or not batch.is_file() or batch.suffix != ".json":
56
- raise ContractError("path", "Refresh journals must be regular JSON files")
57
- store.apply_batch(read_json(batch))
58
- except BaseException:
59
- destination.unlink(missing_ok=True)
60
- raise
61
- return
23
+ return _materialize_schema(bundle, destination)
62
24
  schema, seed = bundle / "db/schema.sql", bundle / "db/seed.sql"
63
25
  if require_sql and not schema.is_file():
64
26
  raise WorldStartError("mock-tools bundle is missing db/schema.sql")
65
- conn = sqlite3.connect(destination)
27
+ materialize(schema, seed, destination)
28
+ return None
29
+
30
+
31
+ def _materialize_schema(bundle: Path, destination: Path) -> dict | None:
32
+ from .schema.snapshot import current_default, default_snapshot, refuse_unheld_pin
33
+
34
+ contract = check_bundle(bundle)
35
+ if destination.exists():
36
+ raise ContractError("state_exists", "Refusing to overwrite an existing template")
37
+ copied = current_default(bundle, contract)
38
+ if copied is not None:
39
+ # The compiled snapshot holds rows this contract may open; whether they are proven is the caller's (ProvenTemplate).
40
+ WorldDatabase.clone_file(default_snapshot(bundle, contract), destination)
41
+ return copied
42
+ refuse_unheld_pin(bundle, contract)
43
+ initial = read_json(bundle / "data/initial.json")
44
+ refuse_initial_rows(contract, initial)
66
45
  try:
67
- if schema.is_file():
68
- conn.executescript(schema.read_text(encoding="utf-8"))
69
- if seed.is_file():
70
- conn.executescript(seed.read_text(encoding="utf-8"))
71
- conn.commit()
72
- except sqlite3.Error as error:
73
- raise WorldStartError("Failed to build seed database; check db/schema.sql and db/seed.sql") from error
74
- finally:
75
- conn.close()
46
+ with WorldDatabase.create(destination, contract) as store:
47
+ store.apply_batch(initial)
48
+ for journal in _journals(bundle):
49
+ store.apply_batch(read_json(journal))
50
+ except BaseException:
51
+ destination.unlink(missing_ok=True)
52
+ raise
53
+ return None
54
+
55
+
56
+ def _journals(bundle: Path) -> list[Path]:
57
+ """``data/batches/*.json`` in order: each an immutable refresh, applied as an explicit mutation."""
58
+ batches = bundle / "data/batches"
59
+ if batches.is_symlink():
60
+ raise ContractError("path", "Refresh batches cannot be symlinks")
61
+ if not batches.exists():
62
+ return []
63
+ journals = sorted(batches.iterdir())
64
+ if any(batch.is_symlink() or not batch.is_file() or batch.suffix != ".json" for batch in journals):
65
+ raise ContractError("path", "Refresh journals must be regular JSON files")
66
+ return journals
76
67
 
77
68
 
78
69
  def refuse_initial_rows(contract: Contract, initial: object) -> None:
@@ -110,18 +101,7 @@ def refuse_initial_rows(contract: Contract, initial: object) -> None:
110
101
  "refusals": refusals,
111
102
  }
112
103
  row = initial["mutations"][first["index"]].get("value")
113
- spec = contract.entities.get(first["entity"])
114
- if spec is None:
115
- fail("entity", summary + first["detail"], first["pointer"], **context)
116
- if not isinstance(row, dict):
117
- fail("rows", summary + first["detail"], first["pointer"], **context)
118
- if any(name not in row for name in spec["primary_key"]):
119
- fail("primary_key", summary + first["detail"], first["pointer"], **context)
120
- try:
121
- validate(spec["schema"], row, location=f"{spec['location']}/schema")
122
- except ContractError as error:
123
- raise error.contextualize(message=summary + error.detail["message"], **context)
124
- fail("rows", summary + first["detail"], first["pointer"], **context)
104
+ raise_shape_refusal(contract, first, row, summary, context, first["pointer"])
125
105
 
126
106
 
127
107
  def validate_schema_materialization(bundle: Path) -> None:
@@ -136,6 +116,6 @@ def validate_schema_materialization(bundle: Path) -> None:
136
116
  with TemporaryDirectory(prefix="gateway-schema-validation-") as directory:
137
117
  materialize_template(
138
118
  bundle,
139
- Path(directory) / "template.sqlite",
119
+ Path(directory) / "template.db",
140
120
  require_sql=True,
141
121
  )