@withgateway/sdk 0.1.19 → 0.2.0

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 +141 -2
  2. package/dist/cli.js +8677 -1320
  3. package/dist/cli.js.map +1 -1
  4. package/dist/cli.mjs +8683 -1327
  5. package/dist/cli.mjs.map +1 -1
  6. package/dist/index.d.mts +1 -1
  7. package/dist/index.d.ts +1 -1
  8. package/dist/index.js +1005 -55
  9. package/dist/index.js.map +1 -1
  10. package/dist/index.mjs +969 -47
  11. package/dist/index.mjs.map +1 -1
  12. package/dist/tracing/index.js +9 -2
  13. package/dist/tracing/index.js.map +1 -1
  14. package/dist/tracing/index.mjs +9 -2
  15. package/dist/tracing/index.mjs.map +1 -1
  16. package/dist/worlds/index.d.mts +738 -28
  17. package/dist/worlds/index.d.ts +738 -28
  18. package/dist/worlds/index.js +966 -51
  19. package/dist/worlds/index.js.map +1 -1
  20. package/dist/worlds/index.mjs +960 -45
  21. package/dist/worlds/index.mjs.map +1 -1
  22. package/package.json +9 -2
  23. package/runtime/gatewaysdk/__init__.py +0 -0
  24. package/runtime/gatewaysdk/environment/__init__.py +108 -0
  25. package/runtime/gatewaysdk/environment/_bundle.py +281 -0
  26. package/runtime/gatewaysdk/environment/_harbor.py +276 -0
  27. package/runtime/gatewaysdk/environment/_materialize.py +97 -0
  28. package/runtime/gatewaysdk/environment/_tar.py +33 -0
  29. package/runtime/gatewaysdk/environment/_world.py +346 -0
  30. package/runtime/gatewaysdk/environment/core.py +527 -0
  31. package/runtime/gatewaysdk/environment/errors.py +58 -0
  32. package/runtime/gatewaysdk/environment/runtime.py +150 -0
  33. package/runtime/gatewaysdk/environment/schema/__init__.py +35 -0
  34. package/runtime/gatewaysdk/environment/schema/__main__.py +225 -0
  35. package/runtime/gatewaysdk/environment/schema/_slack_fidelity.py +116 -0
  36. package/runtime/gatewaysdk/environment/schema/_slack_scenario.py +183 -0
  37. package/runtime/gatewaysdk/environment/schema/api.py +1628 -0
  38. package/runtime/gatewaysdk/environment/schema/batch.py +755 -0
  39. package/runtime/gatewaysdk/environment/schema/compiler.py +615 -0
  40. package/runtime/gatewaysdk/environment/schema/conform.py +428 -0
  41. package/runtime/gatewaysdk/environment/schema/connector.py +777 -0
  42. package/runtime/gatewaysdk/environment/schema/connectors/apple-business-manager/handlers.py +17 -0
  43. package/runtime/gatewaysdk/environment/schema/connectors/apple-business-manager/parity.json +28 -0
  44. package/runtime/gatewaysdk/environment/schema/connectors/apple-business-manager/provenance.json +233 -0
  45. package/runtime/gatewaysdk/environment/schema/connectors/apple-business-manager/scope.toml +112 -0
  46. package/runtime/gatewaysdk/environment/schema/connectors/apple-business-manager/world.json +1380 -0
  47. package/runtime/gatewaysdk/environment/schema/connectors/base.json +28 -0
  48. package/runtime/gatewaysdk/environment/schema/connectors/custom/handlers.py +18 -0
  49. package/runtime/gatewaysdk/environment/schema/connectors/custom/world.json +123 -0
  50. package/runtime/gatewaysdk/environment/schema/connectors/github/handlers.py +81 -0
  51. package/runtime/gatewaysdk/environment/schema/connectors/github/parity.json +37 -0
  52. package/runtime/gatewaysdk/environment/schema/connectors/github/provenance.json +134 -0
  53. package/runtime/gatewaysdk/environment/schema/connectors/github/scope.toml +158 -0
  54. package/runtime/gatewaysdk/environment/schema/connectors/github/world.json +5869 -0
  55. package/runtime/gatewaysdk/environment/schema/connectors/google-calendar/handlers.py +23 -0
  56. package/runtime/gatewaysdk/environment/schema/connectors/google-calendar/world.json +209 -0
  57. package/runtime/gatewaysdk/environment/schema/connectors/google-drive/handlers.py +18 -0
  58. package/runtime/gatewaysdk/environment/schema/connectors/google-drive/world.json +286 -0
  59. package/runtime/gatewaysdk/environment/schema/connectors/jamf/handlers.py +34 -0
  60. package/runtime/gatewaysdk/environment/schema/connectors/jamf/parity.json +49 -0
  61. package/runtime/gatewaysdk/environment/schema/connectors/jamf/provenance.json +181 -0
  62. package/runtime/gatewaysdk/environment/schema/connectors/jamf/scope.toml +128 -0
  63. package/runtime/gatewaysdk/environment/schema/connectors/jamf/world.json +2218 -0
  64. package/runtime/gatewaysdk/environment/schema/connectors/jira/handlers.py +28 -0
  65. package/runtime/gatewaysdk/environment/schema/connectors/jira/world.json +389 -0
  66. package/runtime/gatewaysdk/environment/schema/connectors/kandji/handlers.py +38 -0
  67. package/runtime/gatewaysdk/environment/schema/connectors/kandji/parity.json +29 -0
  68. package/runtime/gatewaysdk/environment/schema/connectors/kandji/provenance.json +152 -0
  69. package/runtime/gatewaysdk/environment/schema/connectors/kandji/scope.toml +120 -0
  70. package/runtime/gatewaysdk/environment/schema/connectors/kandji/world.json +765 -0
  71. package/runtime/gatewaysdk/environment/schema/connectors/linear/handlers.py +20 -0
  72. package/runtime/gatewaysdk/environment/schema/connectors/linear/world.json +363 -0
  73. package/runtime/gatewaysdk/environment/schema/connectors/microsoft-teams/fidelity.json +45 -0
  74. package/runtime/gatewaysdk/environment/schema/connectors/microsoft-teams/handlers.py +1 -0
  75. package/runtime/gatewaysdk/environment/schema/connectors/microsoft-teams/provenance.json +851 -0
  76. package/runtime/gatewaysdk/environment/schema/connectors/microsoft-teams/scope.md +231 -0
  77. package/runtime/gatewaysdk/environment/schema/connectors/microsoft-teams/teams-types.json +1710 -0
  78. package/runtime/gatewaysdk/environment/schema/connectors/microsoft-teams/world.json +858 -0
  79. package/runtime/gatewaysdk/environment/schema/connectors/netsuite/handlers.py +32 -0
  80. package/runtime/gatewaysdk/environment/schema/connectors/netsuite/parity.json +50 -0
  81. package/runtime/gatewaysdk/environment/schema/connectors/netsuite/provenance.json +137 -0
  82. package/runtime/gatewaysdk/environment/schema/connectors/netsuite/scope.toml +78 -0
  83. package/runtime/gatewaysdk/environment/schema/connectors/netsuite/world.json +16243 -0
  84. package/runtime/gatewaysdk/environment/schema/connectors/salesforce/handlers.py +806 -0
  85. package/runtime/gatewaysdk/environment/schema/connectors/salesforce/parity.json +46 -0
  86. package/runtime/gatewaysdk/environment/schema/connectors/salesforce/provenance.json +143 -0
  87. package/runtime/gatewaysdk/environment/schema/connectors/salesforce/scope.toml +174 -0
  88. package/runtime/gatewaysdk/environment/schema/connectors/salesforce/world.json +4695 -0
  89. package/runtime/gatewaysdk/environment/schema/connectors/slack/MODEL.md +236 -0
  90. package/runtime/gatewaysdk/environment/schema/connectors/slack/capabilities.json +1039 -0
  91. package/runtime/gatewaysdk/environment/schema/connectors/slack/handlers.py +762 -0
  92. package/runtime/gatewaysdk/environment/schema/connectors/slack/parity.json +65 -0
  93. package/runtime/gatewaysdk/environment/schema/connectors/slack/provenance.json +294 -0
  94. package/runtime/gatewaysdk/environment/schema/connectors/slack/scope.toml +44 -0
  95. package/runtime/gatewaysdk/environment/schema/connectors/slack/world.json +4993 -0
  96. package/runtime/gatewaysdk/environment/schema/connectors/workday/handlers.py +75 -0
  97. package/runtime/gatewaysdk/environment/schema/connectors/workday/parity.json +36 -0
  98. package/runtime/gatewaysdk/environment/schema/connectors/workday/provenance.json +179 -0
  99. package/runtime/gatewaysdk/environment/schema/connectors/workday/scope.toml +180 -0
  100. package/runtime/gatewaysdk/environment/schema/connectors/workday/world.json +806 -0
  101. package/runtime/gatewaysdk/environment/schema/data.py +593 -0
  102. package/runtime/gatewaysdk/environment/schema/extract.py +263 -0
  103. package/runtime/gatewaysdk/environment/schema/host.py +2407 -0
  104. package/runtime/gatewaysdk/environment/schema/host_surfaces.py +275 -0
  105. package/runtime/gatewaysdk/environment/schema/platform.py +1272 -0
  106. package/runtime/gatewaysdk/environment/schema/scaffold.py +250 -0
  107. package/runtime/gatewaysdk/environment/schema/skill.py +118 -0
  108. package/runtime/gatewaysdk/environment/schema/skills/agents/connector-template-author.md +202 -0
  109. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/CONNECTORS.md +331 -0
  110. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/CONVENTIONS.md +100 -0
  111. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +313 -0
  112. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/ROWS.md +223 -0
  113. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +293 -0
  114. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +390 -0
  115. package/runtime/gatewaysdk/environment/schema/slack.py +757 -0
  116. package/runtime/gatewaysdk/environment/schema/snapshot.py +479 -0
  117. package/runtime/gatewaysdk/environment/schema/store.py +904 -0
  118. package/runtime/gatewaysdk/environment/schema/tasks.py +525 -0
  119. package/runtime/gatewaysdk/environment/schema/tools_world.py +322 -0
  120. package/runtime/gatewaysdk/environment/schema/validation.py +577 -0
  121. package/runtime/gatewaysdk/environment/schema/worker.py +78 -0
  122. package/runtime/gatewaysdk/environment/schema/workers.py +500 -0
  123. package/runtime/gatewaysdk/environment/schema/world_tests.py +336 -0
  124. package/skills/agents/connector-template-author.md +202 -0
  125. package/skills/connector-schema-authoring/CONNECTORS.md +331 -0
  126. package/skills/connector-schema-authoring/CONVENTIONS.md +100 -0
  127. package/skills/connector-schema-authoring/SKILL.md +313 -0
  128. package/skills/world-data-ingestion/ROWS.md +223 -0
  129. package/skills/world-data-ingestion/SKILL.md +293 -0
  130. package/skills/worlds-getting-started/SKILL.md +390 -0
@@ -0,0 +1,276 @@
1
+ """Harbor worlds — per-task docker sandboxes for harbor-kind environments.
2
+
3
+ A harbor env is a tree of task dirs (``task.toml`` + ``instruction.md`` +
4
+ ``tests/``). ``env.task(name)`` boots one task's declared ``docker_image`` as
5
+ a local container, copies the task dir in, and hands back a
6
+ :class:`HarborWorld`: ``exec`` commands inside the sandbox, then ``verify()``
7
+ runs the task's own grader (``tests/test.sh``) and parses the harbor reward
8
+ contract (``/logs/verifier/reward.json`` scalar ``reward`` + named numeric
9
+ sub-rewards; ``reward.txt`` fallback; missing/unparseable → score ``None``,
10
+ NEVER 0 — mirrors ``benchmark_hub.harbor_adapter`` / the runner's harvest).
11
+
12
+ The docker layer is an injectable interface (:class:`DockerRuntime`) so tests
13
+ run offline against a fake; the real implementation shells out to the docker
14
+ CLI with timeouts on every call (never hangs).
15
+ """
16
+
17
+ from __future__ import annotations
18
+
19
+ import json
20
+ import re
21
+ import shutil
22
+ import subprocess
23
+ import time
24
+ import uuid
25
+ from dataclasses import dataclass
26
+ from pathlib import Path
27
+ from typing import TYPE_CHECKING, Dict, List, Optional, Sequence, Tuple, Union
28
+
29
+ from ._bundle import HarborTask
30
+ from ._world import VerifierResult
31
+ from .errors import VerifierError, WorldStartError
32
+
33
+ if TYPE_CHECKING: # pragma: no cover
34
+ from .core import Environment
35
+
36
+ Command = Union[str, Sequence[str]]
37
+
38
+ REWARD_JSON_PATH = "/logs/verifier/reward.json"
39
+ REWARD_TXT_PATH = "/logs/verifier/reward.txt"
40
+
41
+
42
+ @dataclass
43
+ class ExecResult:
44
+ """Outcome of one command inside the sandbox."""
45
+
46
+ exit_code: int
47
+ stdout: str
48
+ stderr: str
49
+
50
+ @property
51
+ def ok(self) -> bool:
52
+ return self.exit_code == 0
53
+
54
+
55
+ class DockerRuntime:
56
+ """The container operations a harbor world needs. Subclass (or duck-type)
57
+ to inject a fake for offline tests; :class:`CliDockerRuntime` is the real
58
+ thing."""
59
+
60
+ def available(self) -> Tuple[bool, str]:
61
+ """(usable, reason-if-not)."""
62
+ raise NotImplementedError
63
+
64
+ def run_container(self, image: str, *, name: str) -> str:
65
+ """Start a long-lived container from ``image``; return its id."""
66
+ raise NotImplementedError
67
+
68
+ def copy_in(self, container: str, source: Path, dest: str) -> None:
69
+ """Copy a local file/dir into the container at ``dest``."""
70
+ raise NotImplementedError
71
+
72
+ def exec(self, container: str, cmd: Command, *, timeout: float) -> ExecResult:
73
+ """Run a command in the container (str → via ``sh -c``)."""
74
+ raise NotImplementedError
75
+
76
+ def read_file(self, container: str, path: str) -> Optional[bytes]:
77
+ """The file's bytes, or ``None`` when it does not exist."""
78
+ raise NotImplementedError
79
+
80
+ def remove(self, container: str) -> None:
81
+ """Force-remove the container (best-effort)."""
82
+ raise NotImplementedError
83
+
84
+
85
+ class CliDockerRuntime(DockerRuntime):
86
+ """Shells out to the ``docker`` CLI. Every call has a timeout."""
87
+
88
+ def __init__(self, binary: str = "docker", *, pull_timeout: float = 900.0) -> None:
89
+ self._binary = binary
90
+ self._pull_timeout = pull_timeout
91
+
92
+ def _run(self, args: List[str], *, timeout: float, binary_output: bool = False) -> subprocess.CompletedProcess:
93
+ return subprocess.run(
94
+ [self._binary, *args],
95
+ capture_output=True,
96
+ text=not binary_output,
97
+ timeout=timeout,
98
+ )
99
+
100
+ def available(self) -> Tuple[bool, str]:
101
+ if shutil.which(self._binary) is None:
102
+ return False, f"'{self._binary}' not found on PATH"
103
+ try:
104
+ proc = self._run(["version", "--format", "{{.Server.Version}}"], timeout=15)
105
+ except subprocess.TimeoutExpired:
106
+ return False, "docker daemon did not answer within 15s"
107
+ if proc.returncode != 0:
108
+ return False, (proc.stderr or proc.stdout or "docker daemon unreachable").strip()[:300]
109
+ return True, ""
110
+
111
+ def run_container(self, image: str, *, name: str) -> str:
112
+ try:
113
+ proc = self._run(
114
+ ["run", "-d", "--name", name, "--entrypoint", "sleep", image, "infinity"],
115
+ timeout=self._pull_timeout,
116
+ )
117
+ except subprocess.TimeoutExpired as error:
118
+ raise WorldStartError(
119
+ f"docker run {image} timed out after {self._pull_timeout}s (pull too slow?)"
120
+ ) from error
121
+ if proc.returncode != 0:
122
+ raise WorldStartError(
123
+ f"docker run {image} failed: {(proc.stderr or proc.stdout).strip()[:500]}"
124
+ )
125
+ return proc.stdout.strip()
126
+
127
+ def copy_in(self, container: str, source: Path, dest: str) -> None:
128
+ proc = self._run(["cp", str(source), f"{container}:{dest}"], timeout=300)
129
+ if proc.returncode != 0:
130
+ raise WorldStartError(f"docker cp {source} failed: {proc.stderr.strip()[:500]}")
131
+
132
+ def exec(self, container: str, cmd: Command, *, timeout: float) -> ExecResult:
133
+ args = ["exec", container]
134
+ args += ["sh", "-c", cmd] if isinstance(cmd, str) else list(cmd)
135
+ try:
136
+ proc = self._run(args, timeout=timeout)
137
+ except subprocess.TimeoutExpired:
138
+ return ExecResult(exit_code=124, stdout="", stderr=f"timed out after {timeout}s")
139
+ return ExecResult(exit_code=proc.returncode, stdout=proc.stdout, stderr=proc.stderr)
140
+
141
+ def read_file(self, container: str, path: str) -> Optional[bytes]:
142
+ try:
143
+ proc = self._run(["exec", container, "cat", path], timeout=60, binary_output=True)
144
+ except subprocess.TimeoutExpired:
145
+ return None
146
+ return proc.stdout if proc.returncode == 0 else None
147
+
148
+ def remove(self, container: str) -> None:
149
+ try:
150
+ self._run(["rm", "-f", container], timeout=60)
151
+ except subprocess.TimeoutExpired: # pragma: no cover — best-effort cleanup
152
+ pass
153
+
154
+
155
+ def parse_rewards(
156
+ reward_json: Optional[bytes], reward_txt: Optional[bytes]
157
+ ) -> Tuple[Optional[float], Dict[str, float], str]:
158
+ """(scalar score, named sub-rewards, note) from the harbor reward files.
159
+
160
+ ``reward.json``: scalar = the ``reward`` key (or the first numeric value);
161
+ every OTHER numeric key is a named sub-reward. ``reward.txt``: bare float
162
+ fallback. Missing/unparseable → ``(None, {}, why)`` — never 0.
163
+ """
164
+ if reward_json is not None:
165
+ try:
166
+ data = json.loads(reward_json.decode("utf-8"))
167
+ except (ValueError, UnicodeDecodeError):
168
+ data = None
169
+ if isinstance(data, (int, float)) and not isinstance(data, bool):
170
+ return float(data), {}, "scalar reward.json"
171
+ if isinstance(data, dict):
172
+ numeric = {
173
+ key: float(value)
174
+ for key, value in data.items()
175
+ if isinstance(value, (int, float)) and not isinstance(value, bool)
176
+ }
177
+ if "reward" in numeric:
178
+ scalar = numeric.pop("reward")
179
+ return scalar, numeric, "reward.json"
180
+ if numeric:
181
+ first_key = next(iter(numeric))
182
+ scalar = numeric.pop(first_key)
183
+ return scalar, numeric, f"reward.json (no 'reward' key — used '{first_key}')"
184
+ return None, {}, "reward.json held no numeric metrics"
185
+ note = "reward.json unparseable"
186
+ else:
187
+ note = "reward.json missing"
188
+
189
+ if reward_txt is not None:
190
+ try:
191
+ return float(reward_txt.decode("utf-8").strip()), {}, f"{note}; reward.txt fallback"
192
+ except (ValueError, UnicodeDecodeError):
193
+ return None, {}, f"{note}; reward.txt unparseable"
194
+ return None, {}, f"{note}; no reward.txt"
195
+
196
+
197
+ class HarborWorld:
198
+ """One task's live docker sandbox."""
199
+
200
+ def __init__(self, env: "Environment", task: HarborTask, docker: DockerRuntime) -> None:
201
+ self.env = env
202
+ self.task = task
203
+ self._docker = docker
204
+ self.id = uuid.uuid4().hex[:8]
205
+
206
+ usable, reason = docker.available()
207
+ if not usable:
208
+ raise WorldStartError(
209
+ f"docker unavailable: {reason} — install/start Docker, or inject "
210
+ "a DockerRuntime (gwenv.init_from_path(..., docker=...))."
211
+ )
212
+ if not task.docker_image:
213
+ raise WorldStartError(
214
+ f"harbor task '{task.name}' declares no [environment].docker_image "
215
+ "(Dockerfile-only tasks have nothing pullable) — build and tag the "
216
+ "image, set docker_image in task.toml, or run it via the harbor "
217
+ "engine / platform Batch instead."
218
+ )
219
+ container_name = re.sub(r"[^a-zA-Z0-9_.-]", "-", f"gwenv-{env.slug}-{task.name}")[:52] + f"-{self.id}"
220
+ try:
221
+ self.container = docker.run_container(task.docker_image, name=container_name)
222
+ except WorldStartError:
223
+ raise
224
+ except Exception as error: # pragma: no cover — runtime-impl specific
225
+ raise WorldStartError(f"failed to start {task.docker_image}: {error}") from error
226
+ try:
227
+ docker.copy_in(self.container, task.path, "/task")
228
+ except Exception:
229
+ self.close()
230
+ raise
231
+
232
+ def exec(self, cmd: Command, *, timeout: float = 120.0) -> ExecResult:
233
+ """Run a command inside the task sandbox."""
234
+ started = time.perf_counter()
235
+ result = self._docker.exec(self.container, cmd, timeout=timeout)
236
+ summary = cmd if isinstance(cmd, str) else " ".join(cmd)
237
+ self.env._record_route(
238
+ f"{self.task.name}:exec[{summary[:60]}]",
239
+ "env",
240
+ (time.perf_counter() - started) * 1000.0,
241
+ self.id,
242
+ )
243
+ return result
244
+
245
+ def verify(self, name: Optional[str] = None) -> VerifierResult:
246
+ """Run the task's own grader (``tests/test.sh``) and parse the reward
247
+ files. A missing/failed grader yields score ``None`` (never 0), with
248
+ the failure surfaced in ``detail``."""
249
+ if not self.task.has_tests:
250
+ raise VerifierError(f"harbor task '{self.task.name}' ships no tests/ dir — nothing to verify")
251
+
252
+ verifier_cfg = self.task.config.get("verifier") if isinstance(self.task.config.get("verifier"), dict) else {}
253
+ timeout = float(verifier_cfg.get("timeout_sec") or 600.0)
254
+
255
+ self._docker.copy_in(self.container, self.task.path / "tests", "/tests")
256
+ self._docker.exec(self.container, ["mkdir", "-p", "/logs/verifier"], timeout=30)
257
+ run = self._docker.exec(self.container, ["bash", "/tests/test.sh"], timeout=timeout)
258
+
259
+ score, rewards, note = parse_rewards(
260
+ self._docker.read_file(self.container, REWARD_JSON_PATH),
261
+ self._docker.read_file(self.container, REWARD_TXT_PATH),
262
+ )
263
+ detail = note
264
+ if not run.ok:
265
+ detail = f"test.sh exited {run.exit_code} ({(run.stderr or run.stdout).strip()[:300]}); {note}"
266
+ passed = None if score is None else score >= 1.0
267
+ return VerifierResult(
268
+ name=name or self.task.name, passed=passed, score=score, detail=detail, rewards=rewards
269
+ )
270
+
271
+ def state(self, path: str) -> Optional[bytes]:
272
+ """Read a file out of the sandbox (harbor worlds have no SQL surface)."""
273
+ return self._docker.read_file(self.container, path)
274
+
275
+ def close(self) -> None:
276
+ self._docker.remove(self.container)
@@ -0,0 +1,97 @@
1
+ """Shared SDK/hosted template materialization; schema mode never falls back."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import shutil
6
+ import sqlite3
7
+ import sys
8
+ from pathlib import Path
9
+ from tempfile import TemporaryDirectory
10
+
11
+ from ._bundle import load_handlers, parse_manifest
12
+ from .errors import WorldStartError
13
+ from .schema import SQLiteStore, bundle_mode, check_bundle
14
+ from .schema.validation import read_json
15
+
16
+
17
+ def materialize_template(bundle: Path, destination: Path, *, require_sql: bool = False) -> None:
18
+ bundle, destination = Path(bundle), Path(destination)
19
+ if bundle_mode(bundle) is not None:
20
+ contract = check_bundle(bundle)
21
+ if destination.exists():
22
+ from .schema import ContractError
23
+
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
+ from .schema import ContractError
37
+
38
+ raise ContractError(
39
+ "snapshot_pinned",
40
+ "db/snapshot.json pins a hosted snapshot that is not in the tree: fetch the world "
41
+ "with its snapshot (load_world_to_sandbox, gateway worlds pull) instead of "
42
+ "materializing from its data files",
43
+ schema_path="/db/state.sqlite",
44
+ )
45
+ initial = read_json(bundle / "data/initial.json")
46
+ try:
47
+ with SQLiteStore.create(destination, contract) as store:
48
+ store.apply_batch(initial)
49
+ # Immutable refresh journals retain each mapping/source contribution.
50
+ # Coverage never prunes: every change is an explicit store mutation.
51
+ batches = bundle / "data/batches"
52
+ if batches.is_symlink():
53
+ from .schema import ContractError
54
+
55
+ raise ContractError("path", "Refresh batches cannot be symlinks")
56
+ if batches.exists():
57
+ for batch in sorted(batches.iterdir()):
58
+ if batch.is_symlink() or not batch.is_file() or batch.suffix != ".json":
59
+ from .schema import ContractError
60
+
61
+ raise ContractError("path", "Refresh journals must be regular JSON files")
62
+ store.apply_batch(read_json(batch))
63
+ except BaseException:
64
+ destination.unlink(missing_ok=True)
65
+ raise
66
+ return
67
+ schema, seed = bundle / "db/schema.sql", bundle / "db/seed.sql"
68
+ if require_sql and not schema.is_file():
69
+ raise WorldStartError("mock-tools bundle is missing db/schema.sql")
70
+ conn = sqlite3.connect(destination)
71
+ try:
72
+ if schema.is_file():
73
+ conn.executescript(schema.read_text(encoding="utf-8"))
74
+ if seed.is_file():
75
+ conn.executescript(seed.read_text(encoding="utf-8"))
76
+ conn.commit()
77
+ except sqlite3.Error as error:
78
+ raise WorldStartError("Failed to build seed database; check db/schema.sql and db/seed.sql") from error
79
+ finally:
80
+ conn.close()
81
+
82
+
83
+ def validate_schema_materialization(bundle: Path) -> None:
84
+ """Validate compiled artifacts and initial state without retaining a database."""
85
+ bundle = Path(bundle)
86
+ write_bytecode = sys.dont_write_bytecode
87
+ sys.dont_write_bytecode = True
88
+ try:
89
+ load_handlers(bundle, parse_manifest(bundle))
90
+ finally:
91
+ sys.dont_write_bytecode = write_bytecode
92
+ with TemporaryDirectory(prefix="gateway-schema-validation-") as directory:
93
+ materialize_template(
94
+ bundle,
95
+ Path(directory) / "template.sqlite",
96
+ require_sql=True,
97
+ )
@@ -0,0 +1,33 @@
1
+ """Guarded tar extraction.
2
+
3
+ Shared by the benchmark-container ``pull`` path (untrusted-by-provenance), the
4
+ verifiers runner's bundle extraction and the World Host's version cache. Rejects any
5
+ member that would write outside the destination directory — via ``..`` traversal, an absolute path, or a
6
+ sym/hard link — *before* extracting anything, so a malicious or malformed tarball
7
+ cannot escape ``dest_path``.
8
+ """
9
+
10
+ from __future__ import annotations
11
+
12
+ import tarfile
13
+ from pathlib import Path
14
+
15
+
16
+ def safe_tar_extract(tar: tarfile.TarFile, dest_path: str | Path) -> None:
17
+ """Extract ``tar`` into ``dest_path``, refusing any member that escapes it.
18
+
19
+ Raises ``ValueError`` on the first unsafe member (absolute path, ``..``
20
+ component, or a symlink/hardlink). All members are validated up front, so
21
+ nothing is written when any member is unsafe.
22
+ """
23
+ dest = Path(dest_path).resolve()
24
+ for member in tar.getmembers():
25
+ if member.issym() or member.islnk():
26
+ raise ValueError(f"refusing link member in archive: {member.name}")
27
+ member_path = Path(member.name)
28
+ if member_path.is_absolute() or ".." in member_path.parts:
29
+ raise ValueError(f"unsafe path in archive: {member.name}")
30
+ resolved = (dest / member_path).resolve()
31
+ if not resolved.is_relative_to(dest):
32
+ raise ValueError(f"archive member escapes destination: {member.name}")
33
+ tar.extractall(dest)