@vulcan-energy/mcp-helper 0.3.0 → 0.3.1

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.
@@ -9,13 +9,16 @@ import { fileURLToPath } from 'node:url';
9
9
 
10
10
  const hash = bytes => createHash('sha256').update(bytes).digest('hex');
11
11
  const RELEASE_ORIGIN = 'https://usevulcan.app';
12
+ // Catalogue ids: lower-case words joined by '-' or '.' (the EPC id carries its version, 0.13.2); never '..'.
13
+ const BUNDLE_ID = /^[a-z0-9]+(?:[.-][a-z0-9]+)*$/;
12
14
  // As targets.ts:modelArtifacts: not source archives or notices, and not a pinned converter
13
15
  // that is not also the runtime. The host converts with the package's own WASM.
14
16
  const isModelArtifact = (manifest, path) => !path.startsWith('source/') && !path.startsWith('notices/')
15
17
  && !([manifest.preparation?.javascript, manifest.preparation?.wasm].includes(path) && ![manifest.runtime?.javascript, manifest.runtime?.wasm].includes(path));
16
- // Preparation reads only the pinned schema and defaults.
18
+ // Preparation reads only the pinned schema, defaults and product data (targetPreparation.ts:preparationManifest).
17
19
  const isSelected = (manifest, path, preparationOnly) => preparationOnly
18
- ? [manifest.preparation?.schema, manifest.preparation?.defaults].includes(path) : isModelArtifact(manifest, path);
20
+ ? [manifest.preparation?.schema, manifest.preparation?.defaults].includes(path) || (!!manifest.runtime?.data && path.startsWith(manifest.runtime.data))
21
+ : isModelArtifact(manifest, path);
19
22
  function assertArtifactPath(path) {
20
23
  if (!path || path.includes('\\') || path.startsWith('/') || path.split('/').some(part => !part || part === '..' || part === '.')) throw new Error('Invalid target artifact path');
21
24
  }
@@ -24,7 +27,7 @@ export async function readVerifiedBundle(manifestPath, expectedHash, { preparati
24
27
  const bytes = await readFile(manifestPath);
25
28
  if (hash(bytes) !== expectedHash) throw new Error('Target manifest hash mismatch');
26
29
  const manifest = JSON.parse(bytes);
27
- if (!/^[a-z0-9-]+$/.test(manifest.bundleId ?? '') || !Array.isArray(manifest.artifacts)) throw new Error('Invalid target manifest');
30
+ if (!BUNDLE_ID.test(manifest.bundleId ?? '') || !Array.isArray(manifest.artifacts)) throw new Error('Invalid target manifest');
28
31
  const root = await realpath(dirname(manifestPath));
29
32
  const routes = new Map();
30
33
  for (const artifact of manifest.artifacts) {
@@ -39,12 +42,18 @@ export async function readVerifiedBundle(manifestPath, expectedHash, { preparati
39
42
  return { manifest, routes };
40
43
  }
41
44
 
45
+ async function releaseTables() {
46
+ try { return await import('./release-manifests.mjs'); }
47
+ catch { throw new Error('HEM target release pins are missing. Build the target CLI assets with node scripts/hem-targets/build-cli-runtime.mjs, or install a helper release that includes them.'); }
48
+ }
49
+ /** The target a saved pin runs on: the replacement of a retired pin (targets.ts RETIRED_HEM_TARGETS), else the pin. */
50
+ export async function currentBundleId(bundleId, retired) {
51
+ retired ??= (await releaseTables()).RETIRED_HEM_TARGETS;
52
+ return Object.hasOwn(retired, bundleId) ? retired[bundleId].replacement : bundleId;
53
+ }
42
54
  async function releasePin(bundleId, pins) {
43
- if (!pins) {
44
- try { pins = (await import('./release-manifests.mjs')).RELEASE_MANIFEST_HASHES; }
45
- catch { throw new Error('HEM target release pins are missing. Build the target CLI assets with node scripts/hem-targets/build-cli-runtime.mjs, or install a helper release that includes them.'); }
46
- }
47
- const expected = /^[a-z0-9-]+$/.test(bundleId ?? '') && Object.hasOwn(pins, bundleId) && pins[bundleId];
55
+ pins ??= (await releaseTables()).RELEASE_MANIFEST_HASHES;
56
+ const expected = BUNDLE_ID.test(bundleId ?? '') && Object.hasOwn(pins, bundleId) && pins[bundleId];
48
57
  if (!expected) throw new Error(`HEM target '${bundleId}' is not supported by this version; update @vulcan-energy/mcp-helper or @vulcan-energy/analyst, whichever you are running`);
49
58
  return expected;
50
59
  }
@@ -74,7 +83,9 @@ async function fetchBytes(fetcher, bundleId, url, timeoutMs, root) {
74
83
 
75
84
  /** Resolve a released bundle into a local cache, verified against the pins compiled into this helper. */
76
85
  // The user cache (XDG_CACHE_HOME, as other tools read it); a host whose home is read-only sets it.
77
- export async function resolveReleaseBundle(bundleId, { cacheDir = join(process.env.XDG_CACHE_HOME || join(homedir(), '.cache'), 'vulcan/hem-targets'), fetch: fetcher = globalThis.fetch, pins, onProgress, timeoutMs = DOWNLOAD_TIMEOUT_MS, preparationOnly = false } = {}) {
86
+ export async function resolveReleaseBundle(savedBundleId, { cacheDir = join(process.env.XDG_CACHE_HOME || join(homedir(), '.cache'), 'vulcan/hem-targets'), fetch: fetcher = globalThis.fetch, pins, retired, onProgress, timeoutMs = DOWNLOAD_TIMEOUT_MS, preparationOnly = false } = {}) {
87
+ // A test that supplies pins supplies the retired table with them, or none.
88
+ const bundleId = await currentBundleId(savedBundleId, retired ?? (pins ? {} : undefined));
78
89
  const expected = await releasePin(bundleId, pins);
79
90
  const root = join(cacheDir, bundleId);
80
91
  const manifestPath = join(root, 'manifest.json');
@@ -1,15 +1,61 @@
1
1
  // ../hem-target-runtime/src/hem/targets.ts
2
2
  var WRAPPERS = {
3
3
  fhs: {
4
+ /** Wire name the target preparation artifacts accept. */
4
5
  profile: "fhs",
6
+ /** Community defaults template the family's bundles pin for preparation. */
7
+ preparationDefaults: "defaults_template.json",
8
+ /** Schema dialect the editor reads; separate from the wire profile. */
9
+ schemaMode: "fhs",
5
10
  modes: ["actual", "actual-fee", "notional", "notional-fee"],
11
+ /** Modes of a scenario that selects no model wrapper. */
12
+ defaultModes: ["actual"],
6
13
  scenarioModes: {
7
14
  fhs_assumptions: ["actual"],
8
15
  fhs_compliance: ["actual", "actual-fee", "notional", "notional-fee"]
9
16
  },
10
- pythonModule: "bin.fhs",
17
+ /** The run-mode name users see, per scenario wrapper. */
18
+ scenarioLabels: { fhs_assumptions: "Single run", fhs_compliance: "Compliance" },
19
+ /** How the run's results are read; written to target-run.json. */
20
+ resultsKind: "fhs",
11
21
  coreDistribution: "hem-core",
12
- wrapperDistribution: "hem-fhs-wrapper"
22
+ wrapperDistribution: "hem-fhs-wrapper",
23
+ /** Further pinned distributions; each target pins their version and commit in `components`. */
24
+ componentDistributions: [],
25
+ /** Systems take HEM Database products, picked in the editor's product slots. */
26
+ hemDatabaseProducts: false,
27
+ /** The scenario wrapper an agent's single-model run uses when the caller names none. */
28
+ singleRunWrapper: "fhs_compliance",
29
+ /** Fabric from construction bands on an existing building (the editor's `constructionBands` rule). */
30
+ constructionBands: false,
31
+ /** A scenario may pick its own weather file. */
32
+ customWeather: true
33
+ },
34
+ epc: {
35
+ /** vulcan-model-transform `ModelProfile::Epc`. */
36
+ profile: "epc",
37
+ /** The shared template plus the HEM:EPC fields with no Vulcan source. */
38
+ preparationDefaults: "defaults_template_epc.json",
39
+ /** The full-input schema is a Core-shaped input (pydantic unions), not the FHS dialect. */
40
+ schemaMode: "core",
41
+ /** `quick` is the main EPC run only (upstream --skip-smart-metric --skip-fees-metric); `full` adds the smart and FEES runs. */
42
+ modes: ["quick", "full"],
43
+ defaultModes: ["quick"],
44
+ scenarioModes: {
45
+ epc_quick: ["quick"],
46
+ epc_full: ["full"]
47
+ },
48
+ scenarioLabels: { epc_quick: "Rating and energy", epc_full: "Full EPC" },
49
+ resultsKind: "epc",
50
+ coreDistribution: "hem-core",
51
+ wrapperDistribution: "hem-epc-wrapper",
52
+ componentDistributions: ["hem-epc-orchestrator", "hemie", "hem-db-client"],
53
+ hemDatabaseProducts: true,
54
+ singleRunWrapper: "epc_quick",
55
+ // An existing building converts to HEMIE, whose fabric is the age band and constructions.
56
+ constructionBands: true,
57
+ // The Orchestrator runs on its pinned weather (pythonTarget.ts).
58
+ customWeather: false
13
59
  }
14
60
  };
15
61
  function targetWrapper(target) {
@@ -18,9 +64,29 @@ function targetWrapper(target) {
18
64
  return wrapper;
19
65
  }
20
66
  var HEM_TARGETS = [
67
+ // The Rust a9 that ECaaS runs in production (epb-ecaas-api e1c090e, lambda/Cargo.lock). Its wrapper
68
+ // schema equals the Python a9 one, so it keeps that conversion profile's wire name. It is built
69
+ // with the carried patch set fhs-a9-schema-v1 (targetSchemaCorrections.ts); build and parity:
70
+ // docs/development/HEM_Rust_A9_Target.md.
71
+ {
72
+ id: "rust-fhs-a9-9e41af89-f2c2425f-v1",
73
+ label: "HEM:FHS 1.0.0a9",
74
+ runtime: "rust",
75
+ version: "1.0.0a9",
76
+ engineVersion: "1.0.0a9",
77
+ wrapperVersion: "1.0.0a9",
78
+ wrapper: "fhs",
79
+ engineCommit: "9e41af890cc62a1cec08957340231c3591956dac",
80
+ wrapperCommit: "f2c2425f00870e1611750bd2ac1be20132301e0d",
81
+ conversionProfile: "python_fhs_a9",
82
+ // Measured, example_semi_detached in wasm-browser-cli at load 13-19 (13 November): actual mode
83
+ // 5.9-9.0 s, all four modes 48.3-48.6 s (docs/development/HEM_Rust_A9_Target.md).
84
+ status: "provisional",
85
+ typicalRunMinutes: { fhs_assumptions: 0.15, fhs_compliance: 0.8 }
86
+ },
21
87
  {
22
88
  id: "rust-fhs-a7-62d3df70-c5ba2673-v1",
23
- label: "Rust HEM:FHS 1.0.0a7",
89
+ label: "HEM:FHS 1.0.0a7",
24
90
  runtime: "rust",
25
91
  version: "1.0.0a7",
26
92
  engineVersion: "1.0.0a7",
@@ -28,36 +94,42 @@ var HEM_TARGETS = [
28
94
  wrapper: "fhs",
29
95
  engineCommit: "62d3df705690f33b3fc3e905c9971d4f3743bf2e",
30
96
  wrapperCommit: "c5ba2673fbd886cfe4fb528f61b376bdf406ebbd",
31
- conversionProfile: "current_rust_fhs"
32
- },
33
- {
34
- id: "python-fhs-a9-918addad-b9b90138-v1",
35
- label: "Python HEM:FHS 1.0.0a9",
36
- runtime: "python",
37
- version: "1.0.0a9",
38
- engineVersion: "1.0.0a9",
39
- wrapperVersion: "1.0.0a9",
40
- wrapper: "fhs",
41
- engineCommit: "918addad2f9ffbcd9c7a4ed73497d047210be2d2",
42
- wrapperCommit: "b9b901382feb0e5d27f969532842250147fb4068",
43
- conversionProfile: "python_fhs_a9"
44
- },
97
+ conversionProfile: "current_rust_fhs",
98
+ // Actual mode: house_two_storey 7.4 s and 8.1 s through wasm-browser-cli at load 16-20 (13 November). Compliance not measured.
99
+ status: "legacy",
100
+ typicalRunMinutes: { fhs_assumptions: 0.12 }
101
+ }
102
+ ];
103
+ var RECOMMENDED_HEM_TARGET = HEM_TARGETS[0].id;
104
+ var UNRELEASED_HEM_TARGETS = [
45
105
  {
46
- id: "python-fhs-a8-f2ab6cf7-8ca182b0-v1",
47
- label: "Python HEM:FHS 1.0.0a8",
106
+ id: "python-epc-0.13.2-6367f1ec-18032feb-v1",
107
+ label: "HEM:EPC 0.13.2",
48
108
  runtime: "python",
49
- version: "1.0.0a8",
50
- engineVersion: "1.0.0a8",
51
- wrapperVersion: "1.0.0a8",
52
- wrapper: "fhs",
53
- engineCommit: "f2ab6cf78860c36d260cb21396b747cc372f2c9d",
54
- wrapperCommit: "8ca182b0171a3a928059a9c0ec0145ecefe3f4e9",
55
- conversionProfile: "python_fhs_a8"
109
+ version: "0.13.2",
110
+ engineVersion: "2.0.0a4",
111
+ wrapperVersion: "0.13.2",
112
+ wrapper: "epc",
113
+ engineCommit: "6367f1ecb101c7f72a2006a921c732c790b0d338",
114
+ wrapperCommit: "18032feb59294b323fc28af4fb032d34bd44bf67",
115
+ conversionProfile: "epc_full_input_v1",
116
+ components: {
117
+ "hem-epc-orchestrator": { version: "0.13.2a0", commit: "993463233ad0c416e83c4de3b84889280d3c4619" },
118
+ hemie: { version: "0.18.1", commit: "2876e2ec1c7bad2b738c9c3b3685d86860a91f41" },
119
+ "hem-db-client": { version: "1.0.0a10", commit: "9eeb026dd52a612197b5552ca113d8121fa72679" }
120
+ },
121
+ // db-client/data/*.csv at the hem-db-client commit.
122
+ productDataSha256: "d0acf4ebf050e80f3dc576ffbb1295ebeb1176e9fd4a9ec1d151a9e8f4df7457",
123
+ // Quick, measured: house_two_storey 491-535 s in wasm-browser-cli (HEM_EPC_Integration_Plan.md, Status).
124
+ // Full, estimated: 35 min natively at the measured 2.4-2.6x browser ratio (same plan, Measured).
125
+ status: "provisional",
126
+ typicalRunMinutes: { epc_quick: 9, epc_full: 90 },
127
+ estimatedRunMinutes: ["epc_full"]
56
128
  }
57
129
  ];
58
- var RECOMMENDED_HEM_TARGET = HEM_TARGETS[0].id;
130
+ var findHemTarget = (id) => [...HEM_TARGETS, ...UNRELEASED_HEM_TARGETS].find((target) => target.id === id);
59
131
  function resolveHemTarget(id) {
60
- const target = HEM_TARGETS.find((target2) => target2.id === id);
132
+ const target = findHemTarget(id);
61
133
  if (!target) throw new Error(`HEM target '${id}' is unavailable. Select a supported target explicitly; saved runs are never upgraded automatically.`);
62
134
  return target;
63
135
  }
@@ -67,9 +139,11 @@ function modelArtifacts(manifest) {
67
139
  return manifest.artifacts.filter((artifact) => !artifact.path.startsWith("source/") && !artifact.path.startsWith("notices/") && !converter.includes(artifact.path));
68
140
  }
69
141
  function validateTargetManifest(manifest, target) {
70
- if (manifest.bundleId !== target.id || manifest.protocol !== 1 || manifest.engineCommit !== target.engineCommit || manifest.wrapperCommit !== target.wrapperCommit || manifest.conversionProfile !== target.conversionProfile) {
142
+ if (manifest.bundleId !== target.id || manifest.protocol !== 1 || manifest.engineCommit !== target.engineCommit || manifest.wrapperCommit !== target.wrapperCommit || manifest.conversionProfile !== target.conversionProfile || JSON.stringify(sortedComponents(manifest.components)) !== JSON.stringify(sortedComponents(target.components)) || manifest.productDataSha256 !== target.productDataSha256) {
71
143
  throw new Error(`Target manifest identity mismatch for ${target.id}`);
72
144
  }
145
+ const wrapper = targetWrapper(target);
146
+ if (JSON.stringify(Object.keys(target.components ?? {}).sort()) !== JSON.stringify([...wrapper.componentDistributions].sort())) throw new Error(`${target.id} must pin exactly the ${target.wrapper.toUpperCase()} component distributions`);
73
147
  const paths = /* @__PURE__ */ new Set();
74
148
  const sizesByHash = /* @__PURE__ */ new Map();
75
149
  const isRelativePath = (path) => typeof path === "string" && /^[a-zA-Z0-9_./+-]+$/.test(path) && path.split("/").every((segment) => segment !== "" && segment !== "." && segment !== "..");
@@ -86,7 +160,10 @@ function validateTargetManifest(manifest, target) {
86
160
  if (path.startsWith("source/") || path.startsWith("notices/")) throw new Error(`Runtime/preparation cannot reference reserved source/notice material: ${path}`);
87
161
  if (!paths.has(path)) throw new Error(`Target manifest is missing required artifact ${path}`);
88
162
  }
89
- if (!manifest.modes.length || new Set(manifest.modes).size !== manifest.modes.length || manifest.modes.some((mode) => !targetWrapper(target).modes.includes(mode))) throw new Error("Unsupported or duplicate FHS calculation modes");
163
+ if (!manifest.modes.length || new Set(manifest.modes).size !== manifest.modes.length || manifest.modes.some((mode) => !wrapper.modes.includes(mode))) throw new Error(`Unsupported or duplicate ${target.wrapper.toUpperCase()} calculation modes`);
164
+ const { data } = manifest.runtime;
165
+ if (!!data !== !!target.productDataSha256) throw new Error("Runtime product data and its pinned hash must be declared together");
166
+ if (data && (target.runtime !== "python" || data.startsWith("source/") || data.startsWith("notices/") || !data.endsWith("/") || !isRelativePath(data.slice(0, -1)) || !manifest.artifacts.some((artifact) => artifact.path.startsWith(data)))) throw new Error("Runtime product data must be a non-empty relative Python bundle directory ending in /");
90
167
  if (target.runtime === "rust") {
91
168
  if (!manifest.runtime.wasm) throw new Error("Rust target manifest is missing its runtime WASM artifact");
92
169
  if (manifest.modes.some((mode) => mode !== "actual") && manifest.modes.length !== targetWrapper(target).modes.length) throw new Error("Rust target modes require actual alone or the complete compliance set");
@@ -98,11 +175,15 @@ function validateTargetManifest(manifest, target) {
98
175
  for (const file of ["pyodide.asm.js", "pyodide.asm.wasm", "pyodide-lock.json", "python_stdlib.zip"]) {
99
176
  if (!paths.has(`${index}${file}`)) throw new Error(`Python runtime is missing pinned artifact ${index}${file}`);
100
177
  }
101
- if (requiredVersions?.[targetWrapper(target).coreDistribution] !== target.engineVersion || requiredVersions?.[targetWrapper(target).wrapperDistribution] !== target.wrapperVersion) {
178
+ if (requiredVersions?.[wrapper.coreDistribution] !== target.engineVersion || requiredVersions?.[wrapper.wrapperDistribution] !== target.wrapperVersion) {
102
179
  throw new Error(`Python runtime must pin matching engine ${target.engineVersion} and wrapper ${target.wrapperVersion} distributions`);
103
180
  }
181
+ for (const [distribution, { version }] of Object.entries(target.components ?? {})) {
182
+ if (requiredVersions?.[distribution] !== version) throw new Error(`Python runtime must pin ${distribution} ${version}`);
183
+ }
104
184
  }
105
185
  }
186
+ var sortedComponents = (components) => Object.entries(components ?? {}).sort(([a], [b]) => a.localeCompare(b));
106
187
 
107
188
  // ../hem-target-runtime/src/hem/targetAssets.ts
108
189
  var CACHE = "vulcan-hem-artifacts-v1";