@modainteract/moda-interact-shared 3.1.0 → 5.0.0

package/README.md

@@ -112,8 +112,8 @@ import { runCommerceTurn, type RunnerTool } from
 | `ToolDescriptorSchema`, `definitionToMcpDescriptor` | Full versioned Tool descriptor versus the MCP-facing name/description/inputSchema projection. The server-only execution definition is not exposed as model instructions. |
 | `CommerceManifestSchema` | Resolved immutable release contract. Each selected Capability identifies one Feature and one exact Tool descriptor; `featureBehaviours` contains one behaviour prompt for each represented Feature. Commerce provides the manifest; callers validate it. |
 | `GrantedToolSchema`, `GrantedToolsSchema` | Pinned Tool identity, exact Tool revision, name/version and sorted originating Capability keys selected for a conversation. One Tool reused by several Capabilities is emitted once with all Capability provenance. |
-| `CommerceConversationGrantSchema` | Persisted conversation permission snapshot. Background stores the resolved release, selected Capability keys and granted Tools and reuses them on later turns. Empty Capability/Tool selections are valid. |
-| `CommerceTurnIdentitySchema`, `CommerceAssertionSchema` | Turn identity and resolve/execute assertion shapes. These do not sign or verify JWT signatures; transport/authentication belongs to the services. |
+| `CommerceConversationGrantSchema` | Persisted conversation permission snapshot. Background owns it and stores the resolved release, selected Capability keys and granted Tools for reuse on later turns. Empty Capability/Tool selections are valid. |
+| `CommerceTurnIdentitySchema`, `CommerceAssertionSchema` | Background-owned turn identity and resolve/execute assertion shapes. These do not sign or verify JWT signatures; transport/authentication belongs to the services. |
 | `selectCapabilities` | Pure selection over ordinary Feature Capabilities plus caller-supplied Feature eligibility facts. There is no BASE/RECOVERY_POLICY Capability kind or mandatory `conversation_core`. |
 | `deduplicateTools` | Builds the granted-Tool union from one Tool descriptor per selected Capability while retaining deterministic Capability provenance. |
 | `manifestMatchesGrant`, `currentlyGrantedTools` | Compare pinned selection and current availability. Do not replace signature, tenant, lease or persistence checks. |
@@ -121,6 +121,11 @@ import { runCommerceTurn, type RunnerTool } from
 | `CommerceBasketSchema`, `CommerceProductSchema`, `CommerceOfferSchema`, `CommerceEvidenceSchema`, `CommerceAlternativeSchema` | Bounded commerce facts/evidence exchanged between services. Parsing does not prove external facts are true or current. |
 | `CommerceToolResultSchema`, `commerceToolResultSchema` | Standard result envelope; the factory accepts a specific data schema. |
 
+Background owns conversation, grant and turn state. MCP receives authenticated
+shop identity and may forward only already accepted opaque adapter context, such
+as `CommerceOutreachToolContextSchema`; it does not interpret that context as
+conversation authority.
+
 The direct release contract is Feature/Capability/Tool based. A selected Capability
 contains exactly one `featureId` and one exact `toolDescriptor`; Feature behaviour
 is carried separately and exactly once for each represented Feature. For example:
@@ -2382,3 +2387,85 @@ Type-only exports:
 - `RunnerTool`
 
 </details>
+
+
+## Product discovery and code-owned discount contracts
+
+The existing `/commerce` entrypoint exports `CommerceCategoryCandidateSchema`,
+`CommerceCategoryResolutionSchema`, `CommerceOptionalLookupUnavailableSchema`,
+and `CommerceProductRecommendationSelectionSchema`, with matching inferred types.
+The product input/output dictionaries include category resolution and flat,
+category-aware search. Recommendation selection contains identifiers and quantity,
+not model-authored prices or savings; applicability and cross-field relationships
+remain service policy.
+
+`CommerceBuiltInToolDescriptorSchema`, `CommerceBuiltInToolGrantSchema`, and
+`commerceDiscountBuiltInDescriptors` define the two code-owned discount reads.
+Their durable identity is the canonical tool name and `definitionVersion`; the
+strict descriptor and grant schemas reject extra fields. Reading these exports
+needs no provider/database configuration.
+
+The corrected built-in identities are exactly
+`commerce_get_discount_options@2.0.0` and
+`commerce_get_discount_details@2.0.0`. Their strict descriptor/grant schemas reject
+legacy `1.0.0`; the coordinated pre-production Database/consumer migration must
+finish before corrected consumers run. No legacy version union is supported.
+
+Only discount offer `startsAt`/`endsAt` and discount condition-facts
+`observedAt`/`unavailableAt` use the internal Shared-owned UTC validator:
+`YYYY-MM-DDTHH:mm:ssZ` or `YYYY-MM-DDTHH:mm:ss.<digits>Z`, with one or more
+fractional digits when the fraction is present. Seconds and uppercase `T`/`Z`
+are required; Gregorian dates and clock ranges are validated, including leap-year
+rules. Minute-only times, numeric offsets, leap seconds, invalid calendar dates
+and surrounding whitespace are rejected. Values are validated without coercion
+or normalization. Existing nullability and offer start-before-end checks remain.
+The exported general `DateSchema` and all its non-discount uses are unchanged.
+This correction is independent of Zod's `z.iso.datetime` implementation.
+
+Grants and runner descriptors now explicitly distinguish published identities
+from `kind: "BUILT_IN"`. Built-ins have no fabricated tool/revision IDs or
+capability provenance. Manifest `builtInTools` defaults to an empty array, but
+retained grants must equal the exact canonical descriptor set as well as the
+published capability union. `deduplicateTools` accepts the optional built-in
+descriptor set; `currentlyGrantedTools` requires an explicit currently permitted
+canonical built-in set and otherwise denies built-ins. Hosts still check current
+tenant/turn/release/permission before and after asynchronous tool work.
+
+The runtime runner version is **1.1.0**. Optional lookup unavailability is data
+inside `status: "OK"`; hard errors, stale turns and required referrals retain
+their existing semantics. Details permit bounded nullable scalars and depth five;
+input depth stays three and details payloads stay at 16KiB.
+
+The timestamp/version correction and prior identity cleanup require a coordinated
+breaking package publication and consumer migrations in the separate release task
+(ARCH-058-SHARED-006). This source change does not bump package metadata or publish
+to a registry.
+
+Run `npm run test:product-discovery-contracts` for the focused contracts/runner
+fixtures. To execute the actual Commerce-owned projector/publication integration,
+set `COMMERCE_CONTRACT_SOURCE_ROOT` to its explicit accepted source checkout.
+The test passes candidate schemas as function arguments to that existing
+projector; it neither changes nor links the consumer's installed package.
+The installed consumer still has the released operation registry: candidate operation
+metadata is checked against candidate Shared, and the installed publication pipeline
+is exercised with a registered operation and the actual generated input schema.
+This does not certify consumer adoption of the new operations before release.
+Without this test-only source prerequisite, that integration case is explicitly
+skipped rather than reported as executed.
+
+The discovery input dictionary also supports explicit `browse` (default `false`)
+and the published `commerce_get_shipping_information` operation
+(`shipping.getInformation`, version `1.0.0`). The named
+`CommerceShippingInformationInputSchema` / `CommerceShippingInformationSchema`
+and inferred types expose bounded native facts and independent product/policy outcomes.
+Policy HTML remains untrusted data; adapters enforce ownership, status relationships,
+verified hosts and the UTF-8 body budget.
+
+`CommerceResponseDispositionSchema` / `CommerceResponseDisposition` and
+`CommerceAnswerPresentationSelectionSchema` / `CommerceAnswerPresentationSelection`
+add optional identifier-only presentation fields. Merge their shape with recommendation
+and existing release details; Commerce owns explicit published instructions, and Background
+owns controlled composition. Product-bearing shipping observations latch that host path even
+without a selection; policy-only observations alone may retain ordinary grounded answers.
+Expected limitations never clear a terminal tool error. The default empty response contract,
+hard-referral envelope and two-tool discount built-in allowlist remain unchanged.

package/dist/{chunk-PE2JHOJX.js → chunk-H7NE3H5R.js}

@@ -1,6 +1,12 @@
 import {
-  CommerceManifestSchema
-} from "./chunk-H7AUKACO.js";
+  CommerceConversationGrantSchema,
+  CommerceManifestSchema,
+  GrantedToolsSchema,
+  PublishedToolDescriptorSchema,
+  isBuiltInTool,
+  isTrustedCommerceBuiltInDescriptor,
+  isTrustedCommerceBuiltInGrant
+} from "./chunk-NA76IPIW.js";
 import {
   IdSchema
 } from "./chunk-QVPEX7KY.js";
@@ -25,11 +31,11 @@ function selectCapabilities(candidates, facts) {
     throw new TypeError("Duplicate release membership");
   return selected.map((c) => c.key);
 }
-function deduplicateTools(capabilities) {
+function deduplicateTools(capabilities, builtInTools = []) {
   const byId = /* @__PURE__ */ new Map();
   const names = /* @__PURE__ */ new Map();
   for (const cap of capabilities) {
-    const d = cap.toolDescriptor;
+    const d = PublishedToolDescriptorSchema.parse(cap.toolDescriptor);
     const previous = byId.get(d.toolId);
     const descriptor = canonicalJson(d);
     if (previous && previous.descriptor !== descriptor || names.has(d.name) && names.get(d.name) !== d.toolId)
@@ -51,23 +57,33 @@ function deduplicateTools(capabilities) {
         }
       });
   }
-  return [...byId.values()].map((v) => v.tool).sort((a, b) => a.toolName.localeCompare(b.toolName, "en"));
+  if (builtInTools.some((tool) => !isTrustedCommerceBuiltInDescriptor(tool)))
+    throw new TypeError("Untrusted built-in descriptor");
+  return GrantedToolsSchema.parse([
+    ...[...byId.values()].map((value) => value.tool),
+    ...builtInTools.map((tool) => ({
+      kind: "BUILT_IN",
+      toolName: tool.name,
+      definitionVersion: tool.definitionVersion
+    }))
+  ]).sort((a, b) => a.toolName.localeCompare(b.toolName, "en"));
 }
 function manifestMatchesGrant(manifest, grant) {
+  if (!CommerceManifestSchema.safeParse(manifest).success || !CommerceConversationGrantSchema.safeParse(grant).success) return false;
   return manifest.releaseId === grant.releaseId && canonicalJson(manifest.selectedCapabilityKeys) === canonicalJson(grant.selectedCapabilityKeys) && canonicalJson(
     [...manifest.grantedTools].sort(
-      (a, b) => a.toolId.localeCompare(b.toolId)
+      (a, b) => a.toolName.localeCompare(b.toolName)
     )
   ) === canonicalJson(
     [...grant.grantedTools].sort(
-      (a, b) => a.toolId.localeCompare(b.toolId)
+      (a, b) => a.toolName.localeCompare(b.toolName)
     )
   );
 }
 var parseCommerceManifest = (raw) => CommerceManifestSchema.parse(raw);
-function currentlyGrantedTools(grant, eligibleCapabilityKeys, enabledToolIds) {
+function currentlyGrantedTools(grant, eligibleCapabilityKeys, enabledToolIds, allowedBuiltInTools = []) {
   return grant.grantedTools.filter(
-    (t) => enabledToolIds.has(t.toolId) && t.capabilityKeys.some((k) => eligibleCapabilityKeys.has(k))
+    (t) => isBuiltInTool(t) ? isTrustedCommerceBuiltInGrant(t) && allowedBuiltInTools.some((descriptor) => isTrustedCommerceBuiltInDescriptor(descriptor) && descriptor.name === t.toolName && descriptor.definitionVersion === t.definitionVersion) : enabledToolIds.has(t.toolId) && t.capabilityKeys.some((k) => eligibleCapabilityKeys.has(k))
   );
 }
 
@@ -78,4 +94,4 @@ export {
   parseCommerceManifest,
   currentlyGrantedTools
 };
-//# sourceMappingURL=chunk-PE2JHOJX.js.map
+//# sourceMappingURL=chunk-H7NE3H5R.js.map

package/dist/chunk-H7NE3H5R.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/commerce/selection.ts"],"sourcesContent":["import { IdSchema } from \"./primitives\";\nimport {\n  type CommerceManifest,\n  CommerceManifestSchema,\n  type CommerceConversationGrant,\n  CommerceConversationGrantSchema,\n} from \"./schemas\";\nimport { GrantedToolsSchema, PublishedToolDescriptorSchema, type GrantedTool, type PublishedGrantedTool, type PublishedToolDescriptor, type CommerceBuiltInToolDescriptor, isBuiltInTool } from \"./definitions\";\nimport { isTrustedCommerceBuiltInDescriptor, isTrustedCommerceBuiltInGrant } from \"./built-in-tools\";\nimport { canonicalJson } from \"./canonical-json\";\nexport type FeatureFacts = {\n  id: string;\n  active: boolean;\n  planMappingEnabled: boolean;\n  mode: \"ALWAYS_ENABLED\" | \"MERCHANT_OPT_IN\";\n  preferenceEnabled: boolean | null;\n};\nexport function selectCapabilities(\n  candidates: Array<{\n    key: string;\n    featureId: string;\n    enabled: boolean;\n    position: number;\n  }>,\n  facts: {\n    features: FeatureFacts[];\n  },\n) {\n  for (const candidate of candidates) {\n    IdSchema.parse(candidate.key);\n    IdSchema.parse(candidate.featureId);\n    if (!Number.isSafeInteger(candidate.position) || candidate.position < 0)\n      throw new TypeError(\"Invalid capability position\");\n  }\n  const selected = candidates\n    .filter((c) => {\n      if (!c.enabled) return false;\n      const f = facts.features.find((f) => f.id === c.featureId);\n      return (\n        !!f &&\n        f.active &&\n        f.planMappingEnabled &&\n        (f.mode === \"ALWAYS_ENABLED\" || f.preferenceEnabled === true)\n      );\n    })\n    .sort((a, b) => a.position - b.position);\n  if (\n    new Set(selected.map((c) => c.key)).size !== selected.length ||\n    new Set(selected.map((c) => c.position)).size !== selected.length\n  )\n    throw new TypeError(\"Duplicate release membership\");\n  return selected.map((c) => c.key);\n}\nexport function deduplicateTools(\n  capabilities: Array<{ key: string; toolDescriptor: PublishedToolDescriptor }>,\n  builtInTools: readonly CommerceBuiltInToolDescriptor[] = [],\n): GrantedTool[] {\n  const byId = new Map<string, { tool: PublishedGrantedTool; descriptor: string }>();\n  const names = new Map<string, string>();\n  for (const cap of capabilities) {\n    const d = PublishedToolDescriptorSchema.parse(cap.toolDescriptor);\n    const previous = byId.get(d.toolId);\n    const descriptor = canonicalJson(d);\n    if (\n      (previous && previous.descriptor !== descriptor) ||\n      (names.has(d.name) && names.get(d.name) !== d.toolId)\n    )\n      throw new TypeError(\"Conflicting tool association\");\n    names.set(d.name, d.toolId);\n    if (previous)\n      previous.tool.capabilityKeys = [\n        ...new Set([...previous.tool.capabilityKeys, cap.key]),\n      ].sort();\n    else\n      byId.set(d.toolId, {\n        descriptor,\n        tool: {\n          toolId: d.toolId,\n          toolRevisionId: d.toolRevisionId,\n          toolName: d.name,\n          definitionVersion: d.definitionVersion,\n          capabilityKeys: [cap.key],\n        },\n      });\n  }\n  if (builtInTools.some(tool => !isTrustedCommerceBuiltInDescriptor(tool)))\n    throw new TypeError(\"Untrusted built-in descriptor\");\n  return GrantedToolsSchema.parse([\n    ...[...byId.values()].map(value => value.tool),\n    ...builtInTools.map(tool => ({\n      kind: \"BUILT_IN\" as const, toolName: tool.name,\n      definitionVersion: tool.definitionVersion,\n    })),\n  ]).sort((a, b) => a.toolName.localeCompare(b.toolName, \"en\"));\n}\nexport function manifestMatchesGrant(\n  manifest: CommerceManifest,\n  grant: CommerceConversationGrant,\n) {\n  if (!CommerceManifestSchema.safeParse(manifest).success || !CommerceConversationGrantSchema.safeParse(grant).success) return false;\n  return (\n    manifest.releaseId === grant.releaseId &&\n    canonicalJson(manifest.selectedCapabilityKeys) ===\n      canonicalJson(grant.selectedCapabilityKeys) &&\n    canonicalJson(\n      [...manifest.grantedTools].sort((a, b) =>\n        a.toolName.localeCompare(b.toolName),\n      ),\n    ) ===\n      canonicalJson(\n        [...grant.grantedTools].sort((a, b) =>\n          a.toolName.localeCompare(b.toolName),\n        ),\n      )\n  );\n}\nexport const parseCommerceManifest = (raw: unknown) =>\n  CommerceManifestSchema.parse(raw);\nexport function currentlyGrantedTools(\n  grant: CommerceConversationGrant,\n  eligibleCapabilityKeys: ReadonlySet<string>,\n  enabledToolIds: ReadonlySet<string>,\n  allowedBuiltInTools: readonly CommerceBuiltInToolDescriptor[] = [],\n) {\n  return grant.grantedTools.filter(\n    (t) =>\n      isBuiltInTool(t)\n        ? isTrustedCommerceBuiltInGrant(t) && allowedBuiltInTools.some(descriptor =>\n            isTrustedCommerceBuiltInDescriptor(descriptor) && descriptor.name === t.toolName &&\n            descriptor.definitionVersion === t.definitionVersion)\n        : enabledToolIds.has(t.toolId) && t.capabilityKeys.some((k) => eligibleCapabilityKeys.has(k)),\n  );\n}\n"],"mappings":"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","names":["f"]}

package/dist/{chunk-H7AUKACO.js → chunk-NA76IPIW.js}

@@ -40,7 +40,7 @@ var keywords = [
 ];
 function validateSubset(value, mode) {
   let propertyCount = 0;
-  const maxDepth = mode === "input" ? 3 : 4;
+  const maxDepth = mode === "input" ? 3 : 5;
   function walk(raw, depth) {
     if (depth > maxDepth || !raw || typeof raw !== "object" || Array.isArray(raw))
       return false;
@@ -50,7 +50,7 @@ function validateSubset(value, mode) {
     ))
       return false;
     const nullable = Array.isArray(s.type);
-    if (nullable && (mode !== "input" || s.type.length !== 2 || s.type[1] !== "null"))
+    if (nullable && (s.type.length !== 2 || s.type[1] !== "null" || mode === "details" && ["object", "array"].includes(s.type[0])))
       return false;
     const type = typeof s.type === "string" ? s.type : s.type[0];
     if (![
@@ -255,17 +255,14 @@ var DEFINITION_SIZE_MESSAGE = "Definition exceeds the 65536-byte jsonb text limi
 
 // src/commerce/definitions.ts
 var ToolNameSchema = z3.string().regex(/^[a-z][a-z0-9_]{0,127}$/).refine((n) => n !== "finalResponse");
-var GrantedToolSchema = z3.strictObject({
+var PublishedGrantedToolSchema = z3.strictObject({
   toolId: IdSchema,
   toolRevisionId: IdSchema,
   toolName: ToolNameSchema,
   definitionVersion: SemverSchema,
   capabilityKeys: z3.array(IdSchema).min(1).max(32).refine((v) => distinct(v) && v.join("\0") === [...v].sort().join("\0"))
 });
-var GrantedToolsSchema = z3.array(GrantedToolSchema).max(32).refine(
-  (v) => distinct(v.map((x) => x.toolId)) && distinct(v.map((x) => x.toolName))
-);
-var ToolDescriptorSchema = z3.strictObject({
+var PublishedToolDescriptorSchema = z3.strictObject({
   toolId: IdSchema,
   toolRevisionId: IdSchema,
   name: ToolNameSchema,
@@ -273,6 +270,29 @@ var ToolDescriptorSchema = z3.strictObject({
   description: z3.string().min(1).max(4096),
   inputSchema: InputSchemaSchema
 });
+var CommerceBuiltInToolNameSchema = z3.enum([
+  "commerce_get_discount_options",
+  "commerce_get_discount_details"
+]).meta({ maxLength: 29 });
+var CommerceBuiltInToolGrantSchema = z3.strictObject({
+  kind: z3.enum(["BUILT_IN"]).meta({ maxLength: 8 }),
+  toolName: CommerceBuiltInToolNameSchema,
+  definitionVersion: z3.enum(["2.0.0"]).meta({ maxLength: 5 })
+});
+var CommerceBuiltInToolDescriptorSchema = z3.strictObject({
+  kind: z3.enum(["BUILT_IN"]).meta({ maxLength: 8 }),
+  name: CommerceBuiltInToolNameSchema,
+  definitionVersion: z3.enum(["2.0.0"]).meta({ maxLength: 5 }),
+  description: z3.string().min(1).max(4096),
+  inputSchema: InputSchemaSchema
+});
+var GrantedToolSchema = z3.union([PublishedGrantedToolSchema, CommerceBuiltInToolGrantSchema]);
+var ToolDescriptorSchema = z3.union([PublishedToolDescriptorSchema, CommerceBuiltInToolDescriptorSchema]);
+var GrantedToolsSchema = z3.array(GrantedToolSchema).max(32).refine((values) => {
+  const published = values.filter((value) => !("kind" in value));
+  return distinct(values.map((value) => value.toolName)) && distinct(published.map((value) => value.toolId));
+});
+var isBuiltInTool = (value) => "kind" in value && value.kind === "BUILT_IN";
 var MappingSchema = z3.union([
   z3.strictObject({
     input: z3.string().refine(safeName),
@@ -282,6 +302,10 @@ var MappingSchema = z3.union([
 ]);
 var MappingsSchema = z3.record(z3.string().refine(safeName), MappingSchema).refine((v) => Object.keys(v).length <= 32);
 var POLICY_OPERATIONS = [
+  "taxonomy.resolveCategories",
+  "products.search",
+  "products.get",
+  "shipping.getInformation",
   "recovery.getBasket",
   "shopify.searchProducts",
   "discounts.getOptions",
@@ -499,6 +523,47 @@ var POLICY_OPERATION_DESCRIPTORS = POLICY_OPERATIONS.map(
   (operation) => ({ operation, operationVersion: "1.0.0" })
 );
 
+// src/commerce/built-in-tools.ts
+function immutable(value) {
+  for (const child of Object.values(value))
+    if (child && typeof child === "object") immutable(child);
+  return Object.freeze(value);
+}
+var commerceDiscountBuiltInDescriptors = immutable([
+  {
+    kind: "BUILT_IN",
+    name: "commerce_get_discount_options",
+    definitionVersion: "2.0.0",
+    description: "Read the current shop's permitted discount options.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        limit: { type: "integer", minimum: 1, maximum: 50 },
+        cursor: { type: ["string", "null"], maxLength: 2048 }
+      },
+      additionalProperties: false
+    }
+  },
+  {
+    kind: "BUILT_IN",
+    name: "commerce_get_discount_details",
+    definitionVersion: "2.0.0",
+    description: "Read details for a permitted discount in the current shop.",
+    inputSchema: {
+      type: "object",
+      properties: { offerId: { type: "string", minLength: 1, maxLength: 128 } },
+      required: ["offerId"],
+      additionalProperties: false
+    }
+  }
+]);
+function isTrustedCommerceBuiltInDescriptor(value) {
+  return commerceDiscountBuiltInDescriptors.some((expected) => canonicalJson(expected) === canonicalJson(value));
+}
+function isTrustedCommerceBuiltInGrant(value) {
+  return commerceDiscountBuiltInDescriptors.some((expected) => value.toolName === expected.name && value.definitionVersion === expected.definitionVersion);
+}
+
 // src/commerce/response.ts
 import { z as z4 } from "zod";
 var CommerceResponseContractSchema = z4.strictObject({
@@ -700,7 +765,7 @@ var CommerceConversationGrantSchema = z5.strictObject({
   if (v.expiresAt && Date.parse(v.expiresAt) <= Date.parse(v.createdAt))
     c.addIssue({ code: "custom", message: "Invalid grant retention date" });
   if (jsonBytes(v.grantedTools) > 65536 || jsonBytes(v.selectedCapabilityKeys) > 8192 || v.grantedTools.some(
-    (t) => t.capabilityKeys.some((k) => !v.selectedCapabilityKeys.includes(k))
+    (t) => isBuiltInTool(t) ? !isTrustedCommerceBuiltInGrant(t) : t.capabilityKeys.some((k) => !v.selectedCapabilityKeys.includes(k))
   ))
     c.addIssue({ code: "custom", message: "Unselected grant provenance" });
 });
@@ -714,7 +779,7 @@ var CommerceManifestSchema = z5.strictObject({
       key: IdSchema,
       featureId: IdSchema,
       position: z5.number().int().nonnegative(),
-      toolDescriptor: ToolDescriptorSchema
+      toolDescriptor: PublishedToolDescriptorSchema
     })
   ).max(32),
   featureBehaviours: z5.array(
@@ -724,6 +789,7 @@ var CommerceManifestSchema = z5.strictObject({
     })
   ).max(32),
   selectedCapabilityKeys: z5.array(IdSchema).max(32).refine(distinct),
+  builtInTools: z5.array(CommerceBuiltInToolDescriptorSchema).max(2).default([]),
   grantedTools: GrantedToolsSchema,
   responseContract: CommerceResponseContractSchema,
   responseContractHash: HashSchema
@@ -765,7 +831,8 @@ var CommerceManifestSchema = z5.strictObject({
         }
       });
   }
-  if (union.size !== v.grantedTools.length || v.grantedTools.some((t) => {
+  if (union.size + v.builtInTools.length !== v.grantedTools.length || !distinct(v.builtInTools.map((tool) => tool.name)) || v.builtInTools.some((tool) => !isTrustedCommerceBuiltInDescriptor(tool)) || v.grantedTools.some((t) => {
+    if (isBuiltInTool(t)) return !v.builtInTools.some((descriptor) => descriptor.name === t.toolName && descriptor.definitionVersion === t.definitionVersion && isTrustedCommerceBuiltInGrant(t));
     const expected = union.get(t.toolId)?.tool;
     return !expected || expected.toolRevisionId !== t.toolRevisionId || expected.toolName !== t.toolName || expected.definitionVersion !== t.definitionVersion || JSON.stringify([...new Set(expected.capabilityKeys)].sort()) !== JSON.stringify(t.capabilityKeys);
   }))
@@ -853,13 +920,23 @@ var CommerceProductSchema = z5.strictObject({
   saleEvidence: CommerceProductSaleEvidenceSchema.nullable().optional(),
   observedAt: DateSchema
 });
+var discountUtcPattern = /^([0-9]{4})-([0-9]{2})-([0-9]{2})T([0-9]{2}):([0-9]{2}):([0-9]{2})(?:\.[0-9]+)?Z(?![\s\S])/;
+var CommerceDiscountDateTimeSchema = z5.string().regex(discountUtcPattern).refine((value) => {
+  const match = discountUtcPattern.exec(value);
+  if (!match) return false;
+  const [year, month, day, hour, minute, second] = match.slice(1).map(Number);
+  if (month < 1 || month > 12 || hour > 23 || minute > 59 || second > 59) return false;
+  const leapYear = year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0);
+  const daysInMonth = [31, leapYear ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+  return day >= 1 && day <= daysInMonth[month - 1];
+}, "Expected a valid UTC discount timestamp with seconds");
 var CommerceOfferSchema = z5.strictObject({
   offerId: IdSchema,
   title: z5.string().min(1).max(512),
   method: z5.enum(["AUTOMATIC", "CODE"]),
   code: z5.string().min(1).max(128).nullable(),
-  startsAt: DateSchema.nullable(),
-  endsAt: DateSchema.nullable(),
+  startsAt: CommerceDiscountDateTimeSchema.nullable(),
+  endsAt: CommerceDiscountDateTimeSchema.nullable(),
   support: z5.enum(["SUPPORTED", "UNSUPPORTED", "UNKNOWN"]),
   reasonCodes: z5.array(z5.string().min(1).max(64)).max(16)
 }).refine(
@@ -879,9 +956,9 @@ var CommerceDiscountCombinationFactsSchema = z5.strictObject({
 var CommerceDiscountConditionFactsSchema = z5.strictObject({
   provider: z5.enum(["SHOPIFY", "WOOCOMMERCE"]),
   completeness: z5.enum(["COMPLETE", "PARTIAL", "UNKNOWN"]),
-  observedAt: DateSchema,
+  observedAt: CommerceDiscountDateTimeSchema,
   providerStatus: z5.string().max(64),
-  unavailableAt: DateSchema.nullable(),
+  unavailableAt: CommerceDiscountDateTimeSchema.nullable(),
   discountKind: z5.enum([
     "PERCENTAGE",
     "FIXED_AMOUNT",
@@ -1003,11 +1080,111 @@ function commerceToolResultSchema(data) {
 var CommerceToolResultSchema = commerceToolResultSchema(
   boundedJson(262144)
 );
+var wireId = z5.string().min(1).max(128);
+var taxonomySource = z5.enum(["SHOPIFY_STANDARD_PRODUCT_TAXONOMY"]).meta({ maxLength: 33 });
+var CommerceCategoryCandidateSchema = z5.strictObject({
+  categoryId: wireId,
+  name: z5.string().min(1).max(512),
+  fullName: z5.string().min(1).max(4096),
+  parentId: wireId.nullable(),
+  level: z5.number().int().min(0).max(32),
+  ancestorIds: z5.array(wireId).max(32),
+  distance: z5.number().min(0).max(2)
+});
+var CommerceCategoryResolutionSchema = z5.union([
+  z5.strictObject({
+    outcome: z5.enum(["CANDIDATES", "NO_CANDIDATES"]).meta({ maxLength: 13 }),
+    generationId: wireId,
+    source: taxonomySource,
+    taxonomyVersion: z5.string().min(1).max(64),
+    languageTag: z5.string().min(1).max(35),
+    candidates: z5.array(CommerceCategoryCandidateSchema).max(10)
+  }),
+  z5.strictObject({
+    outcome: z5.enum(["UNAVAILABLE"]).meta({ maxLength: 11 }),
+    reasonCode: z5.enum(["NOT_READY", "TEMPORARY_UNAVAILABLE"]).meta({ maxLength: 21 })
+  })
+]);
+var CommerceOptionalLookupUnavailableSchema = z5.strictObject({
+  outcome: z5.enum(["UNAVAILABLE"]).meta({ maxLength: 11 }),
+  reasonCode: z5.enum(["TEMPORARY_UNAVAILABLE"]).meta({ maxLength: 21 })
+});
+var CommerceProductRecommendationSelectionSchema = z5.strictObject({
+  productRecommendationVersion: z5.enum(["1"]).meta({ maxLength: 1 }).optional(),
+  productRecommendations: z5.array(z5.strictObject({
+    scope: z5.enum(["PRODUCT_ONLY", "ADD_TO_BASKET", "REPLACE_BASKET_LINE"]).meta({ maxLength: 19 }),
+    basketLineId: wireId.nullable(),
+    productId: wireId,
+    variantId: wireId.nullable(),
+    quantity: z5.number().int().min(1).max(99),
+    promotionKind: z5.enum(["NONE", "NATIVE_SALE", "DISCOUNT"]).meta({ maxLength: 11 }),
+    offerIds: z5.array(wireId).max(3)
+  })).min(1).max(3).optional()
+});
+var CommerceResponseDispositionSchema = z5.enum([
+  "STANDARD",
+  "OUT_OF_SCOPE_REDIRECT",
+  "SHIPPING_INFORMATION_UNVERIFIED"
+]).meta({ maxLength: 31 });
+var CommerceAnswerPresentationSelectionSchema = z5.strictObject({
+  responseDisposition: CommerceResponseDispositionSchema.optional(),
+  shippingInformationSelection: z5.strictObject({
+    productId: wireId.nullable(),
+    variantId: wireId.nullable()
+  }).optional()
+});
+var CommerceShippingInformationInputSchema = z5.strictObject({
+  productId: wireId.nullable().default(null),
+  variantId: wireId.nullable().default(null)
+});
+var CommerceShippingInformationSchema = z5.strictObject({
+  provider: z5.enum(["SHOPIFY", "WOOCOMMERCE"]).meta({ maxLength: 11 }),
+  observedAt: DateSchema,
+  product: z5.strictObject({
+    status: z5.enum(["NOT_REQUESTED", "VARIANT_REQUIRED", "AVAILABLE"]).meta({ maxLength: 16 }),
+    productId: wireId.nullable(),
+    variantId: wireId.nullable(),
+    requiresShipping: z5.boolean().nullable(),
+    virtual: z5.boolean().nullable(),
+    weight: z5.strictObject({
+      value: z5.number().min(0),
+      unit: z5.enum(["GRAMS", "KILOGRAMS", "OUNCES", "POUNDS"]).meta({ maxLength: 9 }).nullable()
+    }).nullable(),
+    dimensions: z5.strictObject({
+      length: z5.number().min(0).nullable(),
+      width: z5.number().min(0).nullable(),
+      height: z5.number().min(0).nullable(),
+      unit: z5.string().min(1).max(16).nullable()
+    }).nullable(),
+    shippingClassId: wireId.nullable(),
+    shippingClassSlug: z5.string().min(1).max(512).nullable()
+  }),
+  policy: z5.strictObject({
+    status: z5.enum(["AVAILABLE", "NOT_CONFIGURED", "SCOPE_NOT_GRANTED", "UNSUPPORTED"]).meta({ maxLength: 17 }),
+    trust: z5.enum(["UNTRUSTED_REFERENCE"]).meta({ maxLength: 19 }),
+    title: z5.string().min(1).max(512).nullable(),
+    bodyStatus: z5.enum(["AVAILABLE", "EMPTY", "TOO_LARGE", "NOT_AVAILABLE"]).meta({ maxLength: 13 }),
+    bodyHtml: z5.string().min(1).max(8e3).nullable(),
+    url: z5.url({ protocol: /^https$/ }).min(1).max(2048).nullable(),
+    updatedAt: DateSchema.nullable()
+  })
+});
 var limit = z5.number().int().min(1).max(3).default(3);
 var CommerceToolInputs = {
+  commerce_resolve_product_categories: z5.strictObject({
+    query: z5.string().min(1).max(200),
+    limit: z5.number().int().min(1).max(10).default(5)
+  }),
+  commerce_get_shipping_information: CommerceShippingInformationInputSchema,
   commerce_get_basket: z5.strictObject({}),
   commerce_search_products: z5.strictObject({
-    query: z5.string().min(1).max(200),
+    query: z5.string().min(1).max(200).nullable().default(null),
+    category: z5.strictObject({
+      system: z5.enum(["SHOPIFY_STANDARD_PRODUCT_TAXONOMY", "WOOCOMMERCE_PRODUCT_CATEGORY"]).meta({ maxLength: 33 }),
+      id: wireId,
+      taxonomyVersion: z5.string().min(1).max(64).nullable()
+    }).optional(),
+    browse: z5.boolean().default(false),
     maximumPrice: MoneySchema.optional(),
     availableOnly: z5.boolean().default(true),
     limit: z5.number().int().min(1).max(20).default(10),
@@ -1042,6 +1219,8 @@ var alternatives = z5.strictObject({
   truncated: z5.boolean()
 });
 var CommerceToolOutputs = {
+  commerce_resolve_product_categories: CommerceCategoryResolutionSchema,
+  commerce_get_shipping_information: CommerceShippingInformationSchema,
   commerce_get_basket: CommerceBasketSchema,
   commerce_search_products: z5.strictObject({
     products: z5.array(CommerceProductSchema).max(20),
@@ -1051,15 +1230,15 @@ var CommerceToolOutputs = {
   commerce_get_product: z5.strictObject({
     product: CommerceProductSchema.nullable()
   }),
-  commerce_get_discount_options: z5.strictObject({
+  commerce_get_discount_options: z5.union([CommerceOptionalLookupUnavailableSchema, z5.strictObject({
     mode: z5.enum(["NONE", "FIXED", "AI_BEST_APPLICABLE"]),
     offers: z5.array(CommerceOfferSchema).max(50),
     truncated: z5.boolean(),
     cursor: z5.string().max(2048).nullable().optional()
-  }),
-  commerce_get_discount_details: z5.strictObject({
+  })]),
+  commerce_get_discount_details: z5.union([CommerceOptionalLookupUnavailableSchema, z5.strictObject({
     details: CommerceDiscountDetailsSchema.nullable()
-  }),
+  })]),
   commerce_evaluate_discount: CommerceEvidenceSchema,
   commerce_find_qualifying_products: alternatives,
   commerce_find_similar_products: alternatives
@@ -1101,9 +1280,15 @@ export {
   ConnectionIssueSchema,
   ConnectionResultSchema,
   ToolNameSchema,
+  PublishedGrantedToolSchema,
+  PublishedToolDescriptorSchema,
+  CommerceBuiltInToolNameSchema,
+  CommerceBuiltInToolGrantSchema,
+  CommerceBuiltInToolDescriptorSchema,
   GrantedToolSchema,
-  GrantedToolsSchema,
   ToolDescriptorSchema,
+  GrantedToolsSchema,
+  isBuiltInTool,
   POLICY_OPERATIONS,
   ExternalHttpExecutionSchema,
   CommerceExecutionSchema,
@@ -1118,6 +1303,9 @@ export {
   CommerceToolIdentitySchema,
   CommerceToolRevisionIdentitySchema,
   POLICY_OPERATION_DESCRIPTORS,
+  commerceDiscountBuiltInDescriptors,
+  isTrustedCommerceBuiltInDescriptor,
+  isTrustedCommerceBuiltInGrant,
   CommerceResponseContractSchema,
   EMPTY_RESPONSE_CONTRACT,
   ReferralReasonSchema,
@@ -1145,8 +1333,16 @@ export {
   CommerceErrorCodeSchema,
   commerceToolResultSchema,
   CommerceToolResultSchema,
+  CommerceCategoryCandidateSchema,
+  CommerceCategoryResolutionSchema,
+  CommerceOptionalLookupUnavailableSchema,
+  CommerceProductRecommendationSelectionSchema,
+  CommerceResponseDispositionSchema,
+  CommerceAnswerPresentationSelectionSchema,
+  CommerceShippingInformationInputSchema,
+  CommerceShippingInformationSchema,
   CommerceToolInputs,
   CommerceToolOutputs,
   productBelongsToDomain
 };
-//# sourceMappingURL=chunk-H7AUKACO.js.map
+//# sourceMappingURL=chunk-NA76IPIW.js.map