@newton-xyz/policy-pack-shared 0.2.0 → 0.4.0

package/dist/index.cjs

@@ -21,9 +21,11 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   UnsupportedChainError: () => UnsupportedChainError,
+  UnsupportedEnvError: () => UnsupportedEnvError,
   decodePolicyParams: () => decodePolicyParams,
   encodePolicyParams: () => encodePolicyParams,
-  getDeployment: () => getDeployment
+  getDeployment: () => getDeployment,
+  wrapOutput: () => wrapOutput
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -51,17 +53,28 @@ function decodePolicyParams(pack, encoded) {
 }
 
 // src/pack.ts
-function getDeployment(pack, chainId) {
-  const deployment = pack.deployments[chainId];
-  if (!deployment) {
-    const supported = Object.keys(pack.deployments).sort().join(", ") || "(none)";
+function getDeployment(pack, chainId, env) {
+  const perEnv = pack.deployments[chainId];
+  if (!perEnv) {
+    const supportedChains = Object.keys(pack.deployments).sort().join(", ") || "(none)";
     throw new UnsupportedChainError(
-      `Pack \`${pack.id}\` is not deployed on chain ${chainId}. Supported: ${supported}.`,
+      `Pack \`${pack.id}\` is not deployed on chain ${chainId}. Supported: ${supportedChains}.`,
       pack.id,
       chainId,
       Object.keys(pack.deployments)
     );
   }
+  const deployment = perEnv[env];
+  if (!deployment) {
+    const supportedEnvs = Object.keys(perEnv).sort().join(", ") || "(none)";
+    throw new UnsupportedEnvError(
+      `Pack \`${pack.id}\` is deployed on chain ${chainId} but not in env "${env}". Supported envs on this chain: ${supportedEnvs}.`,
+      pack.id,
+      chainId,
+      env,
+      Object.keys(perEnv)
+    );
+  }
   return deployment;
 }
 var UnsupportedChainError = class extends Error {
@@ -76,4 +89,23 @@ var UnsupportedChainError = class extends Error {
   supportedChainIds;
   name = "UnsupportedChainError";
 };
+var UnsupportedEnvError = class extends Error {
+  constructor(message, packId, chainId, env, supportedEnvs) {
+    super(message);
+    this.packId = packId;
+    this.chainId = chainId;
+    this.env = env;
+    this.supportedEnvs = supportedEnvs;
+  }
+  packId;
+  chainId;
+  env;
+  supportedEnvs;
+  name = "UnsupportedEnvError";
+};
+
+// src/wrap.ts
+function wrapOutput(packId, valueOrError) {
+  return JSON.stringify({ [packId]: valueOrError });
+}
 //# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts","../src/encoding.ts","../src/pack.ts"],"sourcesContent":["export type { ChainId, Deployment } from \"./deployment\";\nexport { decodePolicyParams, encodePolicyParams } from \"./encoding\";\nexport type {\n\tPolicyPack,\n\tPrepareQueryArgs,\n\tPrepareQueryResult,\n} from \"./pack\";\nexport {\n\tgetDeployment,\n\tUnsupportedChainError,\n} from \"./pack\";\n","import { type Hex, hexToBytes, toHex } from \"viem\";\nimport type { z } from \"zod\";\n\n/**\n * The on-chain `policyParams` byte format is a Newton-protocol invariant. The\n * AVS host reads it as `String::from_utf8 → serde_json::from_str` (see\n * `newton-prover-avs/crates/core/src/common/task.rs:402-408`); the SDK must\n * therefore write **UTF-8 JSON**. Keys are sorted recursively so two\n * semantically-equal params objects always produce byte-identical output —\n * the SDK's `verifyPolicyBinding` does a byte-equality check against\n * `getPolicyConfig().policyParams`, which would otherwise depend on JS\n * `JSON.stringify` insertion order.\n */\nfunction sortKeysDeep(value: unknown): unknown {\n\tif (Array.isArray(value)) return value.map(sortKeysDeep);\n\tif (value && typeof value === \"object\") {\n\t\tconst obj = value as Record<string, unknown>;\n\t\tconst sorted: Record<string, unknown> = {};\n\t\tfor (const key of Object.keys(obj).sort()) {\n\t\t\tsorted[key] = sortKeysDeep(obj[key]);\n\t\t}\n\t\treturn sorted;\n\t}\n\treturn value;\n}\n\n/**\n * Encode a pack's params for on-chain storage. Validates against the pack's\n * `paramsSchema` so a curator typo throws here rather than silently writing\n * AVS-rejecting bytes. Returns `Hex` so it drops directly into a viem\n * `setPolicy(bytes)` call.\n */\nexport function encodePolicyParams<T>(\n\tpack: { readonly paramsSchema: z.ZodType<T> },\n\tparams: T,\n): Hex {\n\tconst validated = pack.paramsSchema.parse(params);\n\treturn toHex(JSON.stringify(sortKeysDeep(validated)));\n}\n\n/**\n * Decode `policyParams` bytes read from `getPolicyConfig().policyParams` back\n * into the pack's typed params shape. Revalidates against `paramsSchema` so a\n * stale or corrupted on-chain blob throws at the SDK boundary rather than\n * yielding a partially-valid object that crashes deeper in the call.\n *\n * `fatal: true` matches AVS-side `String::from_utf8` behavior — invalid UTF-8\n * throws here rather than silently becoming U+FFFD and diverging from a path\n * the AVS would reject.\n */\nexport function decodePolicyParams<T>(\n\tpack: { readonly paramsSchema: z.ZodType<T> },\n\tencoded: Hex,\n): T {\n\tconst json = new TextDecoder(\"utf-8\", { fatal: true }).decode(hexToBytes(encoded));\n\treturn pack.paramsSchema.parse(JSON.parse(json));\n}\n","import type { Address, Hex, PublicClient } from \"viem\";\nimport type { z } from \"zod\";\nimport type { ChainId, Deployment } from \"./deployment\";\n\n/**\n * Inputs that a pack's `prepareQuery` reads at intent-build time.\n *\n * The Shield SDK passes a viem `PublicClient` (so the pack can read on-chain\n * state) and the vault address the curator is acting on. Packs that don't\n * need on-chain state can ignore both — `prepareQuery` is optional.\n */\nexport interface PrepareQueryArgs {\n\treadonly publicClient: PublicClient;\n\treadonly vault: Address;\n}\n\n/**\n * `wasmArgs` payload (untyped at this layer; each pack narrows it via its own\n * `WasmArgsSchema`) plus an optional pre-image hash for binding the AVS-side\n * evaluation to a specific on-chain state. VaultsFYI uses this to bind the\n * evaluation to a `keccak(supplyQueue)` snapshot so the policy can reject\n * attestations whose underlying allocation has shifted between intent build\n * and on-chain submission.\n */\nexport interface PrepareQueryResult<TWasmArgs> {\n\treadonly wasmArgs: TWasmArgs;\n\treadonly freshnessHash?: Hex;\n}\n\n/**\n * Canonical typed contract every published `@newton-xyz/policy-pack-<name>`\n * package implements. `@newton-xyz/newton-shield-sdk`'s `createShield(...)`\n * accepts `PolicyPack<P, W, S>` as the curator's pack argument.\n *\n * Type parameters:\n * - `TParams`   — the shape stored on-chain in `NewtonPolicyData.policyParams`\n *                  (e.g. risk envelope thresholds for VaultsFYI).\n * - `TWasmArgs` — the shape passed to the policy's WASM oracle at evaluation\n *                  time (e.g. `{ vault, network, lastKnownAllocationHash }`).\n * - `TSecrets`  — required API credentials uploaded before any run/sim.\n *\n * The fields:\n * - `id`             — stable identifier of the form `<pack>/<purpose>/<version>`,\n *                       e.g. `vaultsfyi/risk-envelope/v1`. Used for telemetry\n *                       and for cross-referencing the `policy_metadata.json`.\n * - `paramsSchema`   — zod schema enforced at curator setup time when the\n *                       pack is bound to a `NewtonPolicyData`.\n * - `wasmArgsSchema` — zod schema enforced per call when the SDK builds the\n *                       intent and forwards `wasmArgs` to the gateway.\n * - `secretsSchema`  — zod schema enforced at upload-time. Validates the\n *                       shape of the secrets the operator stores in the AVS.\n *\n * Encoding is *not* a per-pack concern. The on-chain `policyParams` byte\n * format is a Newton-protocol invariant — UTF-8 JSON, sorted keys —\n * implemented once in this package as `encodePolicyParams` /\n * `decodePolicyParams`. See `./encoding.ts`. Earlier shapes of this\n * interface required each pack to ship its own `encodeParams` /\n * `decodeParams`; that structurally invited drift (vaultsfyi@0.2.0 shipped\n * ABI bytes against an AVS that reads `serde_json::from_str`, breaking\n * every call). The interface now leaves byte-format to the protocol.\n *\n * - `prepareQuery`   — optional. When present, the SDK invokes it on every\n *                       call to gather chain-state freshness inputs. Packs\n *                       that don't need this (e.g. KYC-only packs) omit it.\n *                       The optional second `options` argument is a\n *                       pack-typed escape hatch for per-call overrides —\n *                       e.g. VaultsFYI's `previousAllocationHash` for\n *                       freshness binding. Each concrete pack narrows it\n *                       via its own `prepareQuery` signature; the shared\n *                       interface keeps it `unknown` so the SDK can\n *                       forward it verbatim.\n * - `deployments`    — `chainId → Deployment` map sliced from the upstream\n *                       `deployments.json` for this pack only. Typed as\n *                       `Partial<Record<ChainId, Deployment>>` so callers\n *                       must handle `undefined` for unsupported chains\n *                       rather than silently reading `.policy` off nothing.\n *                       Use `getDeployment(pack, chainId)` from this package\n *                       for the safe lookup.\n * - `metadata`       — static identity from the pack's `policy_metadata.json`.\n */\nexport interface PolicyPack<TParams, TWasmArgs, TSecrets> {\n\treadonly id: string;\n\treadonly paramsSchema: z.ZodType<TParams>;\n\treadonly wasmArgsSchema: z.ZodType<TWasmArgs>;\n\treadonly secretsSchema: z.ZodType<TSecrets>;\n\tprepareQuery?(args: PrepareQueryArgs, options?: unknown): Promise<PrepareQueryResult<TWasmArgs>>;\n\treadonly deployments: Readonly<Partial<Record<ChainId, Deployment>>>;\n\treadonly metadata: {\n\t\treadonly name: string;\n\t\treadonly version: string;\n\t\treadonly description: string;\n\t\treadonly author?: string;\n\t\treadonly link?: string;\n\t};\n}\n\n/**\n * Safe lookup helper. Returns the `Deployment` for `chainId` if the pack is\n * deployed on that chain, or throws `UnsupportedChainError` with the list of\n * chain ids the pack is known to support. Use this at every SDK callsite that\n * reads `pack.deployments[chainId]` so unsupported-chain failures surface\n * immediately rather than as `undefined.policy` further down.\n */\nexport function getDeployment<TParams, TWasmArgs, TSecrets>(\n\tpack: PolicyPack<TParams, TWasmArgs, TSecrets>,\n\tchainId: ChainId,\n): Deployment {\n\tconst deployment = pack.deployments[chainId];\n\tif (!deployment) {\n\t\tconst supported = Object.keys(pack.deployments).sort().join(\", \") || \"(none)\";\n\t\tthrow new UnsupportedChainError(\n\t\t\t`Pack \\`${pack.id}\\` is not deployed on chain ${chainId}. Supported: ${supported}.`,\n\t\t\tpack.id,\n\t\t\tchainId,\n\t\t\tObject.keys(pack.deployments),\n\t\t);\n\t}\n\treturn deployment;\n}\n\n/**\n * Thrown by `getDeployment` when a pack is asked for a chain it isn't\n * deployed on. SDK consumers can catch this specifically to surface a\n * curator-friendly error rather than a `TypeError: Cannot read property\n * 'policy' of undefined`.\n */\nexport class UnsupportedChainError extends Error {\n\toverride readonly name = \"UnsupportedChainError\";\n\tconstructor(\n\t\tmessage: string,\n\t\treadonly packId: string,\n\t\treadonly chainId: ChainId,\n\t\treadonly supportedChainIds: ReadonlyArray<ChainId>,\n\t) {\n\t\tsuper(message);\n\t}\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACAA,kBAA4C;AAa5C,SAAS,aAAa,OAAyB;AAC9C,MAAI,MAAM,QAAQ,KAAK,EAAG,QAAO,MAAM,IAAI,YAAY;AACvD,MAAI,SAAS,OAAO,UAAU,UAAU;AACvC,UAAM,MAAM;AACZ,UAAM,SAAkC,CAAC;AACzC,eAAW,OAAO,OAAO,KAAK,GAAG,EAAE,KAAK,GAAG;AAC1C,aAAO,GAAG,IAAI,aAAa,IAAI,GAAG,CAAC;AAAA,IACpC;AACA,WAAO;AAAA,EACR;AACA,SAAO;AACR;AAQO,SAAS,mBACf,MACA,QACM;AACN,QAAM,YAAY,KAAK,aAAa,MAAM,MAAM;AAChD,aAAO,mBAAM,KAAK,UAAU,aAAa,SAAS,CAAC,CAAC;AACrD;AAYO,SAAS,mBACf,MACA,SACI;AACJ,QAAM,OAAO,IAAI,YAAY,SAAS,EAAE,OAAO,KAAK,CAAC,EAAE,WAAO,wBAAW,OAAO,CAAC;AACjF,SAAO,KAAK,aAAa,MAAM,KAAK,MAAM,IAAI,CAAC;AAChD;;;AC+CO,SAAS,cACf,MACA,SACa;AACb,QAAM,aAAa,KAAK,YAAY,OAAO;AAC3C,MAAI,CAAC,YAAY;AAChB,UAAM,YAAY,OAAO,KAAK,KAAK,WAAW,EAAE,KAAK,EAAE,KAAK,IAAI,KAAK;AACrE,UAAM,IAAI;AAAA,MACT,UAAU,KAAK,EAAE,+BAA+B,OAAO,gBAAgB,SAAS;AAAA,MAChF,KAAK;AAAA,MACL;AAAA,MACA,OAAO,KAAK,KAAK,WAAW;AAAA,IAC7B;AAAA,EACD;AACA,SAAO;AACR;AAQO,IAAM,wBAAN,cAAoC,MAAM;AAAA,EAEhD,YACC,SACS,QACA,SACA,mBACR;AACD,UAAM,OAAO;AAJJ;AACA;AACA;AAAA,EAGV;AAAA,EALU;AAAA,EACA;AAAA,EACA;AAAA,EALQ,OAAO;AAS1B;","names":[]}
+{"version":3,"sources":["../src/index.ts","../src/encoding.ts","../src/pack.ts","../src/wrap.ts"],"sourcesContent":["export type { ChainId, Deployment, GatewayEnv } from \"./deployment\";\nexport { decodePolicyParams, encodePolicyParams } from \"./encoding\";\nexport type {\n\tPolicyPack,\n\tPrepareQueryArgs,\n\tPrepareQueryResult,\n} from \"./pack\";\nexport {\n\tgetDeployment,\n\tUnsupportedChainError,\n\tUnsupportedEnvError,\n} from \"./pack\";\nexport { wrapOutput } from \"./wrap\";\n","import { type Hex, hexToBytes, toHex } from \"viem\";\nimport type { z } from \"zod\";\n\n/**\n * The on-chain `policyParams` byte format is a Newton-protocol invariant. The\n * AVS host reads it as `String::from_utf8 → serde_json::from_str` (see\n * `newton-prover-avs/crates/core/src/common/task.rs:402-408`); the SDK must\n * therefore write **UTF-8 JSON**. Keys are sorted recursively so two\n * semantically-equal params objects always produce byte-identical output —\n * the SDK's `verifyPolicyBinding` does a byte-equality check against\n * `getPolicyConfig().policyParams`, which would otherwise depend on JS\n * `JSON.stringify` insertion order.\n */\nfunction sortKeysDeep(value: unknown): unknown {\n\tif (Array.isArray(value)) return value.map(sortKeysDeep);\n\tif (value && typeof value === \"object\") {\n\t\tconst obj = value as Record<string, unknown>;\n\t\tconst sorted: Record<string, unknown> = {};\n\t\tfor (const key of Object.keys(obj).sort()) {\n\t\t\tsorted[key] = sortKeysDeep(obj[key]);\n\t\t}\n\t\treturn sorted;\n\t}\n\treturn value;\n}\n\n/**\n * Encode a pack's params for on-chain storage. Validates against the pack's\n * `paramsSchema` so a curator typo throws here rather than silently writing\n * AVS-rejecting bytes. Returns `Hex` so it drops directly into a viem\n * `setPolicy(bytes)` call.\n */\nexport function encodePolicyParams<T>(\n\tpack: { readonly paramsSchema: z.ZodType<T> },\n\tparams: T,\n): Hex {\n\tconst validated = pack.paramsSchema.parse(params);\n\treturn toHex(JSON.stringify(sortKeysDeep(validated)));\n}\n\n/**\n * Decode `policyParams` bytes read from `getPolicyConfig().policyParams` back\n * into the pack's typed params shape. Revalidates against `paramsSchema` so a\n * stale or corrupted on-chain blob throws at the SDK boundary rather than\n * yielding a partially-valid object that crashes deeper in the call.\n *\n * `fatal: true` matches AVS-side `String::from_utf8` behavior — invalid UTF-8\n * throws here rather than silently becoming U+FFFD and diverging from a path\n * the AVS would reject.\n */\nexport function decodePolicyParams<T>(\n\tpack: { readonly paramsSchema: z.ZodType<T> },\n\tencoded: Hex,\n): T {\n\tconst json = new TextDecoder(\"utf-8\", { fatal: true }).decode(hexToBytes(encoded));\n\treturn pack.paramsSchema.parse(JSON.parse(json));\n}\n","import type { Address, Hex, PublicClient } from \"viem\";\nimport type { z } from \"zod\";\nimport type { ChainId, Deployment, GatewayEnv } from \"./deployment\";\n\n/**\n * Inputs that a pack's `prepareQuery` reads at intent-build time.\n *\n * The Shield SDK passes a viem `PublicClient` (so the pack can read on-chain\n * state) and the vault address the curator is acting on. Packs that don't\n * need on-chain state can ignore both — `prepareQuery` is optional.\n */\nexport interface PrepareQueryArgs {\n\treadonly publicClient: PublicClient;\n\treadonly vault: Address;\n}\n\n/**\n * `wasmArgs` payload (untyped at this layer; each pack narrows it via its own\n * `WasmArgsSchema`) plus an optional pre-image hash for binding the AVS-side\n * evaluation to a specific on-chain state. VaultsFYI uses this to bind the\n * evaluation to a `keccak(supplyQueue)` snapshot so the policy can reject\n * attestations whose underlying allocation has shifted between intent build\n * and on-chain submission.\n */\nexport interface PrepareQueryResult<TWasmArgs> {\n\treadonly wasmArgs: TWasmArgs;\n\treadonly freshnessHash?: Hex;\n}\n\n/**\n * Canonical typed contract every published `@newton-xyz/policy-pack-<name>`\n * package implements. `@newton-xyz/newton-shield-sdk`'s `createShield(...)`\n * accepts `PolicyPack<P, W, S>` as the curator's pack argument.\n *\n * Type parameters:\n * - `TParams`   — the shape stored on-chain in `NewtonPolicyData.policyParams`\n *                  (e.g. risk envelope thresholds for VaultsFYI).\n * - `TWasmArgs` — the shape passed to the policy's WASM oracle at evaluation\n *                  time (e.g. `{ vault, network, lastKnownAllocationHash }`).\n * - `TSecrets`  — required API credentials uploaded before any run/sim.\n *\n * The fields:\n * - `id`             — stable identifier of the form `<pack>/<purpose>/<version>`,\n *                       e.g. `vaultsfyi/risk-envelope/v1`. Used for telemetry\n *                       and for cross-referencing the `policy_metadata.json`.\n * - `paramsSchema`   — zod schema enforced at curator setup time when the\n *                       pack is bound to a `NewtonPolicyData`.\n * - `wasmArgsSchema` — zod schema enforced per call when the SDK builds the\n *                       intent and forwards `wasmArgs` to the gateway.\n * - `secretsSchema`  — zod schema enforced at upload-time. Validates the\n *                       shape of the secrets the operator stores in the AVS.\n *\n * Encoding is *not* a per-pack concern. The on-chain `policyParams` byte\n * format is a Newton-protocol invariant — UTF-8 JSON, sorted keys —\n * implemented once in this package as `encodePolicyParams` /\n * `decodePolicyParams`. See `./encoding.ts`. Earlier shapes of this\n * interface required each pack to ship its own `encodeParams` /\n * `decodeParams`; that structurally invited drift (vaultsfyi@0.2.0 shipped\n * ABI bytes against an AVS that reads `serde_json::from_str`, breaking\n * every call). The interface now leaves byte-format to the protocol.\n *\n * - `prepareQuery`   — optional. When present, the SDK invokes it on every\n *                       call to gather chain-state freshness inputs. Packs\n *                       that don't need this (e.g. KYC-only packs) omit it.\n *                       The optional second `options` argument is a\n *                       pack-typed escape hatch for per-call overrides —\n *                       e.g. VaultsFYI's `previousAllocationHash` for\n *                       freshness binding. Each concrete pack narrows it\n *                       via its own `prepareQuery` signature; the shared\n *                       interface keeps it `unknown` so the SDK can\n *                       forward it verbatim.\n * - `deployments`    — `chainId → env → Deployment` map sliced from the\n *                       upstream `deployments.json` for this pack only.\n *                       Typed as `Partial<Record<ChainId, Partial<Record<GatewayEnv,\n *                       Deployment>>>>` so callers must handle `undefined`\n *                       both for unsupported chains and for chains where\n *                       only one env has been deployed. Use\n *                       `getDeployment(pack, chainId, env)` from this\n *                       package for the safe lookup.\n * - `metadata`       — static identity from the pack's `policy_metadata.json`.\n */\nexport interface PolicyPack<TParams, TWasmArgs, TSecrets> {\n\treadonly id: string;\n\treadonly paramsSchema: z.ZodType<TParams>;\n\treadonly wasmArgsSchema: z.ZodType<TWasmArgs>;\n\treadonly secretsSchema: z.ZodType<TSecrets>;\n\tprepareQuery?(args: PrepareQueryArgs, options?: unknown): Promise<PrepareQueryResult<TWasmArgs>>;\n\treadonly deployments: Readonly<\n\t\tPartial<Record<ChainId, Readonly<Partial<Record<GatewayEnv, Deployment>>>>>\n\t>;\n\treadonly metadata: {\n\t\treadonly name: string;\n\t\treadonly version: string;\n\t\treadonly description: string;\n\t\treadonly author?: string;\n\t\treadonly link?: string;\n\t};\n}\n\n/**\n * Safe lookup helper. Returns the `Deployment` for `(chainId, env)` if the\n * pack is deployed there, or throws — `UnsupportedChainError` if the chain\n * itself has no entry, `UnsupportedEnvError` if the chain has at least one\n * env but not the one requested. Use this at every SDK callsite that reads\n * `pack.deployments[chainId][env]` so unsupported-cell failures surface\n * immediately rather than as `undefined.policy` further down.\n */\nexport function getDeployment<TParams, TWasmArgs, TSecrets>(\n\tpack: PolicyPack<TParams, TWasmArgs, TSecrets>,\n\tchainId: ChainId,\n\tenv: GatewayEnv,\n): Deployment {\n\tconst perEnv = pack.deployments[chainId];\n\tif (!perEnv) {\n\t\tconst supportedChains = Object.keys(pack.deployments).sort().join(\", \") || \"(none)\";\n\t\tthrow new UnsupportedChainError(\n\t\t\t`Pack \\`${pack.id}\\` is not deployed on chain ${chainId}. Supported: ${supportedChains}.`,\n\t\t\tpack.id,\n\t\t\tchainId,\n\t\t\tObject.keys(pack.deployments),\n\t\t);\n\t}\n\tconst deployment = perEnv[env];\n\tif (!deployment) {\n\t\tconst supportedEnvs = Object.keys(perEnv).sort().join(\", \") || \"(none)\";\n\t\tthrow new UnsupportedEnvError(\n\t\t\t`Pack \\`${pack.id}\\` is deployed on chain ${chainId} but not in env \"${env}\". Supported envs on this chain: ${supportedEnvs}.`,\n\t\t\tpack.id,\n\t\t\tchainId,\n\t\t\tenv,\n\t\t\tObject.keys(perEnv) as GatewayEnv[],\n\t\t);\n\t}\n\treturn deployment;\n}\n\n/**\n * Thrown by `getDeployment` when a pack is asked for a chain it isn't\n * deployed on. SDK consumers can catch this specifically to surface a\n * curator-friendly error rather than a `TypeError: Cannot read property\n * 'policy' of undefined`.\n */\nexport class UnsupportedChainError extends Error {\n\toverride readonly name = \"UnsupportedChainError\";\n\tconstructor(\n\t\tmessage: string,\n\t\treadonly packId: string,\n\t\treadonly chainId: ChainId,\n\t\treadonly supportedChainIds: ReadonlyArray<ChainId>,\n\t) {\n\t\tsuper(message);\n\t}\n}\n\n/**\n * Thrown by `getDeployment` when a pack is deployed on the requested chain\n * but not in the requested env. Distinct from `UnsupportedChainError`\n * because the recovery is different: the curator either picks a different\n * env (typo / wrong gateway) or the AVS team needs to deploy the pack into\n * the requested env.\n */\nexport class UnsupportedEnvError extends Error {\n\toverride readonly name = \"UnsupportedEnvError\";\n\tconstructor(\n\t\tmessage: string,\n\t\treadonly packId: string,\n\t\treadonly chainId: ChainId,\n\t\treadonly env: GatewayEnv,\n\t\treadonly supportedEnvs: ReadonlyArray<GatewayEnv>,\n\t) {\n\t\tsuper(message);\n\t}\n}\n","/**\n * Wrap a pack's WASM oracle output under its top-level `PACK_ID` key. Every\n * `policy.js` MUST call this on every return path (success AND error) so the\n * AVS-side `merge_jsons` (`newton-prover-avs/crates/operator/src/simulation.rs:296`)\n * composes cleanly across packs without top-level key collisions.\n *\n * The merge is shallow + last-wins: pre-namespacing, vaultsfyi's\n * `risk_score: number` would silently clobber chainalysis's `risk_score: string`\n * under composition. After namespacing, every pack's output sits under its\n * unique `PACK_ID` key and merges into a single `data.wasm` blob that\n * composite Rego can reference unambiguously as `data.wasm.<pack-id>.<field>`.\n *\n * The contract this helper locks:\n * - **Output is JSON-stringified** so `policy.js` can `return wrapOutput(...)`\n *   directly. The AVS host parses every PolicyData WASM's stdout as UTF-8\n *   JSON before merging.\n * - **Top-level keys are exactly `[packId]`** — assertable in\n *   `<pack>/wrapping_test.rego` with a fixture `data.wasm.<pack-id>` shape.\n *   To be enforced at PR time by an AST-lint CI guard (Phase 0 § Stream C,\n *   shipped in a separate PR) that flags any raw `return JSON.stringify(...)`\n *   callsite in `<pack>/policy.js` not routed through this helper.\n * - **`undefined` and other JSON-nonrepresentable payloads** (functions,\n *   symbols) cause `JSON.stringify` to omit the key, returning `'{}'` rather\n *   than `{ [packId]: undefined }`. The AVS contract doesn't admit such\n *   payloads — every `policy.js` returns either a structured success object\n *   or `{ error: \"...\" }` — so this is documented as out-of-contract input\n *   rather than guarded at runtime. The Stream C AST-lint catches the\n *   shape upstream.\n * - **Both success and error paths route through here.** Returning\n *   `{\"error\": \"...\"}` directly from `policy.js` would collide across packs in\n *   `merge_jsons` (every pack's error key would land at the top level and\n *   the last one wins). Wrapping the error under `[packId]` keeps per-pack\n *   error semantics (composite Rego can selectively deny on\n *   `data.wasm.<pack-id>.error`).\n *\n * @param packId The pack's stable id, matching the `<name>OracleModule.id`\n *               that ships in Phase 1 and the `KNOWN_PACK_IDS` registry in\n *               Phase 2. Convention: lowercase single-word, matches the\n *               pack's folder name (e.g. `\"vaultsfyi\"`, `\"chainalysis\"`).\n * @param valueOrError The pack's output payload — `{ score, risk_score, ... }`\n *                     for success, `{ error: \"...\" }` for failure paths.\n *                     Untyped at this layer because each pack's WASM emits\n *                     its own shape and the `PolicyPack` /  `OracleModule`\n *                     interfaces today carry input schemas (`paramsSchema`,\n *                     `wasmArgsSchema`, `secretsSchema`) but no on-chain\n *                     output schema — composite Rego references fields by\n *                     name (`data.wasm.<pack-id>.<field>`) and trusts the\n *                     pack-specific WASM bindings paired to each\n *                     `wasm_cid` in the manifest (Phase 1.5).\n * @returns JSON-stringified `{ [packId]: valueOrError }` ready to drop into\n *          a `policy.js` `return` statement.\n *\n * @example\n *   // vaultsfyi/policy.js (success path)\n *   return wrapOutput(\"vaultsfyi\", { score: 80, risk_score: 75, timestamp });\n *   // → '{\"vaultsfyi\":{\"score\":80,\"risk_score\":75,\"timestamp\":...}}'\n *\n *   // vaultsfyi/policy.js (error path)\n *   return wrapOutput(\"vaultsfyi\", { error: String(e) });\n *   // → '{\"vaultsfyi\":{\"error\":\"...\"}}'  — namespaced, won't collide\n */\nexport function wrapOutput(packId: string, valueOrError: unknown): string {\n\treturn JSON.stringify({ [packId]: valueOrError });\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACAA,kBAA4C;AAa5C,SAAS,aAAa,OAAyB;AAC9C,MAAI,MAAM,QAAQ,KAAK,EAAG,QAAO,MAAM,IAAI,YAAY;AACvD,MAAI,SAAS,OAAO,UAAU,UAAU;AACvC,UAAM,MAAM;AACZ,UAAM,SAAkC,CAAC;AACzC,eAAW,OAAO,OAAO,KAAK,GAAG,EAAE,KAAK,GAAG;AAC1C,aAAO,GAAG,IAAI,aAAa,IAAI,GAAG,CAAC;AAAA,IACpC;AACA,WAAO;AAAA,EACR;AACA,SAAO;AACR;AAQO,SAAS,mBACf,MACA,QACM;AACN,QAAM,YAAY,KAAK,aAAa,MAAM,MAAM;AAChD,aAAO,mBAAM,KAAK,UAAU,aAAa,SAAS,CAAC,CAAC;AACrD;AAYO,SAAS,mBACf,MACA,SACI;AACJ,QAAM,OAAO,IAAI,YAAY,SAAS,EAAE,OAAO,KAAK,CAAC,EAAE,WAAO,wBAAW,OAAO,CAAC;AACjF,SAAO,KAAK,aAAa,MAAM,KAAK,MAAM,IAAI,CAAC;AAChD;;;ACmDO,SAAS,cACf,MACA,SACA,KACa;AACb,QAAM,SAAS,KAAK,YAAY,OAAO;AACvC,MAAI,CAAC,QAAQ;AACZ,UAAM,kBAAkB,OAAO,KAAK,KAAK,WAAW,EAAE,KAAK,EAAE,KAAK,IAAI,KAAK;AAC3E,UAAM,IAAI;AAAA,MACT,UAAU,KAAK,EAAE,+BAA+B,OAAO,gBAAgB,eAAe;AAAA,MACtF,KAAK;AAAA,MACL;AAAA,MACA,OAAO,KAAK,KAAK,WAAW;AAAA,IAC7B;AAAA,EACD;AACA,QAAM,aAAa,OAAO,GAAG;AAC7B,MAAI,CAAC,YAAY;AAChB,UAAM,gBAAgB,OAAO,KAAK,MAAM,EAAE,KAAK,EAAE,KAAK,IAAI,KAAK;AAC/D,UAAM,IAAI;AAAA,MACT,UAAU,KAAK,EAAE,2BAA2B,OAAO,oBAAoB,GAAG,oCAAoC,aAAa;AAAA,MAC3H,KAAK;AAAA,MACL;AAAA,MACA;AAAA,MACA,OAAO,KAAK,MAAM;AAAA,IACnB;AAAA,EACD;AACA,SAAO;AACR;AAQO,IAAM,wBAAN,cAAoC,MAAM;AAAA,EAEhD,YACC,SACS,QACA,SACA,mBACR;AACD,UAAM,OAAO;AAJJ;AACA;AACA;AAAA,EAGV;AAAA,EALU;AAAA,EACA;AAAA,EACA;AAAA,EALQ,OAAO;AAS1B;AASO,IAAM,sBAAN,cAAkC,MAAM;AAAA,EAE9C,YACC,SACS,QACA,SACA,KACA,eACR;AACD,UAAM,OAAO;AALJ;AACA;AACA;AACA;AAAA,EAGV;AAAA,EANU;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EANQ,OAAO;AAU1B;;;AC/GO,SAAS,WAAW,QAAgB,cAA+B;AACzE,SAAO,KAAK,UAAU,EAAE,CAAC,MAAM,GAAG,aAAa,CAAC;AACjD;","names":[]}

package/dist/index.d.cts

@@ -10,6 +10,14 @@ import { z } from 'zod';
  * same type they'd see at runtime.
  */
 type ChainId = string;
+/**
+ * Newton AVS environment. Mirrors `@newton-xyz/newton-shield-sdk`'s
+ * `GatewayEnv`. The same `(chainId)` may have separate deployments under
+ * each env — distinct gateways, distinct TaskManager addresses, distinct
+ * registered operators. A pack policy deployed under `stagef` will not be
+ * evaluated by `prod` operators and vice versa.
+ */
+type GatewayEnv = "stagef" | "prod";
 /**
  * On-chain address pair + content addressing for a deployed Newton policy
  * on a given chain. Mirrors the per-pack-per-chain entries in the upstream
@@ -127,13 +135,14 @@ interface PrepareQueryResult<TWasmArgs> {
  *                       via its own `prepareQuery` signature; the shared
  *                       interface keeps it `unknown` so the SDK can
  *                       forward it verbatim.
- * - `deployments`    — `chainId → Deployment` map sliced from the upstream
- *                       `deployments.json` for this pack only. Typed as
- *                       `Partial<Record<ChainId, Deployment>>` so callers
- *                       must handle `undefined` for unsupported chains
- *                       rather than silently reading `.policy` off nothing.
- *                       Use `getDeployment(pack, chainId)` from this package
- *                       for the safe lookup.
+ * - `deployments`    — `chainId → env → Deployment` map sliced from the
+ *                       upstream `deployments.json` for this pack only.
+ *                       Typed as `Partial<Record<ChainId, Partial<Record<GatewayEnv,
+ *                       Deployment>>>>` so callers must handle `undefined`
+ *                       both for unsupported chains and for chains where
+ *                       only one env has been deployed. Use
+ *                       `getDeployment(pack, chainId, env)` from this
+ *                       package for the safe lookup.
  * - `metadata`       — static identity from the pack's `policy_metadata.json`.
  */
 interface PolicyPack<TParams, TWasmArgs, TSecrets> {
@@ -142,7 +151,7 @@ interface PolicyPack<TParams, TWasmArgs, TSecrets> {
     readonly wasmArgsSchema: z.ZodType<TWasmArgs>;
     readonly secretsSchema: z.ZodType<TSecrets>;
     prepareQuery?(args: PrepareQueryArgs, options?: unknown): Promise<PrepareQueryResult<TWasmArgs>>;
-    readonly deployments: Readonly<Partial<Record<ChainId, Deployment>>>;
+    readonly deployments: Readonly<Partial<Record<ChainId, Readonly<Partial<Record<GatewayEnv, Deployment>>>>>>;
     readonly metadata: {
         readonly name: string;
         readonly version: string;
@@ -152,13 +161,14 @@ interface PolicyPack<TParams, TWasmArgs, TSecrets> {
     };
 }
 /**
- * Safe lookup helper. Returns the `Deployment` for `chainId` if the pack is
- * deployed on that chain, or throws `UnsupportedChainError` with the list of
- * chain ids the pack is known to support. Use this at every SDK callsite that
- * reads `pack.deployments[chainId]` so unsupported-chain failures surface
+ * Safe lookup helper. Returns the `Deployment` for `(chainId, env)` if the
+ * pack is deployed there, or throws — `UnsupportedChainError` if the chain
+ * itself has no entry, `UnsupportedEnvError` if the chain has at least one
+ * env but not the one requested. Use this at every SDK callsite that reads
+ * `pack.deployments[chainId][env]` so unsupported-cell failures surface
  * immediately rather than as `undefined.policy` further down.
  */
-declare function getDeployment<TParams, TWasmArgs, TSecrets>(pack: PolicyPack<TParams, TWasmArgs, TSecrets>, chainId: ChainId): Deployment;
+declare function getDeployment<TParams, TWasmArgs, TSecrets>(pack: PolicyPack<TParams, TWasmArgs, TSecrets>, chainId: ChainId, env: GatewayEnv): Deployment;
 /**
  * Thrown by `getDeployment` when a pack is asked for a chain it isn't
  * deployed on. SDK consumers can catch this specifically to surface a
@@ -172,5 +182,83 @@ declare class UnsupportedChainError extends Error {
     readonly name = "UnsupportedChainError";
     constructor(message: string, packId: string, chainId: ChainId, supportedChainIds: ReadonlyArray<ChainId>);
 }
+/**
+ * Thrown by `getDeployment` when a pack is deployed on the requested chain
+ * but not in the requested env. Distinct from `UnsupportedChainError`
+ * because the recovery is different: the curator either picks a different
+ * env (typo / wrong gateway) or the AVS team needs to deploy the pack into
+ * the requested env.
+ */
+declare class UnsupportedEnvError extends Error {
+    readonly packId: string;
+    readonly chainId: ChainId;
+    readonly env: GatewayEnv;
+    readonly supportedEnvs: ReadonlyArray<GatewayEnv>;
+    readonly name = "UnsupportedEnvError";
+    constructor(message: string, packId: string, chainId: ChainId, env: GatewayEnv, supportedEnvs: ReadonlyArray<GatewayEnv>);
+}
+
+/**
+ * Wrap a pack's WASM oracle output under its top-level `PACK_ID` key. Every
+ * `policy.js` MUST call this on every return path (success AND error) so the
+ * AVS-side `merge_jsons` (`newton-prover-avs/crates/operator/src/simulation.rs:296`)
+ * composes cleanly across packs without top-level key collisions.
+ *
+ * The merge is shallow + last-wins: pre-namespacing, vaultsfyi's
+ * `risk_score: number` would silently clobber chainalysis's `risk_score: string`
+ * under composition. After namespacing, every pack's output sits under its
+ * unique `PACK_ID` key and merges into a single `data.wasm` blob that
+ * composite Rego can reference unambiguously as `data.wasm.<pack-id>.<field>`.
+ *
+ * The contract this helper locks:
+ * - **Output is JSON-stringified** so `policy.js` can `return wrapOutput(...)`
+ *   directly. The AVS host parses every PolicyData WASM's stdout as UTF-8
+ *   JSON before merging.
+ * - **Top-level keys are exactly `[packId]`** — assertable in
+ *   `<pack>/wrapping_test.rego` with a fixture `data.wasm.<pack-id>` shape.
+ *   To be enforced at PR time by an AST-lint CI guard (Phase 0 § Stream C,
+ *   shipped in a separate PR) that flags any raw `return JSON.stringify(...)`
+ *   callsite in `<pack>/policy.js` not routed through this helper.
+ * - **`undefined` and other JSON-nonrepresentable payloads** (functions,
+ *   symbols) cause `JSON.stringify` to omit the key, returning `'{}'` rather
+ *   than `{ [packId]: undefined }`. The AVS contract doesn't admit such
+ *   payloads — every `policy.js` returns either a structured success object
+ *   or `{ error: "..." }` — so this is documented as out-of-contract input
+ *   rather than guarded at runtime. The Stream C AST-lint catches the
+ *   shape upstream.
+ * - **Both success and error paths route through here.** Returning
+ *   `{"error": "..."}` directly from `policy.js` would collide across packs in
+ *   `merge_jsons` (every pack's error key would land at the top level and
+ *   the last one wins). Wrapping the error under `[packId]` keeps per-pack
+ *   error semantics (composite Rego can selectively deny on
+ *   `data.wasm.<pack-id>.error`).
+ *
+ * @param packId The pack's stable id, matching the `<name>OracleModule.id`
+ *               that ships in Phase 1 and the `KNOWN_PACK_IDS` registry in
+ *               Phase 2. Convention: lowercase single-word, matches the
+ *               pack's folder name (e.g. `"vaultsfyi"`, `"chainalysis"`).
+ * @param valueOrError The pack's output payload — `{ score, risk_score, ... }`
+ *                     for success, `{ error: "..." }` for failure paths.
+ *                     Untyped at this layer because each pack's WASM emits
+ *                     its own shape and the `PolicyPack` /  `OracleModule`
+ *                     interfaces today carry input schemas (`paramsSchema`,
+ *                     `wasmArgsSchema`, `secretsSchema`) but no on-chain
+ *                     output schema — composite Rego references fields by
+ *                     name (`data.wasm.<pack-id>.<field>`) and trusts the
+ *                     pack-specific WASM bindings paired to each
+ *                     `wasm_cid` in the manifest (Phase 1.5).
+ * @returns JSON-stringified `{ [packId]: valueOrError }` ready to drop into
+ *          a `policy.js` `return` statement.
+ *
+ * @example
+ *   // vaultsfyi/policy.js (success path)
+ *   return wrapOutput("vaultsfyi", { score: 80, risk_score: 75, timestamp });
+ *   // → '{"vaultsfyi":{"score":80,"risk_score":75,"timestamp":...}}'
+ *
+ *   // vaultsfyi/policy.js (error path)
+ *   return wrapOutput("vaultsfyi", { error: String(e) });
+ *   // → '{"vaultsfyi":{"error":"..."}}'  — namespaced, won't collide
+ */
+declare function wrapOutput(packId: string, valueOrError: unknown): string;
 
-export { type ChainId, type Deployment, type PolicyPack, type PrepareQueryArgs, type PrepareQueryResult, UnsupportedChainError, decodePolicyParams, encodePolicyParams, getDeployment };
+export { type ChainId, type Deployment, type GatewayEnv, type PolicyPack, type PrepareQueryArgs, type PrepareQueryResult, UnsupportedChainError, UnsupportedEnvError, decodePolicyParams, encodePolicyParams, getDeployment, wrapOutput };

package/dist/index.d.ts

@@ -10,6 +10,14 @@ import { z } from 'zod';
  * same type they'd see at runtime.
  */
 type ChainId = string;
+/**
+ * Newton AVS environment. Mirrors `@newton-xyz/newton-shield-sdk`'s
+ * `GatewayEnv`. The same `(chainId)` may have separate deployments under
+ * each env — distinct gateways, distinct TaskManager addresses, distinct
+ * registered operators. A pack policy deployed under `stagef` will not be
+ * evaluated by `prod` operators and vice versa.
+ */
+type GatewayEnv = "stagef" | "prod";
 /**
  * On-chain address pair + content addressing for a deployed Newton policy
  * on a given chain. Mirrors the per-pack-per-chain entries in the upstream
@@ -127,13 +135,14 @@ interface PrepareQueryResult<TWasmArgs> {
  *                       via its own `prepareQuery` signature; the shared
  *                       interface keeps it `unknown` so the SDK can
  *                       forward it verbatim.
- * - `deployments`    — `chainId → Deployment` map sliced from the upstream
- *                       `deployments.json` for this pack only. Typed as
- *                       `Partial<Record<ChainId, Deployment>>` so callers
- *                       must handle `undefined` for unsupported chains
- *                       rather than silently reading `.policy` off nothing.
- *                       Use `getDeployment(pack, chainId)` from this package
- *                       for the safe lookup.
+ * - `deployments`    — `chainId → env → Deployment` map sliced from the
+ *                       upstream `deployments.json` for this pack only.
+ *                       Typed as `Partial<Record<ChainId, Partial<Record<GatewayEnv,
+ *                       Deployment>>>>` so callers must handle `undefined`
+ *                       both for unsupported chains and for chains where
+ *                       only one env has been deployed. Use
+ *                       `getDeployment(pack, chainId, env)` from this
+ *                       package for the safe lookup.
  * - `metadata`       — static identity from the pack's `policy_metadata.json`.
  */
 interface PolicyPack<TParams, TWasmArgs, TSecrets> {
@@ -142,7 +151,7 @@ interface PolicyPack<TParams, TWasmArgs, TSecrets> {
     readonly wasmArgsSchema: z.ZodType<TWasmArgs>;
     readonly secretsSchema: z.ZodType<TSecrets>;
     prepareQuery?(args: PrepareQueryArgs, options?: unknown): Promise<PrepareQueryResult<TWasmArgs>>;
-    readonly deployments: Readonly<Partial<Record<ChainId, Deployment>>>;
+    readonly deployments: Readonly<Partial<Record<ChainId, Readonly<Partial<Record<GatewayEnv, Deployment>>>>>>;
     readonly metadata: {
         readonly name: string;
         readonly version: string;
@@ -152,13 +161,14 @@ interface PolicyPack<TParams, TWasmArgs, TSecrets> {
     };
 }
 /**
- * Safe lookup helper. Returns the `Deployment` for `chainId` if the pack is
- * deployed on that chain, or throws `UnsupportedChainError` with the list of
- * chain ids the pack is known to support. Use this at every SDK callsite that
- * reads `pack.deployments[chainId]` so unsupported-chain failures surface
+ * Safe lookup helper. Returns the `Deployment` for `(chainId, env)` if the
+ * pack is deployed there, or throws — `UnsupportedChainError` if the chain
+ * itself has no entry, `UnsupportedEnvError` if the chain has at least one
+ * env but not the one requested. Use this at every SDK callsite that reads
+ * `pack.deployments[chainId][env]` so unsupported-cell failures surface
  * immediately rather than as `undefined.policy` further down.
  */
-declare function getDeployment<TParams, TWasmArgs, TSecrets>(pack: PolicyPack<TParams, TWasmArgs, TSecrets>, chainId: ChainId): Deployment;
+declare function getDeployment<TParams, TWasmArgs, TSecrets>(pack: PolicyPack<TParams, TWasmArgs, TSecrets>, chainId: ChainId, env: GatewayEnv): Deployment;
 /**
  * Thrown by `getDeployment` when a pack is asked for a chain it isn't
  * deployed on. SDK consumers can catch this specifically to surface a
@@ -172,5 +182,83 @@ declare class UnsupportedChainError extends Error {
     readonly name = "UnsupportedChainError";
     constructor(message: string, packId: string, chainId: ChainId, supportedChainIds: ReadonlyArray<ChainId>);
 }
+/**
+ * Thrown by `getDeployment` when a pack is deployed on the requested chain
+ * but not in the requested env. Distinct from `UnsupportedChainError`
+ * because the recovery is different: the curator either picks a different
+ * env (typo / wrong gateway) or the AVS team needs to deploy the pack into
+ * the requested env.
+ */
+declare class UnsupportedEnvError extends Error {
+    readonly packId: string;
+    readonly chainId: ChainId;
+    readonly env: GatewayEnv;
+    readonly supportedEnvs: ReadonlyArray<GatewayEnv>;
+    readonly name = "UnsupportedEnvError";
+    constructor(message: string, packId: string, chainId: ChainId, env: GatewayEnv, supportedEnvs: ReadonlyArray<GatewayEnv>);
+}
+
+/**
+ * Wrap a pack's WASM oracle output under its top-level `PACK_ID` key. Every
+ * `policy.js` MUST call this on every return path (success AND error) so the
+ * AVS-side `merge_jsons` (`newton-prover-avs/crates/operator/src/simulation.rs:296`)
+ * composes cleanly across packs without top-level key collisions.
+ *
+ * The merge is shallow + last-wins: pre-namespacing, vaultsfyi's
+ * `risk_score: number` would silently clobber chainalysis's `risk_score: string`
+ * under composition. After namespacing, every pack's output sits under its
+ * unique `PACK_ID` key and merges into a single `data.wasm` blob that
+ * composite Rego can reference unambiguously as `data.wasm.<pack-id>.<field>`.
+ *
+ * The contract this helper locks:
+ * - **Output is JSON-stringified** so `policy.js` can `return wrapOutput(...)`
+ *   directly. The AVS host parses every PolicyData WASM's stdout as UTF-8
+ *   JSON before merging.
+ * - **Top-level keys are exactly `[packId]`** — assertable in
+ *   `<pack>/wrapping_test.rego` with a fixture `data.wasm.<pack-id>` shape.
+ *   To be enforced at PR time by an AST-lint CI guard (Phase 0 § Stream C,
+ *   shipped in a separate PR) that flags any raw `return JSON.stringify(...)`
+ *   callsite in `<pack>/policy.js` not routed through this helper.
+ * - **`undefined` and other JSON-nonrepresentable payloads** (functions,
+ *   symbols) cause `JSON.stringify` to omit the key, returning `'{}'` rather
+ *   than `{ [packId]: undefined }`. The AVS contract doesn't admit such
+ *   payloads — every `policy.js` returns either a structured success object
+ *   or `{ error: "..." }` — so this is documented as out-of-contract input
+ *   rather than guarded at runtime. The Stream C AST-lint catches the
+ *   shape upstream.
+ * - **Both success and error paths route through here.** Returning
+ *   `{"error": "..."}` directly from `policy.js` would collide across packs in
+ *   `merge_jsons` (every pack's error key would land at the top level and
+ *   the last one wins). Wrapping the error under `[packId]` keeps per-pack
+ *   error semantics (composite Rego can selectively deny on
+ *   `data.wasm.<pack-id>.error`).
+ *
+ * @param packId The pack's stable id, matching the `<name>OracleModule.id`
+ *               that ships in Phase 1 and the `KNOWN_PACK_IDS` registry in
+ *               Phase 2. Convention: lowercase single-word, matches the
+ *               pack's folder name (e.g. `"vaultsfyi"`, `"chainalysis"`).
+ * @param valueOrError The pack's output payload — `{ score, risk_score, ... }`
+ *                     for success, `{ error: "..." }` for failure paths.
+ *                     Untyped at this layer because each pack's WASM emits
+ *                     its own shape and the `PolicyPack` /  `OracleModule`
+ *                     interfaces today carry input schemas (`paramsSchema`,
+ *                     `wasmArgsSchema`, `secretsSchema`) but no on-chain
+ *                     output schema — composite Rego references fields by
+ *                     name (`data.wasm.<pack-id>.<field>`) and trusts the
+ *                     pack-specific WASM bindings paired to each
+ *                     `wasm_cid` in the manifest (Phase 1.5).
+ * @returns JSON-stringified `{ [packId]: valueOrError }` ready to drop into
+ *          a `policy.js` `return` statement.
+ *
+ * @example
+ *   // vaultsfyi/policy.js (success path)
+ *   return wrapOutput("vaultsfyi", { score: 80, risk_score: 75, timestamp });
+ *   // → '{"vaultsfyi":{"score":80,"risk_score":75,"timestamp":...}}'
+ *
+ *   // vaultsfyi/policy.js (error path)
+ *   return wrapOutput("vaultsfyi", { error: String(e) });
+ *   // → '{"vaultsfyi":{"error":"..."}}'  — namespaced, won't collide
+ */
+declare function wrapOutput(packId: string, valueOrError: unknown): string;
 
-export { type ChainId, type Deployment, type PolicyPack, type PrepareQueryArgs, type PrepareQueryResult, UnsupportedChainError, decodePolicyParams, encodePolicyParams, getDeployment };
+export { type ChainId, type Deployment, type GatewayEnv, type PolicyPack, type PrepareQueryArgs, type PrepareQueryResult, UnsupportedChainError, UnsupportedEnvError, decodePolicyParams, encodePolicyParams, getDeployment, wrapOutput };

package/dist/index.js

@@ -22,17 +22,28 @@ function decodePolicyParams(pack, encoded) {
 }
 
 // src/pack.ts
-function getDeployment(pack, chainId) {
-  const deployment = pack.deployments[chainId];
-  if (!deployment) {
-    const supported = Object.keys(pack.deployments).sort().join(", ") || "(none)";
+function getDeployment(pack, chainId, env) {
+  const perEnv = pack.deployments[chainId];
+  if (!perEnv) {
+    const supportedChains = Object.keys(pack.deployments).sort().join(", ") || "(none)";
     throw new UnsupportedChainError(
-      `Pack \`${pack.id}\` is not deployed on chain ${chainId}. Supported: ${supported}.`,
+      `Pack \`${pack.id}\` is not deployed on chain ${chainId}. Supported: ${supportedChains}.`,
       pack.id,
       chainId,
       Object.keys(pack.deployments)
     );
   }
+  const deployment = perEnv[env];
+  if (!deployment) {
+    const supportedEnvs = Object.keys(perEnv).sort().join(", ") || "(none)";
+    throw new UnsupportedEnvError(
+      `Pack \`${pack.id}\` is deployed on chain ${chainId} but not in env "${env}". Supported envs on this chain: ${supportedEnvs}.`,
+      pack.id,
+      chainId,
+      env,
+      Object.keys(perEnv)
+    );
+  }
   return deployment;
 }
 var UnsupportedChainError = class extends Error {
@@ -47,10 +58,31 @@ var UnsupportedChainError = class extends Error {
   supportedChainIds;
   name = "UnsupportedChainError";
 };
+var UnsupportedEnvError = class extends Error {
+  constructor(message, packId, chainId, env, supportedEnvs) {
+    super(message);
+    this.packId = packId;
+    this.chainId = chainId;
+    this.env = env;
+    this.supportedEnvs = supportedEnvs;
+  }
+  packId;
+  chainId;
+  env;
+  supportedEnvs;
+  name = "UnsupportedEnvError";
+};
+
+// src/wrap.ts
+function wrapOutput(packId, valueOrError) {
+  return JSON.stringify({ [packId]: valueOrError });
+}
 export {
   UnsupportedChainError,
+  UnsupportedEnvError,
   decodePolicyParams,
   encodePolicyParams,
-  getDeployment
+  getDeployment,
+  wrapOutput
 };
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/encoding.ts","../src/pack.ts"],"sourcesContent":["import { type Hex, hexToBytes, toHex } from \"viem\";\nimport type { z } from \"zod\";\n\n/**\n * The on-chain `policyParams` byte format is a Newton-protocol invariant. The\n * AVS host reads it as `String::from_utf8 → serde_json::from_str` (see\n * `newton-prover-avs/crates/core/src/common/task.rs:402-408`); the SDK must\n * therefore write **UTF-8 JSON**. Keys are sorted recursively so two\n * semantically-equal params objects always produce byte-identical output —\n * the SDK's `verifyPolicyBinding` does a byte-equality check against\n * `getPolicyConfig().policyParams`, which would otherwise depend on JS\n * `JSON.stringify` insertion order.\n */\nfunction sortKeysDeep(value: unknown): unknown {\n\tif (Array.isArray(value)) return value.map(sortKeysDeep);\n\tif (value && typeof value === \"object\") {\n\t\tconst obj = value as Record<string, unknown>;\n\t\tconst sorted: Record<string, unknown> = {};\n\t\tfor (const key of Object.keys(obj).sort()) {\n\t\t\tsorted[key] = sortKeysDeep(obj[key]);\n\t\t}\n\t\treturn sorted;\n\t}\n\treturn value;\n}\n\n/**\n * Encode a pack's params for on-chain storage. Validates against the pack's\n * `paramsSchema` so a curator typo throws here rather than silently writing\n * AVS-rejecting bytes. Returns `Hex` so it drops directly into a viem\n * `setPolicy(bytes)` call.\n */\nexport function encodePolicyParams<T>(\n\tpack: { readonly paramsSchema: z.ZodType<T> },\n\tparams: T,\n): Hex {\n\tconst validated = pack.paramsSchema.parse(params);\n\treturn toHex(JSON.stringify(sortKeysDeep(validated)));\n}\n\n/**\n * Decode `policyParams` bytes read from `getPolicyConfig().policyParams` back\n * into the pack's typed params shape. Revalidates against `paramsSchema` so a\n * stale or corrupted on-chain blob throws at the SDK boundary rather than\n * yielding a partially-valid object that crashes deeper in the call.\n *\n * `fatal: true` matches AVS-side `String::from_utf8` behavior — invalid UTF-8\n * throws here rather than silently becoming U+FFFD and diverging from a path\n * the AVS would reject.\n */\nexport function decodePolicyParams<T>(\n\tpack: { readonly paramsSchema: z.ZodType<T> },\n\tencoded: Hex,\n): T {\n\tconst json = new TextDecoder(\"utf-8\", { fatal: true }).decode(hexToBytes(encoded));\n\treturn pack.paramsSchema.parse(JSON.parse(json));\n}\n","import type { Address, Hex, PublicClient } from \"viem\";\nimport type { z } from \"zod\";\nimport type { ChainId, Deployment } from \"./deployment\";\n\n/**\n * Inputs that a pack's `prepareQuery` reads at intent-build time.\n *\n * The Shield SDK passes a viem `PublicClient` (so the pack can read on-chain\n * state) and the vault address the curator is acting on. Packs that don't\n * need on-chain state can ignore both — `prepareQuery` is optional.\n */\nexport interface PrepareQueryArgs {\n\treadonly publicClient: PublicClient;\n\treadonly vault: Address;\n}\n\n/**\n * `wasmArgs` payload (untyped at this layer; each pack narrows it via its own\n * `WasmArgsSchema`) plus an optional pre-image hash for binding the AVS-side\n * evaluation to a specific on-chain state. VaultsFYI uses this to bind the\n * evaluation to a `keccak(supplyQueue)` snapshot so the policy can reject\n * attestations whose underlying allocation has shifted between intent build\n * and on-chain submission.\n */\nexport interface PrepareQueryResult<TWasmArgs> {\n\treadonly wasmArgs: TWasmArgs;\n\treadonly freshnessHash?: Hex;\n}\n\n/**\n * Canonical typed contract every published `@newton-xyz/policy-pack-<name>`\n * package implements. `@newton-xyz/newton-shield-sdk`'s `createShield(...)`\n * accepts `PolicyPack<P, W, S>` as the curator's pack argument.\n *\n * Type parameters:\n * - `TParams`   — the shape stored on-chain in `NewtonPolicyData.policyParams`\n *                  (e.g. risk envelope thresholds for VaultsFYI).\n * - `TWasmArgs` — the shape passed to the policy's WASM oracle at evaluation\n *                  time (e.g. `{ vault, network, lastKnownAllocationHash }`).\n * - `TSecrets`  — required API credentials uploaded before any run/sim.\n *\n * The fields:\n * - `id`             — stable identifier of the form `<pack>/<purpose>/<version>`,\n *                       e.g. `vaultsfyi/risk-envelope/v1`. Used for telemetry\n *                       and for cross-referencing the `policy_metadata.json`.\n * - `paramsSchema`   — zod schema enforced at curator setup time when the\n *                       pack is bound to a `NewtonPolicyData`.\n * - `wasmArgsSchema` — zod schema enforced per call when the SDK builds the\n *                       intent and forwards `wasmArgs` to the gateway.\n * - `secretsSchema`  — zod schema enforced at upload-time. Validates the\n *                       shape of the secrets the operator stores in the AVS.\n *\n * Encoding is *not* a per-pack concern. The on-chain `policyParams` byte\n * format is a Newton-protocol invariant — UTF-8 JSON, sorted keys —\n * implemented once in this package as `encodePolicyParams` /\n * `decodePolicyParams`. See `./encoding.ts`. Earlier shapes of this\n * interface required each pack to ship its own `encodeParams` /\n * `decodeParams`; that structurally invited drift (vaultsfyi@0.2.0 shipped\n * ABI bytes against an AVS that reads `serde_json::from_str`, breaking\n * every call). The interface now leaves byte-format to the protocol.\n *\n * - `prepareQuery`   — optional. When present, the SDK invokes it on every\n *                       call to gather chain-state freshness inputs. Packs\n *                       that don't need this (e.g. KYC-only packs) omit it.\n *                       The optional second `options` argument is a\n *                       pack-typed escape hatch for per-call overrides —\n *                       e.g. VaultsFYI's `previousAllocationHash` for\n *                       freshness binding. Each concrete pack narrows it\n *                       via its own `prepareQuery` signature; the shared\n *                       interface keeps it `unknown` so the SDK can\n *                       forward it verbatim.\n * - `deployments`    — `chainId → Deployment` map sliced from the upstream\n *                       `deployments.json` for this pack only. Typed as\n *                       `Partial<Record<ChainId, Deployment>>` so callers\n *                       must handle `undefined` for unsupported chains\n *                       rather than silently reading `.policy` off nothing.\n *                       Use `getDeployment(pack, chainId)` from this package\n *                       for the safe lookup.\n * - `metadata`       — static identity from the pack's `policy_metadata.json`.\n */\nexport interface PolicyPack<TParams, TWasmArgs, TSecrets> {\n\treadonly id: string;\n\treadonly paramsSchema: z.ZodType<TParams>;\n\treadonly wasmArgsSchema: z.ZodType<TWasmArgs>;\n\treadonly secretsSchema: z.ZodType<TSecrets>;\n\tprepareQuery?(args: PrepareQueryArgs, options?: unknown): Promise<PrepareQueryResult<TWasmArgs>>;\n\treadonly deployments: Readonly<Partial<Record<ChainId, Deployment>>>;\n\treadonly metadata: {\n\t\treadonly name: string;\n\t\treadonly version: string;\n\t\treadonly description: string;\n\t\treadonly author?: string;\n\t\treadonly link?: string;\n\t};\n}\n\n/**\n * Safe lookup helper. Returns the `Deployment` for `chainId` if the pack is\n * deployed on that chain, or throws `UnsupportedChainError` with the list of\n * chain ids the pack is known to support. Use this at every SDK callsite that\n * reads `pack.deployments[chainId]` so unsupported-chain failures surface\n * immediately rather than as `undefined.policy` further down.\n */\nexport function getDeployment<TParams, TWasmArgs, TSecrets>(\n\tpack: PolicyPack<TParams, TWasmArgs, TSecrets>,\n\tchainId: ChainId,\n): Deployment {\n\tconst deployment = pack.deployments[chainId];\n\tif (!deployment) {\n\t\tconst supported = Object.keys(pack.deployments).sort().join(\", \") || \"(none)\";\n\t\tthrow new UnsupportedChainError(\n\t\t\t`Pack \\`${pack.id}\\` is not deployed on chain ${chainId}. Supported: ${supported}.`,\n\t\t\tpack.id,\n\t\t\tchainId,\n\t\t\tObject.keys(pack.deployments),\n\t\t);\n\t}\n\treturn deployment;\n}\n\n/**\n * Thrown by `getDeployment` when a pack is asked for a chain it isn't\n * deployed on. SDK consumers can catch this specifically to surface a\n * curator-friendly error rather than a `TypeError: Cannot read property\n * 'policy' of undefined`.\n */\nexport class UnsupportedChainError extends Error {\n\toverride readonly name = \"UnsupportedChainError\";\n\tconstructor(\n\t\tmessage: string,\n\t\treadonly packId: string,\n\t\treadonly chainId: ChainId,\n\t\treadonly supportedChainIds: ReadonlyArray<ChainId>,\n\t) {\n\t\tsuper(message);\n\t}\n}\n"],"mappings":";AAAA,SAAmB,YAAY,aAAa;AAa5C,SAAS,aAAa,OAAyB;AAC9C,MAAI,MAAM,QAAQ,KAAK,EAAG,QAAO,MAAM,IAAI,YAAY;AACvD,MAAI,SAAS,OAAO,UAAU,UAAU;AACvC,UAAM,MAAM;AACZ,UAAM,SAAkC,CAAC;AACzC,eAAW,OAAO,OAAO,KAAK,GAAG,EAAE,KAAK,GAAG;AAC1C,aAAO,GAAG,IAAI,aAAa,IAAI,GAAG,CAAC;AAAA,IACpC;AACA,WAAO;AAAA,EACR;AACA,SAAO;AACR;AAQO,SAAS,mBACf,MACA,QACM;AACN,QAAM,YAAY,KAAK,aAAa,MAAM,MAAM;AAChD,SAAO,MAAM,KAAK,UAAU,aAAa,SAAS,CAAC,CAAC;AACrD;AAYO,SAAS,mBACf,MACA,SACI;AACJ,QAAM,OAAO,IAAI,YAAY,SAAS,EAAE,OAAO,KAAK,CAAC,EAAE,OAAO,WAAW,OAAO,CAAC;AACjF,SAAO,KAAK,aAAa,MAAM,KAAK,MAAM,IAAI,CAAC;AAChD;;;AC+CO,SAAS,cACf,MACA,SACa;AACb,QAAM,aAAa,KAAK,YAAY,OAAO;AAC3C,MAAI,CAAC,YAAY;AAChB,UAAM,YAAY,OAAO,KAAK,KAAK,WAAW,EAAE,KAAK,EAAE,KAAK,IAAI,KAAK;AACrE,UAAM,IAAI;AAAA,MACT,UAAU,KAAK,EAAE,+BAA+B,OAAO,gBAAgB,SAAS;AAAA,MAChF,KAAK;AAAA,MACL;AAAA,MACA,OAAO,KAAK,KAAK,WAAW;AAAA,IAC7B;AAAA,EACD;AACA,SAAO;AACR;AAQO,IAAM,wBAAN,cAAoC,MAAM;AAAA,EAEhD,YACC,SACS,QACA,SACA,mBACR;AACD,UAAM,OAAO;AAJJ;AACA;AACA;AAAA,EAGV;AAAA,EALU;AAAA,EACA;AAAA,EACA;AAAA,EALQ,OAAO;AAS1B;","names":[]}
+{"version":3,"sources":["../src/encoding.ts","../src/pack.ts","../src/wrap.ts"],"sourcesContent":["import { type Hex, hexToBytes, toHex } from \"viem\";\nimport type { z } from \"zod\";\n\n/**\n * The on-chain `policyParams` byte format is a Newton-protocol invariant. The\n * AVS host reads it as `String::from_utf8 → serde_json::from_str` (see\n * `newton-prover-avs/crates/core/src/common/task.rs:402-408`); the SDK must\n * therefore write **UTF-8 JSON**. Keys are sorted recursively so two\n * semantically-equal params objects always produce byte-identical output —\n * the SDK's `verifyPolicyBinding` does a byte-equality check against\n * `getPolicyConfig().policyParams`, which would otherwise depend on JS\n * `JSON.stringify` insertion order.\n */\nfunction sortKeysDeep(value: unknown): unknown {\n\tif (Array.isArray(value)) return value.map(sortKeysDeep);\n\tif (value && typeof value === \"object\") {\n\t\tconst obj = value as Record<string, unknown>;\n\t\tconst sorted: Record<string, unknown> = {};\n\t\tfor (const key of Object.keys(obj).sort()) {\n\t\t\tsorted[key] = sortKeysDeep(obj[key]);\n\t\t}\n\t\treturn sorted;\n\t}\n\treturn value;\n}\n\n/**\n * Encode a pack's params for on-chain storage. Validates against the pack's\n * `paramsSchema` so a curator typo throws here rather than silently writing\n * AVS-rejecting bytes. Returns `Hex` so it drops directly into a viem\n * `setPolicy(bytes)` call.\n */\nexport function encodePolicyParams<T>(\n\tpack: { readonly paramsSchema: z.ZodType<T> },\n\tparams: T,\n): Hex {\n\tconst validated = pack.paramsSchema.parse(params);\n\treturn toHex(JSON.stringify(sortKeysDeep(validated)));\n}\n\n/**\n * Decode `policyParams` bytes read from `getPolicyConfig().policyParams` back\n * into the pack's typed params shape. Revalidates against `paramsSchema` so a\n * stale or corrupted on-chain blob throws at the SDK boundary rather than\n * yielding a partially-valid object that crashes deeper in the call.\n *\n * `fatal: true` matches AVS-side `String::from_utf8` behavior — invalid UTF-8\n * throws here rather than silently becoming U+FFFD and diverging from a path\n * the AVS would reject.\n */\nexport function decodePolicyParams<T>(\n\tpack: { readonly paramsSchema: z.ZodType<T> },\n\tencoded: Hex,\n): T {\n\tconst json = new TextDecoder(\"utf-8\", { fatal: true }).decode(hexToBytes(encoded));\n\treturn pack.paramsSchema.parse(JSON.parse(json));\n}\n","import type { Address, Hex, PublicClient } from \"viem\";\nimport type { z } from \"zod\";\nimport type { ChainId, Deployment, GatewayEnv } from \"./deployment\";\n\n/**\n * Inputs that a pack's `prepareQuery` reads at intent-build time.\n *\n * The Shield SDK passes a viem `PublicClient` (so the pack can read on-chain\n * state) and the vault address the curator is acting on. Packs that don't\n * need on-chain state can ignore both — `prepareQuery` is optional.\n */\nexport interface PrepareQueryArgs {\n\treadonly publicClient: PublicClient;\n\treadonly vault: Address;\n}\n\n/**\n * `wasmArgs` payload (untyped at this layer; each pack narrows it via its own\n * `WasmArgsSchema`) plus an optional pre-image hash for binding the AVS-side\n * evaluation to a specific on-chain state. VaultsFYI uses this to bind the\n * evaluation to a `keccak(supplyQueue)` snapshot so the policy can reject\n * attestations whose underlying allocation has shifted between intent build\n * and on-chain submission.\n */\nexport interface PrepareQueryResult<TWasmArgs> {\n\treadonly wasmArgs: TWasmArgs;\n\treadonly freshnessHash?: Hex;\n}\n\n/**\n * Canonical typed contract every published `@newton-xyz/policy-pack-<name>`\n * package implements. `@newton-xyz/newton-shield-sdk`'s `createShield(...)`\n * accepts `PolicyPack<P, W, S>` as the curator's pack argument.\n *\n * Type parameters:\n * - `TParams`   — the shape stored on-chain in `NewtonPolicyData.policyParams`\n *                  (e.g. risk envelope thresholds for VaultsFYI).\n * - `TWasmArgs` — the shape passed to the policy's WASM oracle at evaluation\n *                  time (e.g. `{ vault, network, lastKnownAllocationHash }`).\n * - `TSecrets`  — required API credentials uploaded before any run/sim.\n *\n * The fields:\n * - `id`             — stable identifier of the form `<pack>/<purpose>/<version>`,\n *                       e.g. `vaultsfyi/risk-envelope/v1`. Used for telemetry\n *                       and for cross-referencing the `policy_metadata.json`.\n * - `paramsSchema`   — zod schema enforced at curator setup time when the\n *                       pack is bound to a `NewtonPolicyData`.\n * - `wasmArgsSchema` — zod schema enforced per call when the SDK builds the\n *                       intent and forwards `wasmArgs` to the gateway.\n * - `secretsSchema`  — zod schema enforced at upload-time. Validates the\n *                       shape of the secrets the operator stores in the AVS.\n *\n * Encoding is *not* a per-pack concern. The on-chain `policyParams` byte\n * format is a Newton-protocol invariant — UTF-8 JSON, sorted keys —\n * implemented once in this package as `encodePolicyParams` /\n * `decodePolicyParams`. See `./encoding.ts`. Earlier shapes of this\n * interface required each pack to ship its own `encodeParams` /\n * `decodeParams`; that structurally invited drift (vaultsfyi@0.2.0 shipped\n * ABI bytes against an AVS that reads `serde_json::from_str`, breaking\n * every call). The interface now leaves byte-format to the protocol.\n *\n * - `prepareQuery`   — optional. When present, the SDK invokes it on every\n *                       call to gather chain-state freshness inputs. Packs\n *                       that don't need this (e.g. KYC-only packs) omit it.\n *                       The optional second `options` argument is a\n *                       pack-typed escape hatch for per-call overrides —\n *                       e.g. VaultsFYI's `previousAllocationHash` for\n *                       freshness binding. Each concrete pack narrows it\n *                       via its own `prepareQuery` signature; the shared\n *                       interface keeps it `unknown` so the SDK can\n *                       forward it verbatim.\n * - `deployments`    — `chainId → env → Deployment` map sliced from the\n *                       upstream `deployments.json` for this pack only.\n *                       Typed as `Partial<Record<ChainId, Partial<Record<GatewayEnv,\n *                       Deployment>>>>` so callers must handle `undefined`\n *                       both for unsupported chains and for chains where\n *                       only one env has been deployed. Use\n *                       `getDeployment(pack, chainId, env)` from this\n *                       package for the safe lookup.\n * - `metadata`       — static identity from the pack's `policy_metadata.json`.\n */\nexport interface PolicyPack<TParams, TWasmArgs, TSecrets> {\n\treadonly id: string;\n\treadonly paramsSchema: z.ZodType<TParams>;\n\treadonly wasmArgsSchema: z.ZodType<TWasmArgs>;\n\treadonly secretsSchema: z.ZodType<TSecrets>;\n\tprepareQuery?(args: PrepareQueryArgs, options?: unknown): Promise<PrepareQueryResult<TWasmArgs>>;\n\treadonly deployments: Readonly<\n\t\tPartial<Record<ChainId, Readonly<Partial<Record<GatewayEnv, Deployment>>>>>\n\t>;\n\treadonly metadata: {\n\t\treadonly name: string;\n\t\treadonly version: string;\n\t\treadonly description: string;\n\t\treadonly author?: string;\n\t\treadonly link?: string;\n\t};\n}\n\n/**\n * Safe lookup helper. Returns the `Deployment` for `(chainId, env)` if the\n * pack is deployed there, or throws — `UnsupportedChainError` if the chain\n * itself has no entry, `UnsupportedEnvError` if the chain has at least one\n * env but not the one requested. Use this at every SDK callsite that reads\n * `pack.deployments[chainId][env]` so unsupported-cell failures surface\n * immediately rather than as `undefined.policy` further down.\n */\nexport function getDeployment<TParams, TWasmArgs, TSecrets>(\n\tpack: PolicyPack<TParams, TWasmArgs, TSecrets>,\n\tchainId: ChainId,\n\tenv: GatewayEnv,\n): Deployment {\n\tconst perEnv = pack.deployments[chainId];\n\tif (!perEnv) {\n\t\tconst supportedChains = Object.keys(pack.deployments).sort().join(\", \") || \"(none)\";\n\t\tthrow new UnsupportedChainError(\n\t\t\t`Pack \\`${pack.id}\\` is not deployed on chain ${chainId}. Supported: ${supportedChains}.`,\n\t\t\tpack.id,\n\t\t\tchainId,\n\t\t\tObject.keys(pack.deployments),\n\t\t);\n\t}\n\tconst deployment = perEnv[env];\n\tif (!deployment) {\n\t\tconst supportedEnvs = Object.keys(perEnv).sort().join(\", \") || \"(none)\";\n\t\tthrow new UnsupportedEnvError(\n\t\t\t`Pack \\`${pack.id}\\` is deployed on chain ${chainId} but not in env \"${env}\". Supported envs on this chain: ${supportedEnvs}.`,\n\t\t\tpack.id,\n\t\t\tchainId,\n\t\t\tenv,\n\t\t\tObject.keys(perEnv) as GatewayEnv[],\n\t\t);\n\t}\n\treturn deployment;\n}\n\n/**\n * Thrown by `getDeployment` when a pack is asked for a chain it isn't\n * deployed on. SDK consumers can catch this specifically to surface a\n * curator-friendly error rather than a `TypeError: Cannot read property\n * 'policy' of undefined`.\n */\nexport class UnsupportedChainError extends Error {\n\toverride readonly name = \"UnsupportedChainError\";\n\tconstructor(\n\t\tmessage: string,\n\t\treadonly packId: string,\n\t\treadonly chainId: ChainId,\n\t\treadonly supportedChainIds: ReadonlyArray<ChainId>,\n\t) {\n\t\tsuper(message);\n\t}\n}\n\n/**\n * Thrown by `getDeployment` when a pack is deployed on the requested chain\n * but not in the requested env. Distinct from `UnsupportedChainError`\n * because the recovery is different: the curator either picks a different\n * env (typo / wrong gateway) or the AVS team needs to deploy the pack into\n * the requested env.\n */\nexport class UnsupportedEnvError extends Error {\n\toverride readonly name = \"UnsupportedEnvError\";\n\tconstructor(\n\t\tmessage: string,\n\t\treadonly packId: string,\n\t\treadonly chainId: ChainId,\n\t\treadonly env: GatewayEnv,\n\t\treadonly supportedEnvs: ReadonlyArray<GatewayEnv>,\n\t) {\n\t\tsuper(message);\n\t}\n}\n","/**\n * Wrap a pack's WASM oracle output under its top-level `PACK_ID` key. Every\n * `policy.js` MUST call this on every return path (success AND error) so the\n * AVS-side `merge_jsons` (`newton-prover-avs/crates/operator/src/simulation.rs:296`)\n * composes cleanly across packs without top-level key collisions.\n *\n * The merge is shallow + last-wins: pre-namespacing, vaultsfyi's\n * `risk_score: number` would silently clobber chainalysis's `risk_score: string`\n * under composition. After namespacing, every pack's output sits under its\n * unique `PACK_ID` key and merges into a single `data.wasm` blob that\n * composite Rego can reference unambiguously as `data.wasm.<pack-id>.<field>`.\n *\n * The contract this helper locks:\n * - **Output is JSON-stringified** so `policy.js` can `return wrapOutput(...)`\n *   directly. The AVS host parses every PolicyData WASM's stdout as UTF-8\n *   JSON before merging.\n * - **Top-level keys are exactly `[packId]`** — assertable in\n *   `<pack>/wrapping_test.rego` with a fixture `data.wasm.<pack-id>` shape.\n *   To be enforced at PR time by an AST-lint CI guard (Phase 0 § Stream C,\n *   shipped in a separate PR) that flags any raw `return JSON.stringify(...)`\n *   callsite in `<pack>/policy.js` not routed through this helper.\n * - **`undefined` and other JSON-nonrepresentable payloads** (functions,\n *   symbols) cause `JSON.stringify` to omit the key, returning `'{}'` rather\n *   than `{ [packId]: undefined }`. The AVS contract doesn't admit such\n *   payloads — every `policy.js` returns either a structured success object\n *   or `{ error: \"...\" }` — so this is documented as out-of-contract input\n *   rather than guarded at runtime. The Stream C AST-lint catches the\n *   shape upstream.\n * - **Both success and error paths route through here.** Returning\n *   `{\"error\": \"...\"}` directly from `policy.js` would collide across packs in\n *   `merge_jsons` (every pack's error key would land at the top level and\n *   the last one wins). Wrapping the error under `[packId]` keeps per-pack\n *   error semantics (composite Rego can selectively deny on\n *   `data.wasm.<pack-id>.error`).\n *\n * @param packId The pack's stable id, matching the `<name>OracleModule.id`\n *               that ships in Phase 1 and the `KNOWN_PACK_IDS` registry in\n *               Phase 2. Convention: lowercase single-word, matches the\n *               pack's folder name (e.g. `\"vaultsfyi\"`, `\"chainalysis\"`).\n * @param valueOrError The pack's output payload — `{ score, risk_score, ... }`\n *                     for success, `{ error: \"...\" }` for failure paths.\n *                     Untyped at this layer because each pack's WASM emits\n *                     its own shape and the `PolicyPack` /  `OracleModule`\n *                     interfaces today carry input schemas (`paramsSchema`,\n *                     `wasmArgsSchema`, `secretsSchema`) but no on-chain\n *                     output schema — composite Rego references fields by\n *                     name (`data.wasm.<pack-id>.<field>`) and trusts the\n *                     pack-specific WASM bindings paired to each\n *                     `wasm_cid` in the manifest (Phase 1.5).\n * @returns JSON-stringified `{ [packId]: valueOrError }` ready to drop into\n *          a `policy.js` `return` statement.\n *\n * @example\n *   // vaultsfyi/policy.js (success path)\n *   return wrapOutput(\"vaultsfyi\", { score: 80, risk_score: 75, timestamp });\n *   // → '{\"vaultsfyi\":{\"score\":80,\"risk_score\":75,\"timestamp\":...}}'\n *\n *   // vaultsfyi/policy.js (error path)\n *   return wrapOutput(\"vaultsfyi\", { error: String(e) });\n *   // → '{\"vaultsfyi\":{\"error\":\"...\"}}'  — namespaced, won't collide\n */\nexport function wrapOutput(packId: string, valueOrError: unknown): string {\n\treturn JSON.stringify({ [packId]: valueOrError });\n}\n"],"mappings":";AAAA,SAAmB,YAAY,aAAa;AAa5C,SAAS,aAAa,OAAyB;AAC9C,MAAI,MAAM,QAAQ,KAAK,EAAG,QAAO,MAAM,IAAI,YAAY;AACvD,MAAI,SAAS,OAAO,UAAU,UAAU;AACvC,UAAM,MAAM;AACZ,UAAM,SAAkC,CAAC;AACzC,eAAW,OAAO,OAAO,KAAK,GAAG,EAAE,KAAK,GAAG;AAC1C,aAAO,GAAG,IAAI,aAAa,IAAI,GAAG,CAAC;AAAA,IACpC;AACA,WAAO;AAAA,EACR;AACA,SAAO;AACR;AAQO,SAAS,mBACf,MACA,QACM;AACN,QAAM,YAAY,KAAK,aAAa,MAAM,MAAM;AAChD,SAAO,MAAM,KAAK,UAAU,aAAa,SAAS,CAAC,CAAC;AACrD;AAYO,SAAS,mBACf,MACA,SACI;AACJ,QAAM,OAAO,IAAI,YAAY,SAAS,EAAE,OAAO,KAAK,CAAC,EAAE,OAAO,WAAW,OAAO,CAAC;AACjF,SAAO,KAAK,aAAa,MAAM,KAAK,MAAM,IAAI,CAAC;AAChD;;;ACmDO,SAAS,cACf,MACA,SACA,KACa;AACb,QAAM,SAAS,KAAK,YAAY,OAAO;AACvC,MAAI,CAAC,QAAQ;AACZ,UAAM,kBAAkB,OAAO,KAAK,KAAK,WAAW,EAAE,KAAK,EAAE,KAAK,IAAI,KAAK;AAC3E,UAAM,IAAI;AAAA,MACT,UAAU,KAAK,EAAE,+BAA+B,OAAO,gBAAgB,eAAe;AAAA,MACtF,KAAK;AAAA,MACL;AAAA,MACA,OAAO,KAAK,KAAK,WAAW;AAAA,IAC7B;AAAA,EACD;AACA,QAAM,aAAa,OAAO,GAAG;AAC7B,MAAI,CAAC,YAAY;AAChB,UAAM,gBAAgB,OAAO,KAAK,MAAM,EAAE,KAAK,EAAE,KAAK,IAAI,KAAK;AAC/D,UAAM,IAAI;AAAA,MACT,UAAU,KAAK,EAAE,2BAA2B,OAAO,oBAAoB,GAAG,oCAAoC,aAAa;AAAA,MAC3H,KAAK;AAAA,MACL;AAAA,MACA;AAAA,MACA,OAAO,KAAK,MAAM;AAAA,IACnB;AAAA,EACD;AACA,SAAO;AACR;AAQO,IAAM,wBAAN,cAAoC,MAAM;AAAA,EAEhD,YACC,SACS,QACA,SACA,mBACR;AACD,UAAM,OAAO;AAJJ;AACA;AACA;AAAA,EAGV;AAAA,EALU;AAAA,EACA;AAAA,EACA;AAAA,EALQ,OAAO;AAS1B;AASO,IAAM,sBAAN,cAAkC,MAAM;AAAA,EAE9C,YACC,SACS,QACA,SACA,KACA,eACR;AACD,UAAM,OAAO;AALJ;AACA;AACA;AACA;AAAA,EAGV;AAAA,EANU;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EANQ,OAAO;AAU1B;;;AC/GO,SAAS,WAAW,QAAgB,cAA+B;AACzE,SAAO,KAAK,UAAU,EAAE,CAAC,MAAM,GAAG,aAAa,CAAC;AACjD;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@newton-xyz/policy-pack-shared",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Shared TypeScript contract for Newton policy packs. Defines the PolicyPack<Params, WasmArgs, Secrets> interface that @newton-xyz/newton-shield-sdk consumes.",
   "license": "Apache-2.0",
   "author": "Newton Protocol <https://x.com/newton_xyz> (https://newton.xyz)",