@01.software/cli 0.16.0 → 0.17.1

package/dist/index.js

@@ -13,18 +13,52 @@ import {
 
 // src/lib/credentials.ts
 import {
+  chmodSync,
+  closeSync,
+  constants as fsConstants,
   existsSync,
+  fchmodSync,
+  fstatSync,
+  fsyncSync,
+  lstatSync,
   mkdirSync,
+  openSync,
   readFileSync,
-  writeFileSync,
+  renameSync,
   unlinkSync,
+  writeFileSync,
   appendFileSync
 } from "fs";
-import { join } from "path";
+import { spawnSync } from "child_process";
+import { randomBytes } from "crypto";
+import { dirname, join } from "path";
 import { homedir } from "os";
 var DIR_NAME = ".01software";
 var FILE_NAME = "credentials.json";
 var TENANTS_FILE = "tenants.json";
+var LOCAL_CREDENTIAL_PATH = `${DIR_NAME}/${FILE_NAME}`;
+var LOCAL_GITIGNORE_ENTRY = `${DIR_NAME}/`;
+var PRIVATE_DIRECTORY_MODE = 448;
+var PRIVATE_FILE_MODE = 384;
+var CURRENT_USER_ID = process.platform !== "win32" && typeof process.getuid === "function" ? process.getuid() : null;
+var HAS_POSIX_FILE_PERMISSIONS = CURRENT_USER_ID !== null;
+var SANITIZED_GIT_ENVIRONMENT_VARIABLES = /* @__PURE__ */ new Set([
+  "GIT_ALTERNATE_OBJECT_DIRECTORIES",
+  "GIT_CEILING_DIRECTORIES",
+  "GIT_COMMON_DIR",
+  "GIT_CONFIG_COUNT",
+  "GIT_CONFIG_PARAMETERS",
+  "GIT_DIR",
+  "GIT_DISCOVERY_ACROSS_FILESYSTEM",
+  "GIT_INDEX_FILE",
+  "GIT_ICASE_PATHSPECS",
+  "GIT_GLOB_PATHSPECS",
+  "GIT_LITERAL_PATHSPECS",
+  "GIT_NOGLOB_PATHSPECS",
+  "GIT_OBJECT_DIRECTORY",
+  "GIT_PREFIX",
+  "GIT_WORK_TREE"
+]);
 function getCredentialsPath() {
   return join(homedir(), DIR_NAME, FILE_NAME);
 }
@@ -32,19 +66,12 @@ function loadCredentials() {
   return loadCredentialsFrom(getCredentialsPath());
 }
 function saveCredentials(creds) {
-  const dir = join(homedir(), DIR_NAME);
-  if (!existsSync(dir)) {
-    mkdirSync(dir, { recursive: true, mode: 448 });
-  }
   const filePath = getCredentialsPath();
   const data = {
     ...creds,
     storedAt: (/* @__PURE__ */ new Date()).toISOString()
   };
-  writeFileSync(filePath, JSON.stringify(data, null, 2), {
-    encoding: "utf-8",
-    mode: 384
-  });
+  writeCredentialFile(filePath, JSON.stringify(data, null, 2));
 }
 function deleteCredentials() {
   const filePath = getCredentialsPath();
@@ -58,21 +85,19 @@ function getLocalCredentialsPath() {
 function loadLocalCredentials() {
   return loadCredentialsFrom(getLocalCredentialsPath());
 }
-function saveLocalCredentials(creds) {
-  const dir = join(process.cwd(), DIR_NAME);
-  if (!existsSync(dir)) {
-    mkdirSync(dir, { recursive: true, mode: 448 });
-  }
-  const filePath = getLocalCredentialsPath();
+function saveLocalCredentials(creds, workingDirectory = process.cwd()) {
+  const temporaryFileName = createTemporaryCredentialFileName();
+  ensureGitignore(workingDirectory, `${DIR_NAME}/${temporaryFileName}`);
+  const filePath = join(workingDirectory, DIR_NAME, FILE_NAME);
   const data = {
     ...creds,
     storedAt: (/* @__PURE__ */ new Date()).toISOString()
   };
-  writeFileSync(filePath, JSON.stringify(data, null, 2), {
-    encoding: "utf-8",
-    mode: 384
-  });
-  ensureGitignore();
+  writeCredentialFile(
+    filePath,
+    JSON.stringify(data, null, 2),
+    temporaryFileName
+  );
 }
 function saveTenantList(tenants) {
   const dir = join(homedir(), DIR_NAME);
@@ -100,6 +125,161 @@ function loadTenantList() {
     return null;
   }
 }
+function writeCredentialFile(filePath, content, temporaryFileName = createTemporaryCredentialFileName()) {
+  const directoryPath = dirname(filePath);
+  const directoryDescriptor = openPrivateCredentialDirectory(directoryPath);
+  const initialTarget = inspectCredentialTarget(filePath);
+  const tempPath = join(directoryPath, temporaryFileName);
+  let tempDescriptor;
+  try {
+    tempDescriptor = openSync(tempPath, "wx", PRIVATE_FILE_MODE);
+    const tempStats = fstatSync(tempDescriptor);
+    assertRegularOwnedCredentialFile(tempStats, "temporary credential file");
+    if (HAS_POSIX_FILE_PERMISSIONS) {
+      fchmodSync(tempDescriptor, PRIVATE_FILE_MODE);
+      assertMode(
+        fstatSync(tempDescriptor),
+        PRIVATE_FILE_MODE,
+        "temporary credential file"
+      );
+    }
+    writeFileSync(tempDescriptor, content, { encoding: "utf-8" });
+    fsyncSync(tempDescriptor);
+    closeSync(tempDescriptor);
+    tempDescriptor = void 0;
+    const currentTarget = inspectCredentialTarget(filePath);
+    if (!sameFileIdentity(initialTarget, currentTarget)) {
+      throw credentialFileProtectionError(
+        "credential target changed while being checked"
+      );
+    }
+    renameSync(tempPath, filePath);
+    const finalStats = lstatCredentialPath(filePath);
+    if (!finalStats) {
+      throw credentialFileProtectionError(
+        "credential target disappeared after atomic replacement"
+      );
+    }
+    assertRegularOwnedCredentialFile(finalStats, "credential target");
+    if (HAS_POSIX_FILE_PERMISSIONS) {
+      assertMode(finalStats, PRIVATE_FILE_MODE, "credential target");
+      if (directoryDescriptor !== void 0) {
+        fsyncSync(directoryDescriptor);
+      }
+    }
+  } catch (error) {
+    if (tempDescriptor !== void 0) {
+      try {
+        closeSync(tempDescriptor);
+      } catch {
+      }
+    }
+    try {
+      unlinkSync(tempPath);
+    } catch {
+    }
+    throw error;
+  } finally {
+    if (directoryDescriptor !== void 0) {
+      closeSync(directoryDescriptor);
+    }
+  }
+}
+function openPrivateCredentialDirectory(directoryPath) {
+  let directoryStats = lstatCredentialPath(directoryPath);
+  if (!directoryStats) {
+    try {
+      mkdirSync(directoryPath, { mode: PRIVATE_DIRECTORY_MODE });
+      if (HAS_POSIX_FILE_PERMISSIONS) {
+        chmodSync(directoryPath, PRIVATE_DIRECTORY_MODE);
+      }
+    } catch (error) {
+      if (error.code !== "EEXIST") throw error;
+    }
+    directoryStats = lstatCredentialPath(directoryPath);
+  }
+  if (!directoryStats || directoryStats.isSymbolicLink() || !directoryStats.isDirectory()) {
+    throw credentialFileProtectionError(
+      "credential directory must be a regular directory, not a symlink"
+    );
+  }
+  assertCurrentUserOwns(directoryStats, "credential directory");
+  if (!HAS_POSIX_FILE_PERMISSIONS) return void 0;
+  const descriptor = openSync(
+    directoryPath,
+    fsConstants.O_RDONLY | fsConstants.O_DIRECTORY | fsConstants.O_NOFOLLOW
+  );
+  try {
+    const openedStats = fstatSync(descriptor);
+    if (!openedStats.isDirectory() || openedStats.dev !== directoryStats.dev || openedStats.ino !== directoryStats.ino) {
+      throw credentialFileProtectionError(
+        "credential directory changed while being checked"
+      );
+    }
+    assertCurrentUserOwns(openedStats, "credential directory");
+    fchmodSync(descriptor, PRIVATE_DIRECTORY_MODE);
+    assertMode(
+      fstatSync(descriptor),
+      PRIVATE_DIRECTORY_MODE,
+      "credential directory"
+    );
+    return descriptor;
+  } catch (error) {
+    closeSync(descriptor);
+    throw error;
+  }
+}
+function inspectCredentialTarget(filePath) {
+  const stats = lstatCredentialPath(filePath);
+  if (!stats) return null;
+  assertRegularOwnedCredentialFile(stats, "credential target");
+  return { dev: stats.dev, ino: stats.ino };
+}
+function assertRegularOwnedCredentialFile(stats, description) {
+  if (stats.isSymbolicLink()) {
+    throw credentialFileProtectionError(`${description} must not be a symlink`);
+  }
+  if (!stats.isFile()) {
+    throw credentialFileProtectionError(`${description} must be a regular file`);
+  }
+  if (HAS_POSIX_FILE_PERMISSIONS && stats.nlink > 1) {
+    throw credentialFileProtectionError(
+      `${description} must not have multiple hard links`
+    );
+  }
+  assertCurrentUserOwns(stats, description);
+}
+function assertCurrentUserOwns(stats, description) {
+  if (CURRENT_USER_ID !== null && stats.uid !== CURRENT_USER_ID) {
+    throw credentialFileProtectionError(
+      `${description} must be owned by the current user`
+    );
+  }
+}
+function assertMode(stats, expectedMode, description) {
+  if ((stats.mode & 511) !== expectedMode) {
+    throw credentialFileProtectionError(
+      `${description} permissions could not be secured`
+    );
+  }
+}
+function sameFileIdentity(initial, current) {
+  if (!initial || !current) return initial === current;
+  return initial.dev === current.dev && initial.ino === current.ino;
+}
+function lstatCredentialPath(filePath) {
+  try {
+    return lstatSync(filePath);
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    throw credentialFileProtectionError(
+      "credential filesystem target could not be inspected"
+    );
+  }
+}
+function credentialFileProtectionError(message) {
+  return new Error(`Cannot save credentials: ${message}`);
+}
 function loadCredentialsFrom(filePath) {
   if (!existsSync(filePath)) return null;
   try {
@@ -111,25 +291,160 @@ function loadCredentialsFrom(filePath) {
     return null;
   }
 }
-function ensureGitignore() {
-  const gitignorePath = join(process.cwd(), ".gitignore");
-  const entry = ".01software/";
-  if (existsSync(gitignorePath)) {
-    const content = readFileSync(gitignorePath, "utf-8");
-    if (content.includes(entry)) return;
-    appendFileSync(gitignorePath, `
-${entry}
-`, "utf-8");
-  } else {
-    writeFileSync(gitignorePath, `${entry}
-`, "utf-8");
+function ensureGitignore(cwd, temporaryCredentialPath) {
+  const gitignorePath = join(cwd, ".gitignore");
+  assertSafeGitignorePath(gitignorePath);
+  const gitState = detectGitWorkTree(cwd);
+  if (gitState === "inside") {
+    assertCredentialPathIsUntracked(cwd);
+    if (areCredentialPathsIgnored(cwd, temporaryCredentialPath)) return;
+    ensureTerminalGitignoreEntry(gitignorePath, true);
+    if (!areCredentialPathsIgnored(cwd, temporaryCredentialPath)) {
+      throw credentialProtectionError(
+        "Git still reports a credential path as unignored"
+      );
+    }
+    return;
+  }
+  ensureTerminalGitignoreEntry(gitignorePath, false);
+}
+function assertSafeGitignorePath(gitignorePath) {
+  const stats = lstatIfPresent(gitignorePath);
+  if (stats && (!stats.isFile() || stats.isSymbolicLink())) {
+    throw credentialProtectionError(".gitignore must be a regular file");
+  }
+}
+function ensureTerminalGitignoreEntry(gitignorePath, forceAppend) {
+  const initialStats = lstatIfPresent(gitignorePath);
+  if (!initialStats) {
+    try {
+      writeFileSync(gitignorePath, `${LOCAL_GITIGNORE_ENTRY}
+`, {
+        encoding: "utf-8",
+        flag: "wx"
+      });
+      return;
+    } catch (error) {
+      if (error.code !== "EEXIST") throw error;
+      return ensureTerminalGitignoreEntry(gitignorePath, forceAppend);
+    }
+  }
+  if (!initialStats.isFile() || initialStats.isSymbolicLink()) {
+    throw credentialProtectionError(".gitignore must be a regular file");
+  }
+  const descriptor = openSync(gitignorePath, "a+");
+  try {
+    const openedStats = fstatSync(descriptor);
+    if (!openedStats.isFile() || openedStats.dev !== initialStats.dev || openedStats.ino !== initialStats.ino) {
+      throw credentialProtectionError(".gitignore changed while being checked");
+    }
+    const content = readFileSync(descriptor, "utf-8");
+    const lastNonEmptyLine = content.split(/\r?\n/).filter((line) => line.length > 0).at(-1);
+    if (!forceAppend && (lastNonEmptyLine === LOCAL_GITIGNORE_ENTRY || lastNonEmptyLine === `/${LOCAL_GITIGNORE_ENTRY}`)) {
+      return;
+    }
+    const separator = content.length > 0 && !content.endsWith("\n") ? "\n" : "";
+    appendFileSync(
+      descriptor,
+      `${separator}${LOCAL_GITIGNORE_ENTRY}
+`,
+      "utf-8"
+    );
+  } finally {
+    closeSync(descriptor);
   }
 }
+function detectGitWorkTree(cwd) {
+  const result = runGit(cwd, ["rev-parse", "--is-inside-work-tree"]);
+  if (result.error) {
+    if (result.error.code === "ENOENT" && !hasGitMarker(cwd)) {
+      return "outside";
+    }
+    throw credentialProtectionError("Git repository detection failed");
+  }
+  if (result.status === 0) {
+    if (result.stdout.trim() === "true") return "inside";
+    throw credentialProtectionError(
+      "the current directory is not a Git work tree"
+    );
+  }
+  if (result.status === 128 && !hasGitMarker(cwd)) return "outside";
+  throw credentialProtectionError("Git repository detection failed");
+}
+function assertCredentialPathIsUntracked(cwd) {
+  const result = runGit(cwd, [
+    "ls-files",
+    "-z",
+    "--",
+    `:(icase,literal)${LOCAL_CREDENTIAL_PATH}`
+  ]);
+  if (result.error || result.status !== 0) {
+    throw credentialProtectionError("Git tracked-file verification failed");
+  }
+  if (result.stdout.length > 0) {
+    throw credentialProtectionError(
+      ".01software/credentials.json is already tracked by Git"
+    );
+  }
+}
+function createTemporaryCredentialFileName() {
+  return `.${FILE_NAME}.${randomBytes(12).toString("hex")}.tmp`;
+}
+function areCredentialPathsIgnored(cwd, temporaryCredentialPath) {
+  return isPathIgnored(cwd, LOCAL_CREDENTIAL_PATH) && isPathIgnored(cwd, temporaryCredentialPath);
+}
+function isPathIgnored(cwd, relativePath) {
+  const result = runGit(cwd, [
+    "check-ignore",
+    "--quiet",
+    "--no-index",
+    "--",
+    relativePath
+  ]);
+  if (result.error || result.status !== 0 && result.status !== 1) {
+    throw credentialProtectionError("Git ignore verification failed");
+  }
+  return result.status === 0;
+}
+function runGit(cwd, args) {
+  const env = { ...process.env, LC_ALL: "C" };
+  for (const key of Object.keys(env)) {
+    const normalizedKey = key.toUpperCase();
+    if (SANITIZED_GIT_ENVIRONMENT_VARIABLES.has(normalizedKey) || normalizedKey.startsWith("GIT_CONFIG_KEY_") || normalizedKey.startsWith("GIT_CONFIG_VALUE_")) {
+      delete env[key];
+    }
+  }
+  return spawnSync("git", args, {
+    cwd,
+    encoding: "utf-8",
+    env
+  });
+}
+function hasGitMarker(startPath) {
+  let currentPath = startPath;
+  while (true) {
+    if (lstatIfPresent(join(currentPath, ".git"))) return true;
+    const parentPath = dirname(currentPath);
+    if (parentPath === currentPath) return false;
+    currentPath = parentPath;
+  }
+}
+function lstatIfPresent(filePath) {
+  try {
+    return lstatSync(filePath);
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    throw credentialProtectionError("local Git metadata could not be inspected");
+  }
+}
+function credentialProtectionError(message) {
+  return new Error(`Cannot save local credentials: ${message}`);
+}
 
 // src/lib/output.ts
 import pc from "picocolors";
 
-// ../errors/src/admin-error.ts
+// ../../internal/errors/src/admin-error.ts
 var ADMIN_ERROR_CODES = {
   permission: [
     "tenant_mismatch",
@@ -268,7 +583,7 @@ var CLI_I18N_KO = {
   RetiredHexCredentialsRejected: "\uC774\uC804 hex \uC790\uACA9 \uC99D\uBA85\uC740 \uB354 \uC774\uC0C1 \uD5C8\uC6A9\uB418\uC9C0 \uC54A\uC2B5\uB2C8\uB2E4 \u2014 `01 login`\uC73C\uB85C \uB2E4\uC2DC \uC778\uC99D\uD558\uC138\uC694.",
   InvalidJsonObject: "`--{{label}}` \uC778\uC790\uB294 JSON \uAC1D\uCCB4\uC5EC\uC57C \uD569\uB2C8\uB2E4.",
   InvalidJsonArray: "`--{{label}}` \uC778\uC790\uB294 JSON \uBC30\uC5F4\uC774\uC5B4\uC57C \uD569\uB2C8\uB2E4.",
-  InvalidJsonValue: "`--{{label}}` \uC778\uC790\uC758 JSON \uD615\uC2DD\uC774 \uC62C\uBC14\uB974\uC9C0 \uC54A\uC2B5\uB2C8\uB2E4: {{value}}",
+  InvalidJsonValue: "`--{{label}}` \uC778\uC790\uC758 JSON \uD615\uC2DD\uC774 \uC62C\uBC14\uB974\uC9C0 \uC54A\uC2B5\uB2C8\uB2E4.",
   Empty: "(\uC5C6\uC74C)",
   Total: "\uCD1D {{n}}\uAC1C",
   PageOf: "{{page}} / {{total}} \uD398\uC774\uC9C0",
@@ -300,7 +615,7 @@ var CLI_I18N_EN = {
   RetiredHexCredentialsRejected: "Retired hex credentials are no longer accepted \u2014 run `01 login` to re-authenticate.",
   InvalidJsonObject: "--{{label}} must be a JSON object.",
   InvalidJsonArray: "--{{label}} must be a JSON array.",
-  InvalidJsonValue: "Invalid JSON for --{{label}}: {{value}}",
+  InvalidJsonValue: "Invalid JSON for --{{label}}.",
   Empty: "(empty)",
   Total: "{{n}} total",
   PageOf: "page {{page}}/{{total}}",
@@ -552,40 +867,24 @@ function parseSelect(input) {
 }
 
 // src/lib/parse.ts
-function failArg(label, value, expectedKind) {
-  const message = expectedKind === "object" ? t("InvalidJsonObject", { label }) : expectedKind === "array" ? t("InvalidJsonArray", { label }) : t("InvalidJsonValue", { label, value });
+function failArg(label, _value, expectedKind) {
+  const message = expectedKind === "object" ? t("InvalidJsonObject", { label }) : expectedKind === "array" ? t("InvalidJsonArray", { label }) : t("InvalidJsonValue", { label });
   exitWithError({
     type: "validation",
     code: "invalid_argument",
     field: label,
-    // `message` is read by `printError` for the stderr headline so the
-    // user sees the label/value in the one-line summary; `detail` carries
-    // the structured fields for `--format json` consumers.
+    // Keep rejected values out of terminal and structured output. `message`
+    // is the stderr headline; `detail` carries only the stable field label for
+    // machine consumers.
     message,
-    detail: { message, value, field: label }
+    detail: { message, field: label }
   });
 }
-function stringifyValue(value) {
-  try {
-    return JSON.stringify(value);
-  } catch {
-    return String(value);
-  }
-}
-function formatSchemaIssues(label, issues) {
-  return issues.map((issue) => {
-    const path = issue.path.length > 0 ? issue.path.join(".") : label;
-    return `${path}: ${issue.message}`;
-  }).join("; ");
-}
 function parseWithSchema(value, label, schema) {
   const parsed = schema.safeParse(value);
   if (parsed.success) return parsed.data;
-  const issues = parsed.error.issues.map((issue) => ({
-    path: issue.path.map(String),
-    message: issue.message
-  }));
-  const message = `Invalid value for --${label}: ${formatSchemaIssues(label, issues)}`;
+  const issues = parsed.error.issues.map((issue) => ({ code: issue.code }));
+  const message = `Invalid value for --${label}.`;
   exitWithError({
     type: "validation",
     code: "invalid_argument",
@@ -593,7 +892,6 @@ function parseWithSchema(value, label, schema) {
     message,
     detail: {
       message,
-      value: stringifyValue(value),
       field: label,
       issues
     }
@@ -804,7 +1102,7 @@ function registerCrudCommands(program2, getClient2, getFormat2) {
   });
 }
 
-// ../contracts/src/tenant/index.ts
+// ../../internal/contracts/src/tenant/index.ts
 import { z } from "zod";
 var tenantFieldConfigStateSchema = z.object({
   hiddenFields: z.array(z.string()),
@@ -953,10 +1251,10 @@ var collectionSchemaResponseSchema = z.object({
   }).strict()
 }).strict();
 
-// ../contracts/src/ecommerce/index.ts
-import { z as z4 } from "zod";
+// ../../internal/contracts/src/ecommerce/index.ts
+import { z as z7 } from "zod";
 
-// ../contracts/src/ecommerce/product-upsert.ts
+// ../../internal/contracts/src/ecommerce/product-upsert.ts
 import { z as z2 } from "zod";
 var IdSchema = z2.union([z2.string(), z2.number()]).transform(String);
 var RemovedLegacyMediaFieldSchema = z2.unknown().optional();
@@ -980,6 +1278,7 @@ var productFieldShape = {
   publishedAt: z2.string().optional().nullable(),
   categories: z2.array(IdSchema).optional(),
   tags: z2.array(IdSchema).optional(),
+  markets: z2.array(IdSchema).optional().nullable(),
   seo: z2.object({
     title: z2.string().optional().nullable(),
     description: z2.string().optional().nullable()
@@ -1035,6 +1334,26 @@ var VariantOptionValueObjectSchema = z2.object({
 }).refine((data) => Boolean(data.valueSlug ?? data.valueId ?? data.value), {
   message: "Variant option value object requires valueSlug, valueId, or value"
 });
+var MAX_CATALOG_AMOUNT_DECIMAL_PLACES = 2;
+function catalogAmountDecimalPlaces(value) {
+  if (!Number.isFinite(value)) return 0;
+  const text = String(value);
+  const exponential = text.indexOf("e-");
+  if (exponential !== -1) return Number(text.slice(exponential + 2)) || 0;
+  const dot = text.indexOf(".");
+  return dot === -1 ? 0 : text.length - dot - 1;
+}
+var CatalogAmountSchema = z2.number().min(0).refine(
+  (value) => catalogAmountDecimalPlaces(value) <= MAX_CATALOG_AMOUNT_DECIMAL_PLACES,
+  {
+    message: `Amount must have at most ${MAX_CATALOG_AMOUNT_DECIMAL_PLACES} decimal places; the store currency may allow fewer.`
+  }
+);
+var VariantMarketPriceInputSchema = z2.object({
+  market: IdSchema,
+  price: CatalogAmountSchema,
+  compareAtPrice: CatalogAmountSchema.optional().nullable()
+});
 var VariantInputSchema = z2.object({
   id: IdSchema.optional(),
   optionValues: z2.union([
@@ -1046,8 +1365,8 @@ var VariantInputSchema = z2.object({
   ]).optional(),
   sku: z2.string().optional().nullable(),
   title: z2.string().optional().nullable(),
-  price: z2.number().min(0),
-  compareAtPrice: z2.number().min(0).optional().nullable(),
+  price: CatalogAmountSchema,
+  compareAtPrice: CatalogAmountSchema.optional().nullable(),
   stock: z2.number().int().min(0).optional(),
   isUnlimited: z2.boolean().optional(),
   inventoryPolicy: z2.enum(["deny", "continue"]).optional(),
@@ -1057,6 +1376,7 @@ var VariantInputSchema = z2.object({
   externalId: z2.string().optional().nullable(),
   isActive: z2.boolean().optional(),
   images: z2.array(IdSchema).optional(),
+  marketPrices: z2.array(VariantMarketPriceInputSchema).optional(),
   thumbnail: RemovedLegacyMediaFieldSchema,
   featuredMediaItemId: RemovedLegacyMediaFieldSchema,
   metadata: z2.unknown().optional()
@@ -1109,260 +1429,1035 @@ var ProductUpsertSchema = ProductUpsertObjectSchema.superRefine(
   }
 );
 
-// ../contracts/src/ecommerce/checkout.ts
+// ../../internal/contracts/src/ecommerce/cart.ts
+import { z as z4 } from "zod";
+
+// ../../internal/contracts/src/ecommerce/commerce-common.ts
 import { z as z3 } from "zod";
-var providerSlugSchema = z3.string().trim().regex(/^[a-z0-9][a-z0-9_-]{0,63}$/, "pgProvider must be lowercase slug");
-var CheckoutShippingAddressSchema = z3.object({
-  recipientName: z3.string().min(1),
-  phone: z3.string().min(1),
-  postalCode: z3.string().min(1),
-  address: z3.string().min(1),
-  detailAddress: z3.string().min(1),
-  deliveryMessage: z3.string().optional()
+var currencyCodeSchema = z3.string().regex(
+  /^[A-Z]{3}$/,
+  "currency must be a three-letter uppercase ISO 4217 code"
+);
+var minorAmountSchema = z3.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER);
+var moneySchema = z3.object({
+  amountMinor: minorAmountSchema,
+  currency: currencyCodeSchema
+}).strict();
+var MAX_COMMERCE_EXTENSION_ENTRIES = 50;
+var MAX_COMMERCE_EXTENSION_KEY_LENGTH = 40;
+var MAX_COMMERCE_EXTENSION_VALUE_LENGTH = 500;
+var MAX_COMMERCE_RESOURCE_ID_LENGTH = 255;
+var MAX_COMMERCE_CAPABILITY_LENGTH = 512;
+var MAX_COMMERCE_CUSTOMER_TOKEN_LENGTH = 4096;
+var MAX_COMMERCE_SHORT_TEXT_LENGTH = 200;
+var MAX_COMMERCE_ADDRESS_LENGTH = 500;
+var MAX_COMMERCE_EMAIL_LENGTH = 254;
+var MAX_COMMERCE_PHONE_LENGTH = 32;
+var MAX_COMMERCE_POSTAL_CODE_LENGTH = 32;
+var commerceResourceIdSchema = z3.string().min(1).max(MAX_COMMERCE_RESOURCE_ID_LENGTH);
+var commerceCapabilitySchema = z3.string().min(1).max(MAX_COMMERCE_CAPABILITY_LENGTH);
+var commerceCustomerTokenSchema = z3.string().min(1).max(MAX_COMMERCE_CUSTOMER_TOKEN_LENGTH);
+var publicAttributeKeySchema = z3.string().min(1).max(MAX_COMMERCE_EXTENSION_KEY_LENGTH).refine((key) => !key.startsWith("__"), {
+  message: "attribute key uses a reserved platform prefix"
+});
+var publicAttributeSchema = z3.object({
+  key: publicAttributeKeySchema,
+  value: z3.string().max(MAX_COMMERCE_EXTENSION_VALUE_LENGTH)
+}).strict();
+var publicAttributesSchema = z3.array(publicAttributeSchema).max(MAX_COMMERCE_EXTENSION_ENTRIES).superRefine((attributes, ctx) => {
+  const seen = /* @__PURE__ */ new Set();
+  attributes.forEach(({ key }, index) => {
+    if (seen.has(key)) {
+      ctx.addIssue({
+        code: "custom",
+        path: [index, "key"],
+        message: "attribute keys must be unique"
+      });
+    }
+    seen.add(key);
+  });
 });
-var CheckoutCustomerSnapshotSchema = z3.object({
-  name: z3.string().optional(),
-  email: z3.string().email("Invalid email format"),
-  phone: z3.string().optional()
+var integrationMetadataKeySchema = z3.string().min(1).max(MAX_COMMERCE_EXTENSION_KEY_LENGTH).refine((key) => !key.includes("[") && !key.includes("]"), {
+  message: "integration metadata keys must not use bracket notation"
 });
-var CheckoutRequestSchema = z3.object({
-  cartId: z3.union([z3.string(), z3.number()]).transform(String),
-  cartToken: z3.string().min(1).optional(),
-  pgPaymentId: z3.string().min(1).optional(),
-  pgProvider: providerSlugSchema.optional(),
-  orderNumber: z3.string().min(1, "orderNumber is required"),
-  customerSnapshot: CheckoutCustomerSnapshotSchema,
-  shippingAddress: CheckoutShippingAddressSchema.optional(),
-  discountCode: z3.string().optional()
-}).superRefine((data, ctx) => {
-  if (data.pgPaymentId && !data.pgProvider) {
+var integrationMetadataSchema = z3.record(
+  integrationMetadataKeySchema,
+  z3.string().max(MAX_COMMERCE_EXTENSION_VALUE_LENGTH)
+).superRefine((metadata, ctx) => {
+  if (Object.keys(metadata).length > MAX_COMMERCE_EXTENSION_ENTRIES) {
     ctx.addIssue({
-      code: z3.ZodIssueCode.custom,
-      path: ["pgProvider"],
-      message: "pgProvider is required when pgPaymentId is provided"
+      code: "too_big",
+      origin: "object",
+      maximum: MAX_COMMERCE_EXTENSION_ENTRIES,
+      inclusive: true,
+      message: `integration metadata cannot contain more than ${MAX_COMMERCE_EXTENSION_ENTRIES} entries`
     });
   }
-  if (data.pgProvider && !data.pgPaymentId) {
+});
+var customerSnapshotSchema = z3.object({
+  email: z3.string().email().max(MAX_COMMERCE_EMAIL_LENGTH),
+  name: z3.string().min(1).max(MAX_COMMERCE_SHORT_TEXT_LENGTH).optional(),
+  phone: z3.string().min(1).max(MAX_COMMERCE_PHONE_LENGTH).optional()
+}).strict();
+var checkoutShippingAddressSchema = z3.object({
+  recipientName: z3.string().min(1).max(MAX_COMMERCE_SHORT_TEXT_LENGTH),
+  phone: z3.string().min(1).max(MAX_COMMERCE_PHONE_LENGTH),
+  countryCode: z3.string().trim().length(2).optional(),
+  regionCode: z3.string().trim().min(1).max(64).optional(),
+  postalCode: z3.string().min(1).max(MAX_COMMERCE_POSTAL_CODE_LENGTH),
+  address: z3.string().min(1).max(MAX_COMMERCE_ADDRESS_LENGTH),
+  detailAddress: z3.string().min(1).max(MAX_COMMERCE_ADDRESS_LENGTH),
+  deliveryMessage: z3.string().max(MAX_COMMERCE_EXTENSION_VALUE_LENGTH).optional()
+}).strict();
+var commerceIdempotencyKeySchema = z3.string().max(255).refine(
+  (value) => /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(
+    value
+  ) || /^ik_[A-Za-z0-9_-]{22}$/.test(value),
+  "idempotencyKey must be a UUIDv4 or ik_-prefixed 128-bit base64url value"
+);
+
+// ../../internal/contracts/src/ecommerce/cart.ts
+var MAX_CART_LINE_QUANTITY = 99;
+var MAX_CART_DISCOUNT_CODES = 250;
+var MAX_CART_DISCOUNT_CODE_LENGTH = 128;
+var cartDiscountCodeSchema = z4.object({
+  code: z4.string().min(1).max(MAX_CART_DISCOUNT_CODE_LENGTH),
+  applicable: z4.boolean()
+}).strict();
+var CART_WARNING_CODES = [
+  "DISCOUNT_CODE_NOT_HONOURED",
+  "DISCOUNT_CURRENTLY_INACTIVE",
+  "DISCOUNT_CUSTOMER_NOT_ELIGIBLE",
+  "DISCOUNT_CUSTOMER_USAGE_LIMIT_REACHED",
+  "DISCOUNT_ELIGIBLE_CUSTOMER_MISSING",
+  "DISCOUNT_NO_ENTITLED_LINE_ITEMS",
+  "DISCOUNT_NO_ENTITLED_SHIPPING_LINES",
+  "DISCOUNT_NOT_FOUND",
+  "DISCOUNT_PURCHASE_NOT_IN_RANGE",
+  "DISCOUNT_USAGE_LIMIT_REACHED",
+  "MERCHANDISE_NOT_ENOUGH_STOCK",
+  "MERCHANDISE_OUT_OF_STOCK"
+];
+var cartWarningCodeSchema = z4.enum(CART_WARNING_CODES);
+var cartWarningSchema = z4.object({
+  code: cartWarningCodeSchema,
+  message: z4.string().min(1),
+  target: z4.string().min(1)
+}).strict();
+var updateDiscountCodesBodySchema = z4.object({
+  cartToken: commerceCapabilitySchema,
+  expectedRevision: z4.number().int().nonnegative(),
+  discountCodes: z4.array(z4.string().trim().min(1).max(MAX_CART_DISCOUNT_CODE_LENGTH)).max(
+    MAX_CART_DISCOUNT_CODES,
+    `discountCodes cannot contain more than ${MAX_CART_DISCOUNT_CODES} values`
+  )
+}).strict();
+var updateDiscountCodesParamsSchema = updateDiscountCodesBodySchema.extend({
+  idempotencyKey: commerceIdempotencyKeySchema
+});
+var MAX_CART_LINE_ADMISSIONS = 32;
+var publicMediaSizeSchema = z4.object({
+  width: z4.number().nullable().optional(),
+  height: z4.number().nullable().optional(),
+  mimeType: z4.string().nullable().optional(),
+  filename: z4.string().nullable().optional(),
+  url: z4.string().nullable().optional()
+}).strict();
+var publicMediaAssetSchema = z4.union([
+  z4.string(),
+  z4.object({
+    id: z4.union([z4.string(), z4.number()]).nullable().optional(),
+    alt: z4.string().nullable().optional(),
+    width: z4.number().nullable().optional(),
+    height: z4.number().nullable().optional(),
+    mimeType: z4.string().nullable().optional(),
+    filename: z4.string().nullable().optional(),
+    url: z4.string().nullable().optional(),
+    sizes: z4.record(z4.string(), publicMediaSizeSchema).optional()
+  }).strict()
+]);
+var publicCartReferenceSchema = z4.object({
+  id: z4.string().min(1),
+  title: z4.string().min(1),
+  handle: z4.string().min(1).nullable(),
+  image: publicMediaAssetSchema.nullable()
+}).strict();
+var publicCartMarketSchema = z4.object({
+  id: z4.string().min(1),
+  handle: z4.string().min(1),
+  name: z4.string().min(1)
+}).strict();
+var publicCartItemAdmissionSchema = z4.object({
+  eventId: z4.string().min(1),
+  occurrenceId: z4.string().min(1),
+  admissionTypeId: z4.string().min(1)
+}).strict();
+var cartLineAdmissionsInputSchema = z4.array(publicCartItemAdmissionSchema).max(
+  MAX_CART_LINE_ADMISSIONS,
+  `admissions cannot contain more than ${MAX_CART_LINE_ADMISSIONS} values`
+).min(1, "admissions must contain at least one value").superRefine((admissions, ctx) => {
+  const seen = /* @__PURE__ */ new Set();
+  admissions.forEach((admission, index) => {
+    const key = `${admission.eventId}:${admission.occurrenceId}:${admission.admissionTypeId}`;
+    if (seen.has(key)) {
+      ctx.addIssue({
+        code: "custom",
+        path: [index],
+        message: "admissions must be unique"
+      });
+    }
+    seen.add(key);
+  });
+});
+var cartTokenField = z4.string().min(1, "cartToken is required");
+var cartMarketField = z4.string().trim().min(1).optional();
+var cartEntityIdField = z4.union([z4.string(), z4.number()]).transform(String);
+var createCartSchema = z4.object({
+  market: cartMarketField,
+  attributes: publicAttributesSchema.optional()
+}).strict();
+var getCartSchema = z4.object({ cartToken: cartTokenField }).strict();
+var addCartItemSchema = z4.object({
+  cartToken: cartTokenField,
+  product: cartEntityIdField,
+  variant: cartEntityIdField,
+  option: cartEntityIdField.optional(),
+  quantity: z4.number().int().positive("quantity must be a positive integer"),
+  market: cartMarketField,
+  admissions: cartLineAdmissionsInputSchema.optional()
+}).strict();
+var updateCartItemSchema = z4.object({
+  cartToken: cartTokenField,
+  cartItemId: cartEntityIdField,
+  quantity: z4.number().int().positive("quantity must be a positive integer")
+}).strict();
+var removeCartItemSchema = z4.object({
+  cartToken: cartTokenField,
+  cartItemId: cartEntityIdField
+}).strict();
+var updateCartAttributesSchema = z4.object({
+  cartToken: cartTokenField,
+  attributes: publicAttributesSchema
+}).strict();
+var clearCartSchema = z4.object({ cartToken: cartTokenField }).strict();
+function compareAdmissions(left, right) {
+  for (const field of ["eventId", "occurrenceId", "admissionTypeId"]) {
+    if (left[field] < right[field]) return -1;
+    if (left[field] > right[field]) return 1;
+  }
+  return 0;
+}
+var publicCartItemAdmissionsSchema = z4.array(publicCartItemAdmissionSchema).max(MAX_CART_LINE_ADMISSIONS).superRefine((admissions, ctx) => {
+  let previous;
+  admissions.forEach((admission, index) => {
+    const comparison = previous ? compareAdmissions(admission, previous) : void 0;
+    if (comparison !== void 0 && comparison <= 0) {
+      ctx.addIssue({
+        code: "custom",
+        path: [index],
+        message: comparison === 0 ? "admissions must be unique" : "admissions must be in canonical order"
+      });
+    }
+    previous = admission;
+  });
+});
+var publicCartItemSchema = z4.object({
+  id: z4.string().min(1),
+  product: publicCartReferenceSchema,
+  variant: publicCartReferenceSchema,
+  admissions: publicCartItemAdmissionsSchema,
+  quantity: z4.number().int().positive().max(MAX_CART_LINE_QUANTITY),
+  unitPriceMinor: minorAmountSchema,
+  discountMinor: minorAmountSchema,
+  estimatedLineTotalMinor: minorAmountSchema,
+  requiresShipping: z4.boolean()
+}).strict().superRefine((item, ctx) => {
+  const expectedLineTotal = BigInt(item.unitPriceMinor) * BigInt(item.quantity) - BigInt(item.discountMinor);
+  if (expectedLineTotal < 0n) {
     ctx.addIssue({
-      code: z3.ZodIssueCode.custom,
-      path: ["pgPaymentId"],
-      message: "pgPaymentId is required when pgProvider is provided"
+      code: "custom",
+      path: ["discountMinor"],
+      message: "discountMinor cannot exceed the undiscounted line total"
+    });
+    return;
+  }
+  if (BigInt(item.estimatedLineTotalMinor) !== expectedLineTotal) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["estimatedLineTotalMinor"],
+      message: "estimatedLineTotalMinor must equal unitPriceMinor * quantity - discountMinor"
     });
   }
 });
+var publicCartSchema = z4.object({
+  id: z4.string().min(1),
+  status: z4.enum(["active", "completed", "abandoned"]),
+  revision: z4.number().int().nonnegative(),
+  currency: currencyCodeSchema,
+  market: publicCartMarketSchema,
+  subtotalMinor: minorAmountSchema,
+  discountMinor: minorAmountSchema,
+  estimatedTotalMinor: minorAmountSchema,
+  discountCodes: z4.array(cartDiscountCodeSchema),
+  attributes: publicAttributesSchema,
+  items: z4.array(publicCartItemSchema),
+  expiresAt: z4.string().datetime({ offset: true }),
+  createdAt: z4.string().datetime({ offset: true }),
+  updatedAt: z4.string().datetime({ offset: true })
+}).strict().superRefine((cart, ctx) => {
+  const expectedSubtotal = cart.items.reduce(
+    (total, item) => total + BigInt(item.unitPriceMinor) * BigInt(item.quantity),
+    0n
+  );
+  const expectedTotal = expectedSubtotal - BigInt(cart.discountMinor);
+  const expectedDiscount = cart.items.reduce(
+    (total, item) => total + BigInt(item.discountMinor),
+    0n
+  );
+  if (BigInt(cart.subtotalMinor) !== expectedSubtotal) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["subtotalMinor"],
+      message: "subtotalMinor must equal the sum of undiscounted cart line totals"
+    });
+  }
+  if (BigInt(cart.discountMinor) !== expectedDiscount) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["discountMinor"],
+      message: "discountMinor must equal the sum of cart line discounts"
+    });
+  }
+  if (expectedTotal < 0n) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["discountMinor"],
+      message: "discountMinor cannot exceed subtotalMinor"
+    });
+  } else if (BigInt(cart.estimatedTotalMinor) !== expectedTotal) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["estimatedTotalMinor"],
+      message: "estimatedTotalMinor must equal subtotalMinor - discountMinor"
+    });
+  }
+});
+var cartMutationResultSchema = z4.object({
+  cart: publicCartSchema,
+  warnings: z4.array(cartWarningSchema)
+}).strict();
+var createCartParamsSchema = z4.object({
+  market: commerceResourceIdSchema.optional(),
+  attributes: publicAttributesSchema.optional()
+}).strict();
+var createCartResultSchema = z4.object({
+  cart: publicCartSchema,
+  warnings: z4.array(cartWarningSchema),
+  cartToken: commerceCapabilitySchema
+}).strict().superRefine((result, ctx) => {
+  if (result.cart.revision !== 0) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["cart", "revision"],
+      message: "a newly created Cart must start at revision 0"
+    });
+  }
+});
+var retrieveCartParamsSchema = z4.object({ cartToken: commerceCapabilitySchema }).strict();
+var addItemAdmissionsSchema = z4.tuple([publicCartItemAdmissionSchema], publicCartItemAdmissionSchema).readonly().superRefine((admissions, ctx) => {
+  if (admissions.length > MAX_CART_LINE_ADMISSIONS) {
+    ctx.addIssue({
+      code: "too_big",
+      origin: "array",
+      maximum: MAX_CART_LINE_ADMISSIONS,
+      inclusive: true,
+      message: `admissions cannot contain more than ${MAX_CART_LINE_ADMISSIONS} values`
+    });
+  }
+  admissions.forEach((admission, index) => {
+    if (index === 0) return;
+    const comparison = compareAdmissions(admission, admissions[index - 1]);
+    if (comparison <= 0) {
+      ctx.addIssue({
+        code: "custom",
+        path: [index],
+        message: comparison === 0 ? "admissions must be unique" : "admissions must be in canonical order"
+      });
+    }
+  });
+});
+var addItemBodySchema = z4.object({
+  cartToken: commerceCapabilitySchema,
+  expectedRevision: z4.number().int().nonnegative(),
+  productId: commerceResourceIdSchema,
+  variantId: commerceResourceIdSchema,
+  quantity: z4.number().int().positive().max(MAX_CART_LINE_QUANTITY),
+  admissions: addItemAdmissionsSchema.optional()
+}).strict();
+var addItemParamsSchema = addItemBodySchema.extend({
+  idempotencyKey: commerceIdempotencyKeySchema
+});
+var updateItemBodySchema = z4.object({
+  cartToken: commerceCapabilitySchema,
+  expectedRevision: z4.number().int().nonnegative(),
+  cartItemId: commerceResourceIdSchema,
+  quantity: z4.number().int().positive().max(MAX_CART_LINE_QUANTITY)
+}).strict();
+var updateItemParamsSchema = updateItemBodySchema.extend({
+  idempotencyKey: commerceIdempotencyKeySchema
+});
+var removeItemBodySchema = z4.object({
+  cartToken: commerceCapabilitySchema,
+  expectedRevision: z4.number().int().nonnegative(),
+  cartItemId: commerceResourceIdSchema
+}).strict();
+var removeItemParamsSchema = removeItemBodySchema.extend({
+  idempotencyKey: commerceIdempotencyKeySchema
+});
+var clearCartBodySchema = z4.object({
+  cartToken: commerceCapabilitySchema,
+  expectedRevision: z4.number().int().nonnegative()
+}).strict();
+var clearCartParamsSchema = clearCartBodySchema.extend({
+  idempotencyKey: commerceIdempotencyKeySchema
+});
+var updateCartAttributesBodySchema = z4.object({
+  cartToken: commerceCapabilitySchema,
+  expectedRevision: z4.number().int().nonnegative(),
+  attributes: publicAttributesSchema
+}).strict();
+var updateCartAttributesParamsSchema = updateCartAttributesBodySchema.extend({
+  idempotencyKey: commerceIdempotencyKeySchema
+});
 
-// ../contracts/src/ecommerce/index.ts
-var transactionStatusSchema = z4.enum([
-  "pending",
-  "paid",
-  "failed",
-  "canceled",
-  "refunded"
-]);
-var financialStatusSchema = z4.enum([
-  "pending",
-  "paid",
-  "canceled",
-  "partially_refunded",
-  "refunded"
-]);
-var orderDisplayFinancialStatusSchema = z4.enum([
-  "pending",
-  "paid",
-  "partially_refunded",
-  "refunded",
-  "voided"
-]);
-var confirmationStatusSchema = z4.enum(["unconfirmed", "confirmed"]);
-var fulfillmentOrderStatusSchema = z4.enum([
-  "open",
-  "in_progress",
-  "on_hold",
-  "canceled",
-  "closed"
+// ../../internal/contracts/src/ecommerce/checkout.ts
+import { z as z6 } from "zod";
+
+// ../../internal/contracts/src/ecommerce/payment-session.ts
+import { z as z5 } from "zod";
+var tossProviderOrderIdSchema = z5.string().min(6).max(64).regex(
+  /^[A-Za-z0-9_-]+$/,
+  "providerOrderId may contain only ASCII letters, digits, underscores, and hyphens"
+);
+var accountAliasUuidV4Schema = z5.string().regex(
+  /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i,
+  "providerCustomerKey must be ANONYMOUS or a UUIDv4 account alias"
+);
+var tossProviderCustomerKeySchema = z5.union([
+  z5.literal("ANONYMOUS"),
+  accountAliasUuidV4Schema
 ]);
-var shipmentStatusSchema = z4.enum([
-  "pending",
-  "shipped",
-  "delivered",
-  "canceled",
-  "failed"
+var createPaymentSessionBaseBodyShape = {
+  checkoutToken: commerceCapabilitySchema
+};
+var createTossPaymentSessionBodySchema = z5.object({
+  ...createPaymentSessionBaseBodyShape,
+  provider: z5.literal("toss"),
+  providerOptions: z5.object({ profile: z5.literal("widget_v2") }).strict()
+}).strict();
+var createPaymentSessionParamsSchema = createTossPaymentSessionBodySchema.extend({
+  idempotencyKey: commerceIdempotencyKeySchema
+});
+var retrieveBrowserPaymentSessionParamsSchema = z5.object({
+  paymentSessionId: commerceResourceIdSchema,
+  checkoutToken: commerceCapabilitySchema
+}).strict();
+var retrieveServerPaymentSessionParamsSchema = z5.object({ paymentSessionId: commerceResourceIdSchema }).strict();
+var cancelBrowserPaymentSessionBodySchema = z5.object({
+  paymentSessionId: commerceResourceIdSchema,
+  checkoutToken: commerceCapabilitySchema
+}).strict();
+var cancelBrowserPaymentSessionParamsSchema = cancelBrowserPaymentSessionBodySchema.extend({
+  idempotencyKey: commerceIdempotencyKeySchema
+});
+var cancelServerPaymentSessionBodySchema = z5.object({
+  paymentSessionId: commerceResourceIdSchema
+}).strict();
+var cancelServerPaymentSessionParamsSchema = cancelServerPaymentSessionBodySchema.extend({
+  idempotencyKey: commerceIdempotencyKeySchema
+});
+var cancelPaymentSessionParamsSchema = z5.union([
+  cancelBrowserPaymentSessionParamsSchema,
+  cancelServerPaymentSessionParamsSchema
 ]);
-var orderDisplayFulfillmentStatusSchema = z4.enum([
-  "unfulfilled",
-  "in_progress",
-  "on_hold",
-  "partially_fulfilled",
-  "shipped",
-  "fulfilled",
+var confirmTossPaymentSessionBodySchema = z5.object({
+  paymentSessionId: commerceResourceIdSchema,
+  action: z5.object({
+    type: z5.literal("toss_authorization"),
+    paymentKey: z5.string().min(1).max(512),
+    providerOrderId: tossProviderOrderIdSchema
+  }).strict()
+}).strict();
+var confirmTossPaymentSessionParamsSchema = confirmTossPaymentSessionBodySchema.extend({
+  idempotencyKey: commerceIdempotencyKeySchema
+});
+var customPaymentProviderSchema = z5.string().trim().min(1).max(64).regex(/^[a-z0-9][a-z0-9_-]{0,63}$/i, "provider must be a slug");
+var customPaymentIdentitySchema = z5.string().trim().min(1);
+var customPaymentCurrencyInputSchema = z5.string().trim().min(1).regex(/^[A-Za-z]{3}$/, "currency must be a three-letter ISO 4217 code").transform((currency) => currency.toUpperCase());
+var createCustomPaymentSessionBodySchema = z5.object({
+  provider: customPaymentProviderSchema,
+  checkoutToken: commerceCapabilitySchema
+}).strict();
+var createCustomPaymentSessionParamsSchema = createCustomPaymentSessionBodySchema.extend({
+  idempotencyKey: commerceIdempotencyKeySchema
+});
+var customPaymentSessionSchema = z5.object({
+  id: commerceResourceIdSchema,
+  provider: customPaymentProviderSchema,
+  providerSessionId: customPaymentIdentitySchema,
+  money: moneySchema
+}).strict();
+var confirmCustomPaymentSessionBodySchema = z5.object({
+  provider: customPaymentProviderSchema,
+  providerSessionId: customPaymentIdentitySchema,
+  providerPaymentId: customPaymentIdentitySchema,
+  providerEventId: customPaymentIdentitySchema,
+  amount: z5.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER),
+  currency: customPaymentCurrencyInputSchema,
+  occurredAt: customPaymentIdentitySchema
+}).strict();
+var confirmCustomPaymentSessionResponseSchema = z5.object({
+  orderId: commerceResourceIdSchema,
+  transactionId: commerceResourceIdSchema,
+  status: z5.literal("paid"),
+  alreadyConfirmed: z5.boolean().optional()
+}).strict();
+var paymentNextActionSchema = z5.object({
+  type: z5.literal("toss_widget"),
+  clientKey: z5.string().min(1).max(255),
+  paymentMethodVariantKey: z5.string().min(1).max(255),
+  agreementVariantKey: z5.string().min(1).max(255),
+  providerOrderId: tossProviderOrderIdSchema,
+  providerCustomerKey: tossProviderCustomerKeySchema,
+  orderName: z5.string().min(1).max(200),
+  customerName: z5.string().min(1).max(200).optional(),
+  customerEmail: z5.string().email().max(254).optional()
+}).strict();
+var PAYMENT_SESSION_ROLES = [
+  "active",
+  "canonical_candidate",
+  "canonical",
+  "residual",
+  "historical"
+];
+var paymentSessionRoleSchema = z5.enum(PAYMENT_SESSION_ROLES);
+var PAYMENT_PROVIDER_STATUSES = [
+  "requires_payment_method",
+  "requires_action",
+  "requires_confirmation",
+  "initializing",
+  "processing",
+  "authorized",
+  "canceling",
+  "unknown",
+  "captured",
+  "failed",
   "canceled"
-]);
-var orderReturnStatusSchema = z4.enum([
-  "no_return",
-  "return_requested",
-  "in_progress",
-  "returned"
-]);
-var orderStatusSchema = z4.enum([
-  "pending",
-  "paid",
-  "canceled",
-  "refunded",
-  "preparing",
-  "shipped",
-  "delivered",
-  "confirmed",
-  "return_requested",
-  "return_processing",
-  "returned"
-]);
-var entityIdSchema = z4.union([z4.string().min(1), z4.number()]).transform(String);
-var createOrderItemSchema = z4.object({
-  // `product` and `option` are storefront-optional: the create-order
-  // endpoint derives the product from the variant's parent and snapshots
-  // option selection from the variant.
-  product: entityIdSchema.optional(),
-  variant: entityIdSchema,
-  option: entityIdSchema.optional(),
-  quantity: z4.number().int().positive("quantity must be a positive integer"),
-  unitPrice: z4.number().optional(),
-  totalPrice: z4.number().optional()
+];
+var paymentProviderStatusSchema = z5.enum(PAYMENT_PROVIDER_STATUSES);
+var PAYMENT_RECONCILIATION_REASONS = [
+  "provider_outcome_unknown",
+  "local_commit_ambiguous",
+  "amount_mismatch",
+  "currency_mismatch",
+  "excess_capture_pending_order",
+  "inventory_unavailable",
+  "admission_unavailable",
+  "excess_capture",
+  "late_capture",
+  "cross_checkout_duplicate"
+];
+var paymentReconciliationReasonSchema = z5.enum(
+  PAYMENT_RECONCILIATION_REASONS
+);
+function requiredReconciliationSchema(reasons) {
+  const reasonSchema = z5.enum(reasons);
+  return z5.object({
+    status: z5.literal("required"),
+    reasons: z5.array(reasonSchema).min(1).readonly()
+  }).strict().superRefine((value, ctx) => {
+    const indexes = new Map(reasons.map((reason, index) => [reason, index]));
+    let previous = -1;
+    value.reasons.forEach((reason, index) => {
+      const current = indexes.get(reason) ?? -1;
+      if (current <= previous) {
+        ctx.addIssue({
+          code: "custom",
+          path: ["reasons", index],
+          message: "reconciliation reasons must be unique and canonical-sorted"
+        });
+      }
+      previous = current;
+    });
+  });
+}
+var noReconciliationSchema = z5.object({ status: z5.literal("none") }).strict();
+var publicCaptureEvidenceSchema = z5.object({
+  amountMinor: z5.number().int().nonnegative(),
+  currency: currencyCodeSchema,
+  observedAt: z5.string().datetime({ offset: true })
+}).strict();
+var reconciliationRefundEvidenceSchema = z5.object({
+  providerRefundId: z5.string().min(1),
+  money: moneySchema,
+  observedAt: z5.string().datetime({ offset: true })
+}).strict();
+var PAYMENT_FAILURE_REASONS = [
+  "payment_declined",
+  "authentication_failed",
+  "authorization_expired",
+  "payment_method_unavailable",
+  "provider_terminal_failure",
+  "unknown_provider_terminal_failure"
+];
+var paymentFailureReasonSchema = z5.enum(PAYMENT_FAILURE_REASONS);
+var orderReferenceSchema = z5.object({
+  id: z5.string().min(1),
+  orderNumber: z5.string().min(1)
+}).strict();
+var paymentSessionBaseShape = {
+  id: z5.string().min(1),
+  money: moneySchema,
+  expiresAt: z5.string().datetime({ offset: true }).nullable()
+};
+var suppressedNotReadyShape = {
+  presentationStatus: z5.literal("suppressed"),
+  finalizationStatus: z5.literal("not_ready"),
+  reconciliation: noReconciliationSchema,
+  order: z5.null()
+};
+function stateSchemas(nextAction) {
+  return [
+    z5.object({
+      providerStatus: z5.enum(["requires_payment_method", "requires_action"]),
+      sessionRole: z5.literal("active"),
+      presentationStatus: z5.literal("actionable"),
+      finalizationStatus: z5.literal("not_ready"),
+      nextAction,
+      reconciliation: noReconciliationSchema,
+      order: z5.null()
+    }),
+    z5.object({
+      providerStatus: z5.enum(["requires_payment_method", "requires_action"]),
+      sessionRole: z5.literal("residual"),
+      ...suppressedNotReadyShape
+    }),
+    z5.object({
+      providerStatus: z5.literal("requires_confirmation"),
+      sessionRole: z5.enum(["active", "residual"]),
+      ...suppressedNotReadyShape
+    }),
+    z5.object({
+      providerStatus: z5.enum(["initializing", "processing", "authorized"]),
+      sessionRole: z5.enum(["active", "residual"]),
+      ...suppressedNotReadyShape
+    }),
+    z5.object({
+      providerStatus: z5.literal("canceling"),
+      sessionRole: z5.enum(["active", "residual"]),
+      ...suppressedNotReadyShape
+    }),
+    z5.object({
+      providerStatus: z5.literal("unknown"),
+      sessionRole: z5.enum(["active", "residual"]),
+      presentationStatus: z5.literal("suppressed"),
+      finalizationStatus: z5.literal("not_ready"),
+      reconciliation: requiredReconciliationSchema([
+        "provider_outcome_unknown"
+      ]),
+      order: z5.null()
+    }),
+    z5.object({
+      providerStatus: z5.literal("captured"),
+      sessionRole: z5.enum(["canonical_candidate", "residual"]),
+      presentationStatus: z5.literal("suppressed"),
+      finalizationStatus: z5.literal("pending"),
+      reconciliation: noReconciliationSchema,
+      providerEvidence: publicCaptureEvidenceSchema,
+      order: z5.null()
+    }),
+    z5.object({
+      providerStatus: z5.literal("captured"),
+      sessionRole: z5.enum(["canonical", "historical"]),
+      presentationStatus: z5.literal("suppressed"),
+      finalizationStatus: z5.literal("committed"),
+      reconciliation: noReconciliationSchema,
+      providerEvidence: publicCaptureEvidenceSchema,
+      order: orderReferenceSchema
+    }),
+    z5.object({
+      providerStatus: z5.literal("captured"),
+      sessionRole: z5.enum(["canonical_candidate", "residual"]),
+      presentationStatus: z5.literal("suppressed"),
+      finalizationStatus: z5.literal("pending"),
+      reconciliation: requiredReconciliationSchema([
+        "local_commit_ambiguous",
+        "amount_mismatch",
+        "currency_mismatch",
+        "excess_capture_pending_order"
+      ]),
+      providerEvidence: publicCaptureEvidenceSchema,
+      order: z5.null()
+    }),
+    z5.object({
+      providerStatus: z5.literal("captured"),
+      sessionRole: z5.enum(["canonical", "residual"]),
+      presentationStatus: z5.literal("suppressed"),
+      finalizationStatus: z5.literal("committed"),
+      reconciliation: requiredReconciliationSchema([
+        "inventory_unavailable",
+        "admission_unavailable",
+        "amount_mismatch",
+        "currency_mismatch",
+        "excess_capture",
+        "late_capture",
+        "cross_checkout_duplicate"
+      ]),
+      providerEvidence: publicCaptureEvidenceSchema,
+      order: orderReferenceSchema
+    }),
+    z5.object({
+      providerStatus: z5.literal("failed"),
+      sessionRole: z5.literal("historical"),
+      presentationStatus: z5.literal("suppressed"),
+      finalizationStatus: z5.literal("not_ready"),
+      reconciliation: noReconciliationSchema,
+      failure: z5.object({
+        reason: paymentFailureReasonSchema,
+        message: z5.string().min(1).optional()
+      }).strict(),
+      order: z5.null()
+    }),
+    z5.object({
+      providerStatus: z5.literal("canceled"),
+      sessionRole: z5.literal("historical"),
+      presentationStatus: z5.literal("suppressed"),
+      finalizationStatus: z5.literal("not_ready"),
+      cancellationReason: z5.enum([
+        "expired",
+        "customer",
+        "operator",
+        "provider"
+      ]),
+      reconciliation: noReconciliationSchema,
+      order: z5.null()
+    })
+  ];
+}
+function providerSessionSchemas(action) {
+  return stateSchemas(action).map(
+    (state) => z5.object({
+      ...paymentSessionBaseShape,
+      provider: z5.literal("toss"),
+      ...state.shape
+    }).strict()
+  );
+}
+var publicPaymentSessionVariants = [
+  ...providerSessionSchemas(paymentNextActionSchema)
+];
+var publicPaymentSessionSchema = z5.union(publicPaymentSessionVariants);
+var CreatePaymentSessionParamsSchema = createPaymentSessionParamsSchema;
+var CancelServerPaymentSessionParamsSchema = cancelServerPaymentSessionParamsSchema;
+var ConfirmTossPaymentSessionParamsSchema = confirmTossPaymentSessionParamsSchema;
+
+// ../../internal/contracts/src/ecommerce/checkout.ts
+var canonicalPublicCheckoutItemSchema = z6.object({
+  id: z6.string().min(1),
+  product: publicCartReferenceSchema,
+  variant: publicCartReferenceSchema,
+  productTitle: z6.string().min(1),
+  variantTitle: z6.string().min(1).nullable(),
+  sku: z6.string().min(1).nullable(),
+  admissions: publicCartItemAdmissionsSchema,
+  quantity: z6.number().int().positive().max(MAX_CART_LINE_QUANTITY),
+  unitPriceMinor: minorAmountSchema,
+  discountMinor: minorAmountSchema,
+  lineTotalMinor: minorAmountSchema,
+  requiresShipping: z6.boolean()
+}).strict().superRefine((item, ctx) => {
+  const expectedLineTotal = BigInt(item.unitPriceMinor) * BigInt(item.quantity) - BigInt(item.discountMinor);
+  if (expectedLineTotal < 0n) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["discountMinor"],
+      message: "discountMinor cannot exceed the undiscounted line total"
+    });
+    return;
+  }
+  if (BigInt(item.lineTotalMinor) !== expectedLineTotal) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["lineTotalMinor"],
+      message: "lineTotalMinor must equal unitPriceMinor * quantity - discountMinor"
+    });
+  }
+});
+var checkoutAmountsSchema = z6.object({
+  currency: currencyCodeSchema,
+  subtotalMinor: minorAmountSchema,
+  shippingMinor: minorAmountSchema,
+  discountMinor: minorAmountSchema,
+  totalMinor: minorAmountSchema
+}).strict().superRefine((amounts, ctx) => {
+  const expectedTotal = BigInt(amounts.subtotalMinor) + BigInt(amounts.shippingMinor) - BigInt(amounts.discountMinor);
+  if (BigInt(amounts.totalMinor) !== expectedTotal) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["totalMinor"],
+      message: "totalMinor must equal subtotalMinor + shippingMinor - discountMinor"
+    });
+  }
+});
+var checkoutPaymentSessionRefSchema = z6.object({
+  id: z6.string().min(1),
+  provider: z6.literal("toss"),
+  providerStatus: paymentProviderStatusSchema
+}).strict();
+var openCheckoutPaymentStateSchema = z6.object({
+  activePaymentSession: checkoutPaymentSessionRefSchema.nullable()
 }).strict();
-var providerSlugSchema2 = z4.string().trim().regex(/^[a-z0-9][a-z0-9_-]{0,63}$/, "pgProvider must be lowercase slug");
-var createOrderSchema = z4.object({
-  pgPaymentId: z4.string().min(1).optional(),
-  pgProvider: providerSlugSchema2.optional(),
-  orderNumber: z4.string().min(1, "orderNumber is required"),
-  customer: entityIdSchema.optional(),
-  customerSnapshot: z4.object({
-    name: z4.string().optional(),
-    email: z4.string().email("Invalid email format"),
-    phone: z4.string().optional()
+var spentCheckoutPaymentStateSchema = z6.object({
+  activePaymentSession: z6.null()
+}).strict();
+var lightweightOrderReferenceSchema = z6.object({
+  id: z6.string().min(1),
+  orderNumber: z6.string().min(1)
+}).strict();
+var publicCheckoutBaseShape = {
+  id: z6.string().min(1),
+  amounts: checkoutAmountsSchema,
+  items: z6.array(canonicalPublicCheckoutItemSchema).min(1),
+  customerSnapshot: customerSnapshotSchema,
+  shippingAddress: checkoutShippingAddressSchema.nullable(),
+  attributes: publicAttributesSchema,
+  expiresAt: z6.string().datetime({ offset: true }),
+  createdAt: z6.string().datetime({ offset: true }),
+  updatedAt: z6.string().datetime({ offset: true })
+};
+var abandonedReasonSchema = z6.enum(["expired", "customer", "operator"]);
+var publicCheckoutVariants = [
+  z6.object({
+    ...publicCheckoutBaseShape,
+    status: z6.literal("open"),
+    paymentState: openCheckoutPaymentStateSchema,
+    order: z6.null()
+  }).strict(),
+  z6.object({
+    ...publicCheckoutBaseShape,
+    status: z6.literal("placed"),
+    placedAt: z6.string().datetime({ offset: true }),
+    paymentState: spentCheckoutPaymentStateSchema,
+    order: lightweightOrderReferenceSchema
   }).strict(),
-  shippingAddress: z4.object({
-    postalCode: z4.string().optional(),
-    address: z4.string().optional(),
-    detailAddress: z4.string().optional(),
-    deliveryMessage: z4.string().optional(),
-    recipientName: z4.string().optional(),
-    phone: z4.string().optional()
-  }).strict().optional(),
-  orderItems: z4.array(createOrderItemSchema).min(1, "At least one order item is required").max(100, "Maximum 100 items per order"),
-  totalAmount: z4.number().nonnegative("totalAmount must be non-negative"),
-  shippingAmount: z4.number().min(0).optional(),
-  discountCode: z4.string().optional()
-}).strict().superRefine((data, ctx) => {
-  if (data.pgPaymentId && !data.pgProvider) {
+  z6.object({
+    ...publicCheckoutBaseShape,
+    status: z6.literal("placed"),
+    placedAt: z6.string().datetime({ offset: true }),
+    placedVia: z6.literal("late_capture"),
+    abandonedAt: z6.string().datetime({ offset: true }),
+    abandonedReason: abandonedReasonSchema,
+    paymentState: spentCheckoutPaymentStateSchema,
+    order: lightweightOrderReferenceSchema
+  }).strict(),
+  z6.object({
+    ...publicCheckoutBaseShape,
+    status: z6.literal("abandoned"),
+    abandonedAt: z6.string().datetime({ offset: true }),
+    abandonedReason: abandonedReasonSchema,
+    paymentState: z6.object({
+      activePaymentSession: z6.null()
+    }).strict(),
+    order: z6.null()
+  }).strict()
+];
+function validateCheckoutSnapshot(input, ctx) {
+  const checkout = input;
+  const expectedSubtotal = checkout.items.reduce(
+    (total, item) => total + BigInt(item.unitPriceMinor) * BigInt(item.quantity),
+    0n
+  );
+  const expectedDiscount = checkout.items.reduce(
+    (total, item) => total + BigInt(item.discountMinor),
+    0n
+  );
+  if (BigInt(checkout.amounts.subtotalMinor) !== expectedSubtotal) {
     ctx.addIssue({
-      code: z4.ZodIssueCode.custom,
-      path: ["pgProvider"],
-      message: "pgProvider is required when pgPaymentId is provided"
+      code: "custom",
+      path: ["amounts", "subtotalMinor"],
+      message: "subtotalMinor must equal the sum of undiscounted checkout line totals"
     });
   }
-  if (data.pgProvider && !data.pgPaymentId) {
+  if (BigInt(checkout.amounts.discountMinor) !== expectedDiscount) {
     ctx.addIssue({
-      code: z4.ZodIssueCode.custom,
-      path: ["pgPaymentId"],
-      message: "pgPaymentId is required when pgProvider is provided"
+      code: "custom",
+      path: ["amounts", "discountMinor"],
+      message: "discountMinor must equal the sum of checkout line discounts"
     });
   }
+}
+var publicCheckoutSchema = z6.union(publicCheckoutVariants).superRefine(validateCheckoutSnapshot);
+var serverCheckoutExtraShape = {
+  clientReferenceId: commerceResourceIdSchema.nullable(),
+  integrationMetadata: integrationMetadataSchema
+};
+var serverCheckoutVariants = publicCheckoutVariants.map(
+  (variant) => variant.extend(serverCheckoutExtraShape)
+);
+var serverCheckoutSchema = z6.union(serverCheckoutVariants).superRefine(validateCheckoutSnapshot);
+var retrieveCheckoutParamsSchema = z6.object({ checkoutToken: commerceCapabilitySchema }).strict();
+var retrieveServerCheckoutParamsSchema = z6.object({ checkoutId: commerceResourceIdSchema }).strict();
+var createCheckoutBodySchema = z6.object({
+  cartToken: commerceCapabilitySchema,
+  customer: customerSnapshotSchema,
+  shippingAddress: checkoutShippingAddressSchema.optional()
+}).strict();
+var createCheckoutParamsSchema = createCheckoutBodySchema.extend({
+  idempotencyKey: commerceIdempotencyKeySchema
 });
-var updateTransactionSchema = z4.object({
-  pgPaymentId: z4.string().min(1, "pgPaymentId is required").describe("PG payment ID (required)"),
-  status: transactionStatusSchema.describe(
-    "New transaction status (required)"
-  ),
-  paymentMethod: z4.string().optional().describe("Payment method (optional)"),
-  receiptUrl: z4.string().optional().describe("Receipt URL (optional)"),
-  paymentKey: z4.string().min(1).optional().describe("Provider payment key for verified paid confirmation"),
-  amount: z4.number().int().positive().optional().describe("Provider-confirmed amount for verified paid confirmation")
+var createServerCheckoutBodySchema = createCheckoutBodySchema.safeExtend({
+  clientReferenceId: commerceResourceIdSchema.optional(),
+  integrationMetadata: integrationMetadataSchema.optional()
 }).strict();
-var confirmPaymentSchema = z4.object({
-  orderNumber: z4.string().min(1).optional(),
-  pgPaymentId: z4.string().min(1, "pgPaymentId is required").describe("Provider payment identifier stored on the transaction"),
-  pgProvider: providerSlugSchema2.describe(
-    "Payment provider slug, e.g. toss, portone, stripe"
-  ),
-  pgOrderId: z4.string().min(1).optional(),
-  amount: z4.number().int().nonnegative("amount must be non-negative").describe("Provider-confirmed amount in minor units"),
-  currency: z4.string().min(1).optional(),
-  paymentMethod: z4.string().optional(),
-  receiptUrl: z4.string().url().optional(),
-  approvedAt: z4.string().optional(),
-  providerStatus: z4.string().optional(),
-  providerEventId: z4.string().min(1).optional(),
-  confirmationSource: z4.enum([
-    "provider_webhook",
-    "provider_lookup",
-    "provider_api_confirm",
-    "manual_server"
-  ]).optional(),
-  paymentKey: z4.string().min(1).optional().describe(
-    "Optional provider payment key from the client confirm handshake; stored for BFF/provider refund workflows (also accepted as metadata.tossPaymentKey). Local cancel does not read this field."
-  ),
-  metadata: z4.record(z4.string(), z4.unknown()).optional()
+var createServerCheckoutParamsSchema = createServerCheckoutBodySchema.extend({
+  idempotencyKey: commerceIdempotencyKeySchema
+});
+var createCheckoutResultSchema = z6.object({
+  checkout: publicCheckoutSchema,
+  checkoutToken: commerceCapabilitySchema
+}).strict();
+var createServerCheckoutResultSchema = z6.object({
+  checkout: serverCheckoutSchema,
+  checkoutToken: commerceCapabilitySchema
 }).strict();
-var confirmPaymentResponseSchema = z4.object({
-  orderId: z4.string().min(1),
-  transactionId: z4.string().min(1),
-  status: z4.literal("paid"),
-  alreadyConfirmed: z4.boolean().optional()
+var canonicalCheckoutQuerySchema = z6.object({
+  limit: z6.number().int().min(1).max(100).default(20),
+  cursor: z6.string().min(1).max(512).optional(),
+  status: z6.array(z6.enum(["open", "placed", "abandoned"])).optional(),
+  createdAtFrom: z6.string().datetime({ offset: true }).optional(),
+  createdAtTo: z6.string().datetime({ offset: true }).optional(),
+  clientReferenceId: commerceResourceIdSchema.optional()
+}).strict();
+var checkoutListItemVariants = publicCheckoutVariants.map(
+  (variant) => variant.omit({
+    items: true,
+    shippingAddress: true,
+    attributes: true
+  }).extend({ clientReferenceId: commerceResourceIdSchema.nullable() })
+);
+var checkoutListItemSchema = z6.union(checkoutListItemVariants);
+var canonicalCheckoutQueryResultSchema = z6.object({
+  data: z6.array(checkoutListItemSchema),
+  hasMore: z6.boolean(),
+  nextCursor: z6.string().min(1).max(512).nullable()
 }).strict();
+var CreateServerCheckoutParamsSchema = createServerCheckoutParamsSchema;
+var CanonicalCheckoutQuerySchema = canonicalCheckoutQuerySchema;
+
+// ../../internal/contracts/src/ecommerce/index.ts
+var transactionStatusSchema = z7.enum([
+  "pending",
+  "paid",
+  "success",
+  "failed",
+  "error",
+  "canceled",
+  "refunded"
+]);
+var transactionKindSchema = z7.enum([
+  "authorization",
+  "sale",
+  "capture",
+  "void",
+  "refund"
+]);
 var RETURN_REASON_CODES = [
   "change_of_mind",
   "defective",
   "wrong_delivery",
   "damaged",
+  "size_too_large",
+  "size_too_small",
+  "color",
+  "style",
+  "not_as_described",
+  "wrong_item",
+  "unknown",
   "other"
 ];
-var returnReasonSchema = z4.enum(RETURN_REASON_CODES);
+var returnReasonSchema = z7.enum(RETURN_REASON_CODES);
 var RETURN_REJECTION_REASON_CODES = [
   "window_expired",
   "used_or_damaged",
   "non_returnable",
   "other"
 ];
-var returnRejectionReasonCodeSchema = z4.enum(
+var returnRejectionReasonCodeSchema = z7.enum(
   RETURN_REJECTION_REASON_CODES
 );
-var restockActionSchema = z4.enum(["return_to_stock", "discard"]);
-var returnWithRefundItemSchema = z4.object({
-  orderItem: z4.union([z4.string().min(1), z4.number()]).transform(String),
-  quantity: z4.number().int().positive("quantity must be a positive integer"),
+var RETURN_CANCELLATION_REASON_CODES = [
+  "items_not_received",
+  "customer_withdrew",
+  "merchant_decision",
+  "other"
+];
+var returnCancellationReasonCodeSchema = z7.enum(
+  RETURN_CANCELLATION_REASON_CODES
+);
+var restockActionSchema = z7.enum(["return_to_stock", "discard"]);
+var returnWithRefundItemSchema = z7.object({
+  orderItem: z7.union([z7.string().min(1), z7.number()]).transform(String),
+  quantity: z7.number().int().positive("quantity must be a positive integer"),
   restockAction: restockActionSchema.default("return_to_stock"),
-  restockingFee: z4.number().min(0, "restockingFee must be non-negative").optional().describe("Restocking fee charged for this line (ADR 0005 \xA7Gap 1)")
+  restockingFee: z7.number().min(0, "restockingFee must be non-negative").optional().describe("Restocking fee charged for this line (ADR 0005 \xA7Gap 1)")
 }).strict();
-var returnWithRefundSchema = z4.object({
-  orderNumber: z4.string().min(1, "orderNumber is required").describe("Order number (required)"),
+var returnWithRefundSchema = z7.object({
+  orderNumber: z7.string().min(1, "orderNumber is required").describe("Order number (required)"),
   reason: returnReasonSchema.optional().describe("Return reason (optional)"),
-  reasonDetail: z4.string().optional().describe("Detailed reason text (optional)"),
-  returnItems: z4.array(returnWithRefundItemSchema).min(1, "At least one return item is required").max(100, "Too many return items").describe("Array of products to return (required)"),
-  refundAmount: z4.number().min(0, "refundAmount must be non-negative").describe("Refund amount (required, min 0)"),
-  returnShippingFee: z4.number().min(0, "returnShippingFee must be non-negative").optional().describe(
+  reasonDetail: z7.string().optional().describe("Detailed reason text (optional)"),
+  returnItems: z7.array(returnWithRefundItemSchema).min(1, "At least one return item is required").max(100, "Too many return items").describe("Array of products to return (required)"),
+  refundAmount: z7.number().min(0, "refundAmount must be non-negative").describe("Refund amount (required, min 0)"),
+  returnShippingFee: z7.number().min(0, "returnShippingFee must be non-negative").optional().describe(
     "Return shipping fee charged to the customer (ADR 0005 \xA7Gap 1)"
   ),
-  initialShippingRefundAmount: z4.number().min(0, "initialShippingRefundAmount must be non-negative").optional().describe("Initial order shipping amount refunded to the customer"),
-  initialShippingRefundOverrideNote: z4.string().min(1).optional().describe(
+  initialShippingRefundAmount: z7.number().min(0, "initialShippingRefundAmount must be non-negative").optional().describe("Initial order shipping amount refunded to the customer"),
+  initialShippingRefundOverrideNote: z7.string().min(1).optional().describe(
     "Operator audit note required when overriding policy suggestion"
   ),
-  pgPaymentId: z4.string().min(1, "pgPaymentId is required").describe("PG payment ID for refund (required)"),
-  paymentKey: z4.string().min(1).optional().describe("Provider payment key for verified refund"),
-  refundReceiptUrl: z4.string().optional().describe("Refund receipt URL (optional)")
+  pgPaymentId: z7.string().min(1, "pgPaymentId is required").describe("PG payment ID for refund (required)"),
+  paymentKey: z7.string().min(1).optional().describe("Provider payment key for verified refund"),
+  refundReceiptUrl: z7.string().optional().describe("Refund receipt URL (optional)")
 }).strict();
-var createReturnSchema = z4.object({
-  orderNumber: z4.string().min(1, "orderNumber is required").describe("Order number (required)"),
+var createReturnSchema = z7.object({
+  orderNumber: z7.string().min(1, "orderNumber is required").describe("Order number (required)"),
   reason: returnReasonSchema.optional().describe("Return reason (optional)"),
-  reasonDetail: z4.string().optional().describe("Detailed reason text (optional)"),
-  returnItems: z4.array(returnWithRefundItemSchema).min(1, "At least one return item is required").max(100, "Too many return items").describe("Array of products to return (required)"),
-  refundAmount: z4.number().min(0, "refundAmount must be non-negative").describe(
+  reasonDetail: z7.string().optional().describe("Detailed reason text (optional)"),
+  returnItems: z7.array(returnWithRefundItemSchema).min(1, "At least one return item is required").max(100, "Too many return items").describe("Array of products to return (required)"),
+  refundAmount: z7.number().min(0, "refundAmount must be non-negative").describe(
     "Line refund amount before initial shipping refund (required, min 0)"
   ),
-  returnShippingFee: z4.number().min(0, "returnShippingFee must be non-negative").optional().describe("Return shipping fee charged to the customer"),
-  initialShippingRefundAmount: z4.number().min(0, "initialShippingRefundAmount must be non-negative").optional().describe("Initial order shipping amount refunded to the customer"),
-  initialShippingRefundOverrideNote: z4.string().min(1).optional().describe(
+  returnShippingFee: z7.number().min(0, "returnShippingFee must be non-negative").optional().describe("Return shipping fee charged to the customer"),
+  initialShippingRefundAmount: z7.number().min(0, "initialShippingRefundAmount must be non-negative").optional().describe("Initial order shipping amount refunded to the customer"),
+  initialShippingRefundOverrideNote: z7.string().min(1).optional().describe(
     "Operator audit note required when overriding policy suggestion"
   )
 }).strict();
+var updateReturnSchema = z7.object({
+  returnId: z7.union([z7.string(), z7.number()]).transform(String),
+  // Only non-financial transitions are accepted here. `completed` is included
+  // so the server can return the canonical `server_derived` error instead of
+  // a generic validation failure.
+  status: z7.enum([
+    "processing",
+    "approved",
+    "rejected",
+    "canceled",
+    "completed"
+  ]),
+  reasonCode: returnRejectionReasonCodeSchema.optional(),
+  cancellationReasonCode: returnCancellationReasonCodeSchema.optional(),
+  cancellationReasonDetail: z7.string().trim().min(1).max(2e3).optional()
+}).strict();
 var CANCEL_REASON_CODES = [
   "customer",
   "inventory",
@@ -1371,245 +2466,159 @@ var CANCEL_REASON_CODES = [
   "staff",
   "other"
 ];
-var cancelReasonCodeSchema = z4.enum(CANCEL_REASON_CODES);
+var cancelReasonCodeSchema = z7.enum(CANCEL_REASON_CODES);
 var FORCE_RESOLUTION_REASON_CODES = [
   "staff_error",
   "wrong_fulfillment",
   "other"
 ];
-var forceResolutionReasonCodeSchema = z4.enum(
+var forceResolutionReasonCodeSchema = z7.enum(
   FORCE_RESOLUTION_REASON_CODES
 );
-var idempotencyKeySchema = z4.string().trim().min(1, "idempotencyKey is required").max(255, "idempotencyKey must be 255 characters or fewer").regex(
+var idempotencyKeySchema = z7.string().trim().min(1, "idempotencyKey is required").max(255, "idempotencyKey must be 255 characters or fewer").regex(
   /^[\x21-\x7E]+$/,
   "idempotencyKey must contain only printable header-safe characters"
 );
-var cancelOrderSchema = z4.object({
-  orderNumber: z4.string().min(1, "orderNumber is required").describe("Order number to cancel"),
+var cancelOrderSchema = z7.object({
+  orderNumber: z7.string().min(1, "orderNumber is required").describe("Order number to cancel"),
   reasonCode: cancelReasonCodeSchema.default("other").describe("Operator-selected cancel reason code"),
-  reasonDetail: z4.string().trim().max(2e3, "reasonDetail must be 2000 characters or fewer").optional().describe("Internal cancellation detail stored on the order")
+  reasonDetail: z7.string().trim().max(2e3, "reasonDetail must be 2000 characters or fewer").optional().describe("Internal cancellation detail stored on the order")
 }).strict();
 var cancelOrderResponseBaseSchema = {
-  orderId: z4.string().min(1)
+  orderId: z7.string().min(1)
 };
 var unpaidLocalCancelCommittedResponseFields = {
-  refundedAmount: z4.literal(0),
-  providerRefunded: z4.literal(false)
+  refundedAmount: z7.literal(0),
+  providerRefunded: z7.literal(false)
 };
 var paidLocalCancelCommittedResponseFields = {
-  transactionId: z4.string().min(1),
-  refundedAmount: z4.literal(0),
-  providerRefunded: z4.literal(false),
-  refundPending: z4.literal(true)
-};
-var legacyProviderRefundResponseFields = {
-  transactionId: z4.string().min(1),
-  refundedAmount: z4.number().int().positive(),
-  refundSeq: z4.number().int().positive(),
-  providerRefunded: z4.literal(true)
+  transactionId: z7.string().min(1),
+  refundedAmount: z7.literal(0),
+  providerRefunded: z7.literal(false),
+  refundPending: z7.literal(true)
 };
 var alreadyCanceledResponseFields = {
-  refundedAmount: z4.number().int().nonnegative(),
-  providerRefunded: z4.literal(false)
+  refundedAmount: z7.number().int().nonnegative(),
+  providerRefunded: z7.literal(false)
 };
 var alreadyCanceledRefundPendingResponseFields = {
-  transactionId: z4.string().min(1),
-  refundedAmount: z4.number().int().nonnegative(),
-  providerRefunded: z4.literal(false),
-  refundPending: z4.literal(true)
+  transactionId: z7.string().min(1),
+  refundedAmount: z7.number().int().nonnegative(),
+  providerRefunded: z7.literal(false),
+  refundPending: z7.literal(true)
 };
-var cancelOrderReconciliationStatusSchema = z4.enum([
-  "paid",
-  "preparing",
-  "shipped",
-  "delivered",
-  "confirmed",
-  "return_requested",
-  "return_processing",
-  "returned",
-  "refunded"
-]);
-var cancelOrderResponseSchema = z4.union([
-  z4.object({
+var cancelOrderResponseSchema = z7.union([
+  z7.object({
     ...cancelOrderResponseBaseSchema,
     ...paidLocalCancelCommittedResponseFields,
-    status: z4.literal("canceled"),
-    cancelCommitted: z4.literal(true)
+    status: z7.literal("canceled"),
+    cancelCommitted: z7.literal(true)
   }).strict(),
-  z4.object({
+  z7.object({
     ...cancelOrderResponseBaseSchema,
     ...unpaidLocalCancelCommittedResponseFields,
-    status: z4.literal("canceled"),
-    cancelCommitted: z4.literal(true)
+    status: z7.literal("canceled"),
+    cancelCommitted: z7.literal(true)
   }).strict(),
-  z4.object({
+  z7.object({
     ...cancelOrderResponseBaseSchema,
     ...alreadyCanceledResponseFields,
-    status: z4.literal("canceled"),
-    cancelCommitted: z4.literal(false),
-    alreadyCanceled: z4.literal(true)
+    status: z7.literal("canceled"),
+    cancelCommitted: z7.literal(false),
+    alreadyCanceled: z7.literal(true)
   }).strict(),
-  z4.object({
+  z7.object({
     ...cancelOrderResponseBaseSchema,
     ...alreadyCanceledRefundPendingResponseFields,
-    status: z4.literal("canceled"),
-    cancelCommitted: z4.literal(false),
-    alreadyCanceled: z4.literal(true)
-  }).strict(),
-  z4.object({
-    ...cancelOrderResponseBaseSchema,
-    ...legacyProviderRefundResponseFields,
-    status: cancelOrderReconciliationStatusSchema,
-    cancelCommitted: z4.literal(false),
-    reconciliationRequired: z4.literal(true)
+    status: z7.literal("canceled"),
+    cancelCommitted: z7.literal(false),
+    alreadyCanceled: z7.literal(true)
   }).strict()
 ]);
-var resolveCancelRefundOutcomeSchema = z4.enum(["succeeded", "failed"]);
-var resolveCancelRefundSchema = z4.object({
-  orderNumber: z4.string().min(1, "orderNumber is required").describe("Order number whose pending cancel refund is being resolved"),
+var resolveCancelRefundOutcomeSchema = z7.enum(["succeeded", "failed"]);
+var resolveCancelRefundSchema = z7.object({
+  orderNumber: z7.string().min(1, "orderNumber is required").describe("Order number whose pending cancel refund is being resolved"),
   idempotencyKey: idempotencyKeySchema.describe(
     "Stable key for this PG refund result report"
   ),
   outcome: resolveCancelRefundOutcomeSchema.describe(
     "PG refund result reported by the storefront or BFF"
   ),
-  refundedAmount: z4.number().int("refundedAmount must be an integer minor-unit amount").nonnegative("refundedAmount must be nonnegative"),
-  pgProvider: z4.string().trim().min(1, "pgProvider is required").regex(
+  refundedAmount: z7.number().int("refundedAmount must be an integer minor-unit amount").nonnegative("refundedAmount must be nonnegative"),
+  pgProvider: z7.string().trim().min(1, "pgProvider is required").regex(
     /^[a-z0-9][a-z0-9_-]*$/,
     "pgProvider must be a lowercase provider slug"
   ),
-  pgRefundId: z4.string().trim().min(1).optional()
+  pgRefundId: z7.string().trim().min(1).optional()
 }).strict().superRefine((value, ctx) => {
   if (value.outcome === "succeeded" && value.refundedAmount <= 0) {
     ctx.addIssue({
-      code: z4.ZodIssueCode.custom,
+      code: z7.ZodIssueCode.custom,
       path: ["refundedAmount"],
       message: "refundedAmount must be positive when outcome is succeeded"
     });
   }
   if (value.outcome === "succeeded" && !value.pgRefundId) {
     ctx.addIssue({
-      code: z4.ZodIssueCode.custom,
+      code: z7.ZodIssueCode.custom,
       path: ["pgRefundId"],
       message: "pgRefundId is required when outcome is succeeded"
     });
   }
   if (value.outcome === "failed" && value.refundedAmount !== 0) {
     ctx.addIssue({
-      code: z4.ZodIssueCode.custom,
+      code: z7.ZodIssueCode.custom,
       path: ["refundedAmount"],
       message: "refundedAmount must be 0 when outcome is failed"
     });
   }
 });
-var resolveCancelRefundResponseSchema = z4.union([
-  z4.object({
-    orderId: z4.string().min(1),
-    transactionId: z4.string().min(1),
-    refundTransactionId: z4.string().min(1),
-    refundedAmount: z4.number().int().positive(),
-    refundStatus: z4.literal("succeeded"),
-    transactionStatus: z4.literal("refunded")
+var resolveCancelRefundResponseSchema = z7.union([
+  z7.object({
+    orderId: z7.string().min(1),
+    transactionId: z7.string().min(1),
+    refundTransactionId: z7.string().min(1),
+    refundedAmount: z7.number().int().positive(),
+    refundStatus: z7.literal("succeeded"),
+    transactionStatus: z7.enum(["paid", "refunded"])
   }).strict(),
-  z4.object({
-    orderId: z4.string().min(1),
-    transactionId: z4.string().min(1),
-    refundTransactionId: z4.string().min(1),
-    refundedAmount: z4.literal(0),
-    refundStatus: z4.literal("failed"),
-    transactionStatus: z4.literal("paid")
+  z7.object({
+    orderId: z7.string().min(1),
+    transactionId: z7.string().min(1),
+    refundTransactionId: z7.string().min(1),
+    refundedAmount: z7.literal(0),
+    refundStatus: z7.literal("failed"),
+    transactionStatus: z7.literal("paid")
   }).strict()
 ]);
 
 // src/commands/order.ts
-import { z as z5 } from "zod";
-var idSchema = z5.union([z5.string().min(1), z5.number()]).transform(String);
-var customerSnapshotSchema = z5.object({
-  email: z5.string().email("Invalid email format"),
-  name: z5.string().optional(),
-  phone: z5.string().optional()
-}).strict();
-var orderStatusSchema2 = z5.enum(["confirmed"]);
-var fulfillmentStatusSchema = z5.enum(["shipped", "delivered", "failed"]);
-var updateFulfillmentSchema = z5.object({
+import { z as z8 } from "zod";
+var idSchema = z8.union([z8.string().min(1), z8.number()]).transform(String);
+var orderStatusSchema = z8.enum(["confirmed"]);
+var fulfillmentStatusSchema = z8.enum(["shipped", "delivered", "failed"]);
+var updateFulfillmentSchema = z8.object({
   fulfillmentId: idSchema,
   status: fulfillmentStatusSchema.optional(),
-  carrier: z5.string().min(1).optional(),
-  trackingNumber: z5.string().min(1).optional()
+  carrier: z8.string().min(1).optional(),
+  trackingNumber: z8.string().min(1).optional()
 }).refine(
   (value) => value.status !== void 0 || value.carrier !== void 0 || value.trackingNumber !== void 0,
   {
     message: "status, carrier, or trackingNumber is required"
   }
 );
-var fulfillmentItemsSchema = z5.array(
-  z5.object({
+var fulfillmentItemsSchema = z8.array(
+  z8.object({
     orderItem: idSchema,
-    quantity: z5.number().int().positive("quantity must be a positive integer")
+    quantity: z8.number().int().positive("quantity must be a positive integer")
   }).strict()
 ).min(1, "At least one fulfillment item is required").max(100, "Maximum 100 items per fulfillment");
 function registerOrderCommands(program2, getClient2, getFormat2) {
   const order = program2.command("order").description("Order management");
-  order.command("create").description("Create a new order").option("--payment-id <id>", "Payment ID").option("--provider <slug>", "Payment provider slug").requiredOption("--order-number <num>", "Order number").requiredOption("--email <email>", "Customer email").option("--customer <id>", "Customer ID").option("--name <name>", "Customer name").option("--phone <phone>", "Customer phone").requiredOption("--shipping-address <json>", "Shipping address (JSON)").requiredOption("--products <json>", "Order products array (JSON)").requiredOption("--total-amount <n>", "Total amount", parseFloat).option("--shipping-amount <n>", "Shipping amount", parseFloat).option("--discount-code <code>", "Discount code").option("--dry-run", "Validate inputs without executing").action(async (opts) => {
-    try {
-      const parsed = parseWithSchema(
-        {
-          ...opts.paymentId ? { pgPaymentId: opts.paymentId } : {},
-          ...opts.provider ? { pgProvider: opts.provider } : {},
-          orderNumber: opts.orderNumber,
-          customerSnapshot: {
-            email: opts.email,
-            name: opts.name,
-            phone: opts.phone
-          },
-          customer: opts.customer,
-          shippingAddress: parseJson(
-            opts.shippingAddress,
-            "shipping-address"
-          ),
-          orderItems: parseJsonArray(opts.products, "products"),
-          totalAmount: opts.totalAmount,
-          shippingAmount: opts.shippingAmount,
-          discountCode: opts.discountCode
-        },
-        "order",
-        createOrderSchema
-      );
-      const { pgPaymentId, pgProvider, ...orderData } = parsed;
-      const data = pgPaymentId ? { ...orderData, pgPaymentId, pgProvider } : orderData;
-      if (opts.dryRun) {
-        printResult(
-          { dryRun: true, valid: true, action: "order create", data },
-          getFormat2()
-        );
-        return;
-      }
-      const client = getClient2();
-      const result = await client.commerce.orders.create(data);
-      printResult(result, getFormat2());
-    } catch (e) {
-      exitWithError(e);
-    }
-  });
-  order.command("get <orderNumber>").description("Get an order by order number").action(async (orderNumber) => {
-    try {
-      const client = getClient2();
-      const {
-        docs: [order2]
-      } = await client.collections.from("orders").find({
-        where: { orderNumber: { equals: orderNumber } },
-        limit: 1,
-        depth: 1
-      });
-      if (!order2) throw new Error("Order not found");
-      printResult(order2, getFormat2());
-    } catch (e) {
-      exitWithError(e);
-    }
-  });
   order.command("update <orderNumber>").description("Confirm a delivered order purchase").requiredOption("--status <status>", "New status (confirmed only)").option("--dry-run", "Validate inputs without executing").action(async (orderNumber, opts) => {
     try {
-      const status = parseWithSchema(opts.status, "status", orderStatusSchema2);
+      const status = parseWithSchema(opts.status, "status", orderStatusSchema);
       const data = { orderNumber, status };
       if (opts.dryRun) {
         printResult(
@@ -1653,40 +2662,6 @@ function registerOrderCommands(program2, getClient2, getFormat2) {
       exitWithError(e);
     }
   });
-  order.command("checkout").description("Convert a cart to an order").requiredOption("--cart-id <id>", "Cart ID").option("--payment-id <id>", "Payment ID (optional for free orders)").option("--provider <slug>", "Payment provider slug").requiredOption("--order-number <num>", "Order number").requiredOption("--customer <json>", "Customer snapshot (JSON)").option("--dry-run", "Validate inputs without executing").action(async (opts) => {
-    try {
-      const customerSnapshot = parseWithSchema(
-        parseJson(opts.customer, "customer"),
-        "customer",
-        customerSnapshotSchema
-      );
-      const parsed = parseWithSchema(
-        {
-          cartId: opts.cartId,
-          ...opts.paymentId ? { pgPaymentId: opts.paymentId } : {},
-          ...opts.provider ? { pgProvider: opts.provider } : {},
-          orderNumber: opts.orderNumber,
-          customerSnapshot
-        },
-        "checkout",
-        CheckoutRequestSchema
-      );
-      const { pgPaymentId, pgProvider, ...checkoutData } = parsed;
-      const data = pgPaymentId ? { ...checkoutData, pgPaymentId, pgProvider } : checkoutData;
-      if (opts.dryRun) {
-        printResult(
-          { dryRun: true, valid: true, action: "order checkout", data },
-          getFormat2()
-        );
-        return;
-      }
-      const client = getClient2();
-      const result = await client.commerce.orders.checkout(data);
-      printResult(result, getFormat2());
-    } catch (e) {
-      exitWithError(e);
-    }
-  });
   order.command("prepare <orderNumber>").description("Move paid order fulfillment work to preparation").option("--dry-run", "Validate inputs without executing").action(async (orderNumber, opts) => {
     try {
       const data = { orderNumber };
@@ -1770,8 +2745,8 @@ function registerOrderCommands(program2, getClient2, getFormat2) {
 }
 
 // src/commands/return.ts
-import { z as z6 } from "zod";
-var returnStatusSchema = z6.enum([
+import { z as z9 } from "zod";
+var returnStatusSchema = z9.enum([
   "processing",
   "approved",
   "rejected",
@@ -1900,146 +2875,227 @@ function registerReturnCommands(program2, getClient2, getFormat2) {
   });
 }
 
+// src/lib/sensitive-json-input.ts
+import { createReadStream } from "fs";
+import { stdin as processStdin } from "process";
+var SENSITIVE_JSON_MAX_BYTES = 1024 * 1024;
+function invalidInput(message) {
+  return {
+    type: "validation",
+    code: "invalid_argument",
+    field: "data",
+    message,
+    detail: { message, field: "data" }
+  };
+}
+function isInvalidInput(error) {
+  if (!error || typeof error !== "object") return false;
+  const value = error;
+  return value.type === "validation" && value.code === "invalid_argument";
+}
+async function readBoundedUtf8(source) {
+  const chunks = [];
+  let totalBytes = 0;
+  for await (const chunk of source) {
+    const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+    totalBytes += buffer.byteLength;
+    if (totalBytes > SENSITIVE_JSON_MAX_BYTES) {
+      throw invalidInput(
+        `Sensitive commerce data must be ${SENSITIVE_JSON_MAX_BYTES} bytes or fewer.`
+      );
+    }
+    chunks.push(buffer);
+  }
+  return Buffer.concat(chunks, totalBytes).toString("utf8");
+}
+async function readSensitiveJsonObject(opts, sources = {}) {
+  const sourceCount = [opts.dataStdin, opts.dataFile].filter(Boolean).length;
+  if (sourceCount !== 1) {
+    throw invalidInput(
+      "Exactly one of --data-stdin or --data-file is required for sensitive commerce data."
+    );
+  }
+  let raw;
+  const input = sources.stdin ?? processStdin;
+  try {
+    if (opts.dataStdin) {
+      if (input.isTTY === true) {
+        throw invalidInput(
+          "Sensitive commerce data cannot be read from an interactive terminal. Pipe JSON to --data-stdin or use --data-file."
+        );
+      }
+      raw = await readBoundedUtf8(input);
+    } else {
+      const file = (sources.openFile ?? createReadStream)(opts.dataFile);
+      try {
+        raw = await readBoundedUtf8(file);
+      } finally {
+        file.destroy?.();
+      }
+    }
+  } catch (error) {
+    if (isInvalidInput(error)) throw error;
+    throw invalidInput("Sensitive commerce data could not be read.");
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw invalidInput("Sensitive commerce data must be valid JSON.");
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw invalidInput("Sensitive commerce data must be a JSON object.");
+  }
+  return parsed;
+}
+function sensitiveDryRunResult(action) {
+  return { dryRun: true, valid: true, action };
+}
+
 // src/commands/cart.ts
 function registerCartCommands(program2, getClient2, getFormat2) {
   const cart = program2.command("cart").description("Cart management");
-  cart.command("create").description("Create a cart and print its cartToken handle").option("--dry-run", "Validate inputs without executing").action(async (opts) => {
+  cart.command("create").description("Create a cart and print its cartToken capability").option("--data-stdin", "Read market and attributes JSON from stdin").option("--data-file <path>", "Read market and attributes JSON from file").option("--dry-run", "Validate inputs without executing").action(async (opts) => {
     try {
+      const input = opts.dataStdin || opts.dataFile ? await readSensitiveJsonObject(opts) : {};
+      const data = parseWithSchema(
+        input,
+        "cart create",
+        createCartParamsSchema
+      );
       if (opts.dryRun) {
-        printResult(
-          { dryRun: true, valid: true, action: "cart create", data: {} },
-          getFormat2()
-        );
+        printResult(sensitiveDryRunResult("cart create"), getFormat2());
         return;
       }
-      const client = getClient2();
-      const result = await client.commerce.cart.create();
-      printResult(result, getFormat2());
-    } catch (e) {
-      exitWithError(e);
+      printResult(await getClient2().commerce.carts.create(data), getFormat2());
+    } catch (error) {
+      exitWithError(error);
     }
   });
-  cart.command("add <cartToken>").description("Add an item to a cart (addressed by its cartToken)").requiredOption("--product <id>", "Product ID").requiredOption("--variant <id>", "Variant ID").requiredOption("--option <id>", "Option ID").requiredOption(
-    "--quantity <n>",
-    "Quantity",
-    (v) => parseInt(v, 10)
-  ).option("--dry-run", "Validate inputs without executing").action(async (cartToken, opts) => {
+  cart.command("retrieve").description("Retrieve a cart by its capability token").option("--data-stdin", "Read the Cart capability JSON from stdin").option("--data-file <path>", "Read the Cart capability JSON from file").action(async (opts) => {
     try {
-      const data = {
-        cartToken,
-        product: opts.product,
-        variant: opts.variant,
-        option: opts.option,
-        quantity: opts.quantity
-      };
+      const data = parseWithSchema(
+        await readSensitiveJsonObject(opts),
+        "cart retrieve",
+        retrieveCartParamsSchema
+      );
+      printResult(
+        await getClient2().commerce.carts.retrieve(data),
+        getFormat2()
+      );
+    } catch (error) {
+      exitWithError(error);
+    }
+  });
+  cart.command("add").description("Add an item to a cart").option("--data-stdin", "Read capability and item JSON from stdin").option("--data-file <path>", "Read capability and item JSON from file").option("--dry-run", "Validate inputs without executing").action(async (opts) => {
+    try {
+      const data = parseWithSchema(
+        await readSensitiveJsonObject(opts),
+        "cart add",
+        addItemParamsSchema
+      );
       if (opts.dryRun) {
-        printResult(
-          { dryRun: true, valid: true, action: "cart add", data },
-          getFormat2()
-        );
+        printResult(sensitiveDryRunResult("cart add"), getFormat2());
         return;
       }
-      const client = getClient2();
-      const result = await client.commerce.cart.addItem(data);
-      printResult(result, getFormat2());
-    } catch (e) {
-      exitWithError(e);
+      printResult(await getClient2().commerce.carts.addItem(data), getFormat2());
+    } catch (error) {
+      exitWithError(error);
     }
   });
-  cart.command("update <cartItemId>").description("Update cart item quantity").requiredOption("--cart-token <token>", "Cart token (cart handle)").requiredOption(
-    "--quantity <n>",
-    "New quantity",
-    (v) => parseInt(v, 10)
-  ).option("--dry-run", "Validate inputs without executing").action(async (cartItemId, opts) => {
+  cart.command("update").description("Update cart item quantity").option("--data-stdin", "Read capability and item JSON from stdin").option("--data-file <path>", "Read capability and item JSON from file").option("--dry-run", "Validate inputs without executing").action(async (opts) => {
     try {
-      const data = {
-        cartToken: opts.cartToken,
-        cartItemId,
-        quantity: opts.quantity
-      };
+      const data = parseWithSchema(
+        await readSensitiveJsonObject(opts),
+        "cart update",
+        updateItemParamsSchema
+      );
       if (opts.dryRun) {
-        printResult(
-          { dryRun: true, valid: true, action: "cart update", data },
-          getFormat2()
-        );
+        printResult(sensitiveDryRunResult("cart update"), getFormat2());
         return;
       }
-      const client = getClient2();
-      const result = await client.commerce.cart.updateItem(data);
-      printResult(result, getFormat2());
-    } catch (e) {
-      exitWithError(e);
+      printResult(
+        await getClient2().commerce.carts.updateItem(data),
+        getFormat2()
+      );
+    } catch (error) {
+      exitWithError(error);
     }
   });
-  cart.command("remove <cartItemId>").description("Remove an item from a cart").requiredOption("--cart-token <token>", "Cart token (cart handle)").option("--dry-run", "Validate inputs without executing").action(async (cartItemId, opts) => {
+  cart.command("remove").description("Remove an item from a cart").option("--data-stdin", "Read capability and item JSON from stdin").option("--data-file <path>", "Read capability and item JSON from file").option("--dry-run", "Validate inputs without executing").action(async (opts) => {
     try {
-      const data = { cartToken: opts.cartToken, cartItemId };
-      if (opts.dryRun) {
-        printResult(
-          { dryRun: true, valid: true, action: "cart remove", data },
-          getFormat2()
-        );
+      const data = parseWithSchema(
+        await readSensitiveJsonObject(opts),
+        "cart remove",
+        removeItemParamsSchema
+      );
+      if (opts.dryRun) {
+        printResult(sensitiveDryRunResult("cart remove"), getFormat2());
         return;
       }
-      const client = getClient2();
-      const result = await client.commerce.cart.removeItem(data);
-      printResult(result, getFormat2());
-    } catch (e) {
-      exitWithError(e);
+      printResult(
+        await getClient2().commerce.carts.removeItem(data),
+        getFormat2()
+      );
+    } catch (error) {
+      exitWithError(error);
     }
   });
-  cart.command("clear <cartToken>").description("Remove all items from a cart").option("--dry-run", "Validate inputs without executing").action(async (cartToken, opts) => {
+  cart.command("clear").description("Remove all items from a cart").option("--data-stdin", "Read the Cart capability JSON from stdin").option("--data-file <path>", "Read the Cart capability JSON from file").option("--dry-run", "Validate inputs without executing").action(async (opts) => {
     try {
+      const data = parseWithSchema(
+        await readSensitiveJsonObject(opts),
+        "cart clear",
+        clearCartParamsSchema
+      );
       if (opts.dryRun) {
-        printResult(
-          { dryRun: true, valid: true, action: "cart clear", data: { cartToken } },
-          getFormat2()
-        );
+        printResult(sensitiveDryRunResult("cart clear"), getFormat2());
         return;
       }
-      const client = getClient2();
-      const result = await client.commerce.cart.clear({ cartToken });
-      printResult(result, getFormat2());
-    } catch (e) {
-      exitWithError(e);
+      printResult(await getClient2().commerce.carts.clear(data), getFormat2());
+    } catch (error) {
+      exitWithError(error);
     }
   });
-  cart.command("apply-discount <cartToken>").description("Apply a discount code to a cart").requiredOption("--code <code>", "Discount code").option("--dry-run", "Validate inputs without executing").action(async (cartToken, opts) => {
+  cart.command("discounts").description("Replace all cart discount codes; pass [] to clear").option("--data-stdin", "Read capability and discount JSON from stdin").option("--data-file <path>", "Read capability and discount JSON from file").option("--dry-run", "Validate inputs without executing").action(async (opts) => {
     try {
-      const data = { cartToken, discountCode: opts.code };
+      const data = parseWithSchema(
+        await readSensitiveJsonObject(opts),
+        "cart discounts",
+        updateDiscountCodesParamsSchema
+      );
       if (opts.dryRun) {
-        printResult(
-          { dryRun: true, valid: true, action: "cart apply-discount", data },
-          getFormat2()
-        );
+        printResult(sensitiveDryRunResult("cart discounts"), getFormat2());
         return;
       }
-      const client = getClient2();
-      const result = await client.commerce.cart.applyDiscount(data);
-      printResult(result, getFormat2());
-    } catch (e) {
-      exitWithError(e);
+      printResult(
+        await getClient2().commerce.carts.updateDiscountCodes(data),
+        getFormat2()
+      );
+    } catch (error) {
+      exitWithError(error);
     }
   });
-  cart.command("remove-discount <cartToken>").description("Remove the discount from a cart").option("--dry-run", "Validate inputs without executing").action(async (cartToken, opts) => {
+  cart.command("attributes").description("Replace all public cart attributes; pass [] to clear").option("--data-stdin", "Read capability and attributes JSON from stdin").option(
+    "--data-file <path>",
+    "Read capability and attributes JSON from file"
+  ).option("--dry-run", "Validate inputs without executing").action(async (opts) => {
     try {
+      const data = parseWithSchema(
+        await readSensitiveJsonObject(opts),
+        "cart attributes",
+        updateCartAttributesParamsSchema
+      );
       if (opts.dryRun) {
-        printResult(
-          {
-            dryRun: true,
-            valid: true,
-            action: "cart remove-discount",
-            data: { cartToken }
-          },
-          getFormat2()
-        );
+        printResult(sensitiveDryRunResult("cart attributes"), getFormat2());
         return;
       }
-      const client = getClient2();
-      const result = await client.commerce.cart.removeDiscount({ cartToken });
-      printResult(result, getFormat2());
-    } catch (e) {
-      exitWithError(e);
+      printResult(
+        await getClient2().commerce.carts.updateAttributes(data),
+        getFormat2()
+      );
+    } catch (error) {
+      exitWithError(error);
     }
   });
 }
@@ -2063,124 +3119,196 @@ function registerStockCommands(program2, getClient2, getFormat2) {
 }
 
 // src/commands/transaction.ts
-import { z as z7 } from "zod";
-var transactionAmountSchema = z7.object({
-  amount: z7.string().regex(/^[1-9]\d*$/, "amount must be a positive integer").transform(Number)
-});
-var confirmPaymentAmountSchema = z7.object({
-  amount: z7.string().regex(/^(0|[1-9]\d*)$/, "amount must be a non-negative integer").transform(Number)
-});
-var idempotencyKeyOptionSchema = z7.object({
-  idempotencyKey: idempotencyKeySchema
-});
-function parseTransactionAmount(value) {
-  if (value === void 0) return void 0;
-  return parseWithSchema({ amount: value }, "amount", transactionAmountSchema).amount;
-}
-function parseConfirmPaymentAmount(value) {
-  return parseWithSchema({ amount: value }, "amount", confirmPaymentAmountSchema).amount;
-}
-function parseIdempotencyKey(value) {
-  if (value === void 0) return void 0;
-  return parseWithSchema(
-    { idempotencyKey: value },
-    "idempotencyKey",
-    idempotencyKeyOptionSchema
-  ).idempotencyKey;
-}
-function registerTransactionCommands(program2, getClient2, getFormat2) {
-  const tx = program2.command("transaction").description("Transaction management");
-  tx.command("update").description("Update transaction status").requiredOption("--payment-id <id>", "Payment ID").requiredOption(
-    "--status <status>",
-    "New status (pending, paid, failed, canceled, refunded)"
-  ).option("--payment-method <method>", "Payment method").option("--receipt-url <url>", "Receipt URL").option("--payment-key <key>", "Provider payment key").option("--amount <n>", "Provider-confirmed amount").option("--dry-run", "Validate inputs without executing").action(async (opts) => {
+function registerCommerceSessionCommands(program2, getClient2, getFormat2) {
+  const checkout = program2.command("checkout").description("Checkout management");
+  checkout.command("create").description("Create a Checkout from a server-authoritative Cart").option("--data-stdin", "Read capability and customer JSON from stdin").option("--data-file <path>", "Read capability and customer JSON from file").option("--dry-run", "Validate inputs without executing").action(async (opts) => {
     try {
       const data = parseWithSchema(
-        {
-          pgPaymentId: opts.paymentId,
-          status: opts.status,
-          paymentMethod: opts.paymentMethod,
-          receiptUrl: opts.receiptUrl,
-          paymentKey: opts.paymentKey,
-          amount: parseTransactionAmount(opts.amount)
-        },
-        "transaction",
-        updateTransactionSchema
+        await readSensitiveJsonObject(opts),
+        "checkout",
+        CreateServerCheckoutParamsSchema
+      );
+      if (opts.dryRun) {
+        printResult(sensitiveDryRunResult("checkout create"), getFormat2());
+        return;
+      }
+      printResult(
+        await getClient2().commerce.checkouts.create(data),
+        getFormat2()
+      );
+    } catch (error) {
+      exitWithError(error);
+    }
+  });
+  checkout.command("retrieve <checkoutId>").description("Retrieve a Checkout by ID with server credentials").action(async (checkoutId) => {
+    try {
+      printResult(
+        await getClient2().commerce.checkouts.retrieve({ checkoutId }),
+        getFormat2()
+      );
+    } catch (error) {
+      exitWithError(error);
+    }
+  });
+  checkout.command("query").description("Query lightweight Checkouts with server credentials").option("--params <json>", "Checkout query parameters (JSON)", "{}").action(async (opts) => {
+    try {
+      const data = parseWithSchema(
+        parseJson(opts.params, "params"),
+        "checkout query",
+        CanonicalCheckoutQuerySchema
+      );
+      printResult(
+        await getClient2().commerce.checkouts.query(data),
+        getFormat2()
+      );
+    } catch (error) {
+      exitWithError(error);
+    }
+  });
+  const sessions = program2.command("payment-session").description("PaymentSession management");
+  sessions.command("create").description("Create a canonical provider-configured PaymentSession").option("--data-stdin", "Read canonical create parameters from stdin").option("--data-file <path>", "Read canonical create parameters from file").option("--dry-run", "Validate inputs without executing").action(async (opts) => {
+    try {
+      const data = parseWithSchema(
+        await readSensitiveJsonObject(opts),
+        "payment-session",
+        CreatePaymentSessionParamsSchema
       );
       if (opts.dryRun) {
         printResult(
-          { dryRun: true, valid: true, action: "transaction update", data },
+          sensitiveDryRunResult("payment-session create"),
           getFormat2()
         );
         return;
       }
-      const client = getClient2();
-      const result = await client.commerce.orders.updateTransaction(data);
-      printResult(result, getFormat2());
-    } catch (e) {
-      exitWithError(e);
+      printResult(
+        await getClient2().commerce.paymentSessions.create(data),
+        getFormat2()
+      );
+    } catch (error) {
+      exitWithError(error);
+    }
+  });
+  sessions.command("retrieve <paymentSessionId>").description("Retrieve a PaymentSession").action(async (paymentSessionId) => {
+    try {
+      printResult(
+        await getClient2().commerce.paymentSessions.retrieve({
+          paymentSessionId
+        }),
+        getFormat2()
+      );
+    } catch (error) {
+      exitWithError(error);
     }
   });
-  tx.command("confirm-payment").description("Confirm a provider-verified payment for an order").requiredOption("--payment-id <id>", "Provider payment identifier (pgPaymentId)").requiredOption(
-    "--provider <slug>",
-    "Payment provider slug (toss, portone, stripe, ...)"
-  ).requiredOption(
-    "--amount <n>",
-    "Provider-confirmed amount in minor units"
-  ).option("--order-number <num>", "Order number").option("--pg-order-id <id>", "Provider order id").option("--currency <code>", "Currency code").option("--payment-method <method>", "Payment method").option("--receipt-url <url>", "Receipt URL").option("--approved-at <ts>", "Provider approval timestamp").option("--provider-status <status>", "Provider status").option("--provider-event-id <id>", "Provider event id (idempotency)").option("--idempotency-key <key>", "Idempotency key header override").option(
-    "--confirmation-source <src>",
-    "provider_webhook | provider_lookup | provider_api_confirm | manual_server"
-  ).option("--payment-key <key>", "Provider payment key").option("--dry-run", "Validate inputs without executing").action(async (opts) => {
+  sessions.command("cancel").description("Cancel a PaymentSession and release its payment slot").option("--data-stdin", "Read session ID and idempotency key from stdin").option(
+    "--data-file <path>",
+    "Read session ID and idempotency key from file"
+  ).option("--dry-run", "Validate inputs without executing").action(async (opts) => {
     try {
       const data = parseWithSchema(
-        {
-          pgPaymentId: opts.paymentId,
-          pgProvider: opts.provider,
-          amount: parseConfirmPaymentAmount(opts.amount),
-          ...opts.orderNumber ? { orderNumber: opts.orderNumber } : {},
-          ...opts.pgOrderId ? { pgOrderId: opts.pgOrderId } : {},
-          ...opts.currency ? { currency: opts.currency } : {},
-          ...opts.paymentMethod ? { paymentMethod: opts.paymentMethod } : {},
-          ...opts.receiptUrl ? { receiptUrl: opts.receiptUrl } : {},
-          ...opts.approvedAt ? { approvedAt: opts.approvedAt } : {},
-          ...opts.providerStatus ? { providerStatus: opts.providerStatus } : {},
-          ...opts.providerEventId ? { providerEventId: opts.providerEventId } : {},
-          ...opts.confirmationSource ? { confirmationSource: opts.confirmationSource } : {},
-          ...opts.paymentKey ? { paymentKey: opts.paymentKey } : {}
-        },
-        "confirm-payment",
-        confirmPaymentSchema
+        await readSensitiveJsonObject(opts),
+        "payment-session cancel",
+        CancelServerPaymentSessionParamsSchema
       );
-      const sdkParams = {
-        ...data,
-        ...opts.idempotencyKey !== void 0 ? { idempotencyKey: parseIdempotencyKey(opts.idempotencyKey) } : {}
-      };
       if (opts.dryRun) {
         printResult(
-          {
-            dryRun: true,
-            valid: true,
-            action: "transaction confirm-payment",
-            data: sdkParams
-          },
+          sensitiveDryRunResult("payment-session cancel"),
           getFormat2()
         );
         return;
       }
-      const client = getClient2();
-      const result = await client.commerce.orders.confirmPayment(
-        sdkParams
+      printResult(
+        await getClient2().commerce.paymentSessions.cancel(data),
+        getFormat2()
       );
-      printResult(result, getFormat2());
-    } catch (e) {
-      exitWithError(e);
+    } catch (error) {
+      exitWithError(error);
+    }
+  });
+  sessions.command("confirm-toss").description("Confirm a Toss authorization with the typed server action").option("--data-stdin", "Read Toss confirmation params from stdin").option("--data-file <path>", "Read Toss confirmation params from file").option("--dry-run", "Validate inputs without executing").action(async (opts) => {
+    try {
+      const data = parseWithSchema(
+        await readSensitiveJsonObject(opts),
+        "payment-session confirm-toss",
+        ConfirmTossPaymentSessionParamsSchema
+      );
+      if (opts.dryRun) {
+        printResult(
+          sensitiveDryRunResult("payment-session confirm-toss"),
+          getFormat2()
+        );
+        return;
+      }
+      printResult(
+        await getClient2().commerce.paymentSessions.confirm(data),
+        getFormat2()
+      );
+    } catch (error) {
+      exitWithError(error);
     }
   });
 }
 
+// src/lib/product-detail-options.ts
+function invalidOption(message, field, value) {
+  const error = new Error(message);
+  Object.assign(error, {
+    type: "validation",
+    code: "invalid_argument",
+    field,
+    detail: { message, value, field }
+  });
+  return error;
+}
+function parseLocale(value) {
+  if (value == null) return void 0;
+  if (value === "ko" || value === "en" || value === "all") return value;
+  throw invalidOption("--locale must be one of: ko, en, all", "locale", value);
+}
+function parseFallbackLocale(value) {
+  if (value == null) return void 0;
+  if (value === "ko" || value === "en") return value;
+  if (value === "none") return false;
+  throw invalidOption(
+    "--fallback-locale must be one of: ko, en, none",
+    "fallbackLocale",
+    value
+  );
+}
+function productDetailParamsFromOptions(options) {
+  const hasId = typeof options.id === "string" && options.id.length > 0;
+  const hasSlug = typeof options.slug === "string" && options.slug.length > 0;
+  if (hasId === hasSlug) {
+    throw invalidOption(
+      "Exactly one of --id or --slug is required.",
+      "product",
+      { id: options.id, slug: options.slug }
+    );
+  }
+  const locale = parseLocale(options.locale);
+  const fallbackLocale = parseFallbackLocale(options.fallbackLocale);
+  const identifier = hasId ? { id: options.id } : { slug: options.slug };
+  return {
+    ...identifier,
+    ...options.market !== void 0 ? { market: options.market } : {},
+    ...locale !== void 0 ? { locale } : {},
+    ...fallbackLocale !== void 0 ? { fallbackLocale } : {}
+  };
+}
+
 // src/commands/product.ts
 function registerProductCommands(program2, getClient2, getFormat2) {
   const product = program2.command("product").description("Product management");
+  product.command("detail").description("Get shaped product detail by slug or ID").option("--slug <slug>", "Product slug").option("--id <id>", "Product ID").option("--market <market>", "Market slug").option("--locale <locale>", "Locale: ko, en, or all").option("--fallback-locale <locale>", "Fallback locale: ko, en, or none").action(async (opts) => {
+    try {
+      const params = productDetailParamsFromOptions(opts);
+      const client = getClient2();
+      const result = await client.commerce.product.detail(params);
+      printResult(result, getFormat2());
+    } catch (e) {
+      exitWithError(e);
+    }
+  });
   product.command("upsert").description("Create or update a product graph (options, values, variants)").requiredOption("--input <json>", "Product upsert input (JSON)").option("--dry-run", "Validate inputs without executing").action(async (opts) => {
     try {
       const data = parseWithSchema(
@@ -2234,12 +3362,14 @@ function registerShippingCommands(program2, getClient2, getFormat2) {
     "--order-amount <n>",
     "Order amount",
     (v) => parseInt(v, 10)
-  ).option("--shipping-policy-id <id>", "Shipping policy ID").option("--postal-code <code>", "Destination postal code").action(async (opts) => {
+  ).option("--shipping-policy-id <id>", "Shipping policy ID").option("--country-code <code>", "Destination country code").option("--region-code <code>", "Destination region code").option("--postal-code <code>", "Destination postal code").action(async (opts) => {
     try {
       const client = getClient2();
       const result = await client.commerce.shipping.calculate({
         orderAmount: opts.orderAmount,
         ...opts.shippingPolicyId ? { shippingPolicyId: opts.shippingPolicyId } : {},
+        ...opts.countryCode ? { countryCode: opts.countryCode } : {},
+        ...opts.regionCode ? { regionCode: opts.regionCode } : {},
         ...opts.postalCode ? { postalCode: opts.postalCode } : {}
       });
       printResult(result, getFormat2());
@@ -2250,7 +3380,7 @@ function registerShippingCommands(program2, getClient2, getFormat2) {
 }
 
 // src/commands/auth.ts
-import { randomBytes } from "crypto";
+import { randomBytes as randomBytes2 } from "crypto";
 import { createServer } from "http";
 import { execFile, exec } from "child_process";
 import { platform } from "os";
@@ -2425,7 +3555,7 @@ Logged in successfully!`));
 }
 function registerAuthCommands(program2) {
   program2.command("login").description("Login via browser and store credentials").action(async () => {
-    const state = randomBytes(32).toString("hex");
+    const state = randomBytes2(32).toString("hex");
     try {
       const { port } = await startAuthServer({
         state,
@@ -2514,7 +3644,7 @@ ${loginUrl}`));
       );
       process.exit(3);
     }
-    const state = randomBytes(32).toString("hex");
+    const state = randomBytes2(32).toString("hex");
     const isLocal = !!opts.local;
     try {
       const { port } = await startAuthServer({
@@ -2613,9 +3743,15 @@ function registerFeatureCommands(program2, getClient2, getFormat2) {
 }
 
 // src/commands/agent.ts
+import { SERVER_COLLECTIONS as SERVER_COLLECTIONS4 } from "@01.software/sdk";
+
+// src/lib/agent-plan-allowlist.ts
 import { SERVER_COLLECTIONS as SERVER_COLLECTIONS3 } from "@01.software/sdk";
 
 // src/lib/agent-output.ts
+import { randomBytes as randomBytes3 } from "crypto";
+import fs from "fs";
+import path from "path";
 var PLAN_AGENT_ERROR_CODES = /* @__PURE__ */ new Set([
   "PLAN_EXPIRED",
   "PLAN_MISMATCH",
@@ -2632,9 +3768,95 @@ function agentPlanError(code, message) {
   });
   return error;
 }
+var AGENT_OUTPUT_FILE_MODE = 384;
+var isWin32 = process.platform === "win32";
 function stringifyAgentJson(data, options = {}) {
   return options.pretty ? JSON.stringify(data, null, 2) : JSON.stringify(data);
 }
+function invalidOutputTarget(message, outputFile) {
+  const error = new Error(message);
+  Object.assign(error, {
+    type: "validation",
+    code: "invalid_argument",
+    field: "outputFile",
+    detail: { message, field: "outputFile", value: outputFile }
+  });
+  return error;
+}
+function assertSafeAgentOutputTarget(outputFile) {
+  let stat;
+  try {
+    stat = fs.lstatSync(outputFile);
+  } catch (error) {
+    if (error.code === "ENOENT") return;
+    throw error;
+  }
+  if (stat.isSymbolicLink()) {
+    throw invalidOutputTarget(
+      `Refusing to write Agent output through a symlink: ${outputFile}.`,
+      outputFile
+    );
+  }
+  if (!stat.isFile()) {
+    throw invalidOutputTarget(
+      `Refusing to write Agent output to a non-regular file: ${outputFile}.`,
+      outputFile
+    );
+  }
+  if (!isWin32 && stat.nlink > 1) {
+    throw invalidOutputTarget(
+      `Refusing to write Agent output to a file with multiple hard links: ${outputFile}.`,
+      outputFile
+    );
+  }
+}
+function writeAgentOutputFile(requestedPath, content) {
+  const outputFile = path.resolve(requestedPath);
+  assertSafeAgentOutputTarget(outputFile);
+  const tempFile = path.join(
+    path.dirname(outputFile),
+    `.${path.basename(outputFile)}.${randomBytes3(12).toString("hex")}.tmp`
+  );
+  let tempFd;
+  try {
+    tempFd = fs.openSync(tempFile, "wx", AGENT_OUTPUT_FILE_MODE);
+    if (!isWin32) {
+      fs.fchmodSync(tempFd, AGENT_OUTPUT_FILE_MODE);
+    }
+    fs.writeFileSync(tempFd, content, { encoding: "utf8" });
+    fs.closeSync(tempFd);
+    tempFd = void 0;
+    fs.renameSync(tempFile, outputFile);
+  } catch (error) {
+    if (tempFd !== void 0) {
+      try {
+        fs.closeSync(tempFd);
+      } catch {
+      }
+    }
+    try {
+      fs.unlinkSync(tempFile);
+    } catch {
+    }
+    throw error;
+  }
+  return {
+    outputFile,
+    bytes: Buffer.byteLength(content, "utf8")
+  };
+}
+function resolveAgentPrintOptions(command) {
+  const options = command.optsWithGlobals();
+  return {
+    pretty: Boolean(options.pretty),
+    outputFile: options.outputFile
+  };
+}
+function validateAgentOutputTarget(options) {
+  if (options.outputFile !== void 0) {
+    assertSafeAgentOutputTarget(path.resolve(options.outputFile));
+  }
+}
 function asRecord(value) {
   return value && typeof value === "object" ? value : null;
 }
@@ -2660,6 +3882,20 @@ function isRawNotFound(error) {
   const raw = asRecord(error);
   return raw?.status === 404 || raw?.code === "not_found" || raw?.name === "GoneError";
 }
+function isSdkUsageLimitError(error) {
+  const raw = asRecord(error);
+  return raw?.name === "UsageLimitError" || raw?.code === "USAGE_LIMIT_ERROR";
+}
+function agentErrorEnvelope(code, message, retryable, retryAfter) {
+  return {
+    error: {
+      code,
+      message,
+      retryable,
+      ...typeof retryAfter === "number" ? { retryAfter } : {}
+    }
+  };
+}
 function agentErrorExitCode(code) {
   switch (code) {
     case "INVALID_INPUT":
@@ -2683,22 +3919,30 @@ function classifyAgentError(error) {
   const detailRecord = detail && typeof detail === "object" ? detail : null;
   const agentCode = raw?.agentCode ?? detailRecord?.agentCode;
   if (typeof agentCode === "string" && PLAN_AGENT_ERROR_CODES.has(agentCode)) {
-    return { error: { code: agentCode, message } };
+    return agentErrorEnvelope(agentCode, message, false);
   }
   const adminError = classifyError(error);
   if (isRawNotFound(error) || adminError.code === "not_found") {
-    return { error: { code: "NOT_FOUND", message } };
+    return agentErrorEnvelope("NOT_FOUND", message, false);
   }
   if (adminError.type === "permission") {
-    return { error: { code: "AUTH_FAILED", message } };
+    return agentErrorEnvelope("AUTH_FAILED", message, false);
   }
   if (adminError.type === "validation" && adminError.code !== "unknown") {
-    return { error: { code: "INVALID_INPUT", message } };
+    return agentErrorEnvelope("INVALID_INPUT", message, false);
   }
-  return { error: { code: "INTERNAL", message } };
+  const retryable = !isSdkUsageLimitError(error) && (adminError.type === "network" || adminError.type === "degraded");
+  const retryAfter = retryable && adminError.type === "degraded" && adminError.code === "rate_limited" ? adminError.retryAfter : void 0;
+  return agentErrorEnvelope("INTERNAL", message, retryable, retryAfter);
 }
 function printAgentSuccess(data, options = {}) {
-  console.log(stringifyAgentJson(data, options));
+  const output = stringifyAgentJson(data, options);
+  if (options.outputFile !== void 0) {
+    const receipt = writeAgentOutputFile(options.outputFile, output);
+    console.log(JSON.stringify(receipt));
+    return;
+  }
+  console.log(output);
 }
 function printAgentError(error, options = {}) {
   const envelope = classifyAgentError(error);
@@ -2711,25 +3955,77 @@ function exitWithAgentError(error, options = {}) {
 }
 
 // src/lib/agent-plan-allowlist.ts
-var AGENT_PLAN_COLLECTIONS = [
-  "articles",
-  "article-categories",
-  "article-tags",
-  "links",
-  "link-categories",
-  "link-tags"
-];
-var AGENT_PLAN_COLLECTION_SET = new Set(AGENT_PLAN_COLLECTIONS);
+var AGENT_PLAN_CAPABILITIES = {
+  articles: ["create", "update", "delete"],
+  "article-categories": ["create", "update", "delete"],
+  "article-tags": ["create", "update", "delete"],
+  links: ["create", "update", "delete"],
+  "link-categories": ["create", "update", "delete"],
+  "link-tags": ["create", "update", "delete"],
+  documents: ["create", "update"],
+  "document-categories": ["create", "update"],
+  "document-types": ["create", "update"],
+  canvases: ["create", "update", "delete"],
+  "canvas-categories": ["create", "update", "delete"],
+  "canvas-tags": ["create", "update", "delete"]
+};
+var SERVER_COLLECTION_SET = new Set(SERVER_COLLECTIONS3);
+var AGENT_PLAN_OPERATIONS = /* @__PURE__ */ new Set([
+  "create",
+  "update",
+  "delete"
+]);
+function assertAgentPlanCapabilityMatrix(matrix) {
+  for (const [collection, operations] of Object.entries(matrix)) {
+    if (!SERVER_COLLECTION_SET.has(collection)) {
+      throw new Error(
+        `Agent plan capability collection "${collection}" is not a ServerCollection.`
+      );
+    }
+    if (operations.length === 0) {
+      throw new Error(
+        `Agent plan capability collection "${collection}" has no operations.`
+      );
+    }
+    const seen = /* @__PURE__ */ new Set();
+    for (const operation of operations) {
+      if (!AGENT_PLAN_OPERATIONS.has(operation)) {
+        throw new Error(
+          `Agent plan capability operation "${operation}" is invalid for "${collection}".`
+        );
+      }
+      if (seen.has(operation)) {
+        throw new Error(
+          `Agent plan capability operation "${operation}" is duplicated for "${collection}".`
+        );
+      }
+      seen.add(operation);
+    }
+  }
+}
+assertAgentPlanCapabilityMatrix(AGENT_PLAN_CAPABILITIES);
 function isAgentPlanCollection(collection) {
-  return AGENT_PLAN_COLLECTION_SET.has(collection);
+  return Object.prototype.hasOwnProperty.call(
+    AGENT_PLAN_CAPABILITIES,
+    collection
+  );
+}
+function getAgentPlanOperations(collection) {
+  return isAgentPlanCollection(collection) ? AGENT_PLAN_CAPABILITIES[collection] : [];
 }
-function assertAgentPlanCollection(collection) {
-  if (isAgentPlanCollection(collection)) {
+function isAgentPlanCapability(collection, operation) {
+  if (!isAgentPlanCollection(collection)) return false;
+  return AGENT_PLAN_CAPABILITIES[collection].includes(
+    operation
+  );
+}
+function assertAgentPlanCapability(collection, operation) {
+  if (isAgentPlanCapability(collection, operation)) {
     return collection;
   }
   throw agentPlanError(
     "UNSUPPORTED_OPERATION",
-    `Collection "${collection}" is not supported for agent plan mutations.`
+    `Operation "${operation}" is not supported for collection "${collection}" in agent plan mutations.`
   );
 }
 
@@ -2832,6 +4128,12 @@ function parseStoredAgentPlan(raw, planId) {
   if (operation !== "create" && operation !== "update" && operation !== "delete") {
     throw agentPlanError("PLAN_MISMATCH", "Stored plan has invalid operation.");
   }
+  if (!isAgentPlanCapability(collection, operation)) {
+    throw agentPlanError(
+      "PLAN_MISMATCH",
+      "Stored plan has unsupported collection operation."
+    );
+  }
   const payload = record.payload == null ? void 0 : typeof record.payload === "object" && !Array.isArray(record.payload) ? record.payload : (() => {
     throw agentPlanError("PLAN_MISMATCH", "Stored plan payload is invalid.");
   })();
@@ -2856,6 +4158,12 @@ function parseStoredAgentPlan(raw, planId) {
   };
 }
 function assertStoredPlanHashMatches(plan) {
+  if (!isAgentPlanCapability(plan.collection, plan.operation)) {
+    throw agentPlanError(
+      "PLAN_MISMATCH",
+      "Stored plan has unsupported collection operation."
+    );
+  }
   const expected = hashAgentPlanEnvelope({
     operation: plan.operation,
     collection: plan.collection,
@@ -3076,10 +4384,10 @@ function isSecretFieldName(key) {
   const snake = key.replace(/([a-z0-9])([A-Z])/g, "$1_$2").toLowerCase();
   return SECRET_KEY.test(snake);
 }
-function assertNoSecretFields(value, path = "") {
+function assertNoSecretFields(value, path2 = "") {
   if (Array.isArray(value)) {
     value.forEach((item, index) => {
-      assertNoSecretFields(item, `${path}[${index}]`);
+      assertNoSecretFields(item, `${path2}[${index}]`);
     });
     return;
   }
@@ -3087,7 +4395,7 @@ function assertNoSecretFields(value, path = "") {
     return;
   }
   for (const [key, child] of Object.entries(value)) {
-    const fieldPath = path ? `${path}.${key}` : key;
+    const fieldPath = path2 ? `${path2}.${key}` : key;
     if (isSecretFieldName(key)) {
       throw agentPlanError(
         "INVALID_INPUT",
@@ -3129,7 +4437,7 @@ function buildConfirmCommand(planToken, planHash) {
 }
 
 // src/commands/agent-plan.ts
-function invalidInput(message, field) {
+function invalidInput2(message, field) {
   const error = new Error(message);
   Object.assign(error, {
     type: "validation",
@@ -3143,7 +4451,7 @@ function handleCommanderError(error) {
   if (error.code === "commander.helpDisplayed") {
     process.exit(error.exitCode);
   }
-  exitWithAgentError(invalidInput(error.message, "command"));
+  exitWithAgentError(invalidInput2(error.message, "command"));
 }
 function configureAgentParser(command) {
   command.configureOutput({
@@ -3161,9 +4469,12 @@ async function captureBaseUpdatedAt(client, collection, documentId) {
   return readDocumentUpdatedAt(doc);
 }
 async function runPlanAction(input) {
-  const collection = assertAgentPlanCollection(input.collection);
+  const collection = assertAgentPlanCapability(
+    input.collection,
+    input.operation
+  );
   if (input.operation !== "create" && !input.documentId) {
-    throw invalidInput("Missing required argument: id", "id");
+    throw invalidInput2("Missing required argument: id", "id");
   }
   let payload;
   if (input.operation === "create" || input.operation === "update") {
@@ -3225,7 +4536,7 @@ async function runPlanAction(input) {
       documentId: stored.documentId,
       confirmCommand: buildConfirmCommand(planToken, stored.planHash)
     },
-    { pretty: Boolean(input.pretty) }
+    input.outputOptions
   );
 }
 function registerAgentPlanCommands(agent, getClient2) {
@@ -3233,63 +4544,83 @@ function registerAgentPlanCommands(agent, getClient2) {
     agent.command("plan").description("Plan a mutation without executing")
   );
   configureAgentParser(
-    plan.command("create <collection>").description("Plan a document create").option("--data-stdin", "Read mutation JSON from stdin").option("--data-file <path>", "Read mutation JSON from file").option("--pretty", "Print 2-space indented JSON").action(
-      async (collection, opts) => {
+    plan.command("create <collection>").description("Plan a document create").option("--data-stdin", "Read mutation JSON from stdin").option("--data-file <path>", "Read mutation JSON from file").option("--pretty", "Print 2-space indented success JSON").option(
+      "--output-file <path>",
+      "Write success JSON to a secure file and print a receipt"
+    ).action(
+      async (collection, opts, command) => {
+        const outputOptions = resolveAgentPrintOptions(command);
         try {
+          validateAgentOutputTarget(outputOptions);
           await runPlanAction({
             operation: "create",
             collection,
             dataStdin: opts.dataStdin,
             dataFile: opts.dataFile,
-            pretty: opts.pretty,
+            outputOptions,
             getClient: getClient2
           });
         } catch (error) {
-          exitWithAgentError(error, { pretty: Boolean(opts.pretty) });
+          exitWithAgentError(error, outputOptions);
         }
       }
     )
   );
   configureAgentParser(
-    plan.command("update <collection> <id>").description("Plan a document update").option("--data-stdin", "Read mutation JSON from stdin").option("--data-file <path>", "Read mutation JSON from file").option("--pretty", "Print 2-space indented JSON").action(
-      async (collection, id, opts) => {
+    plan.command("update <collection> <id>").description("Plan a document update").option("--data-stdin", "Read mutation JSON from stdin").option("--data-file <path>", "Read mutation JSON from file").option("--pretty", "Print 2-space indented success JSON").option(
+      "--output-file <path>",
+      "Write success JSON to a secure file and print a receipt"
+    ).action(
+      async (collection, id, opts, command) => {
+        const outputOptions = resolveAgentPrintOptions(command);
         try {
+          validateAgentOutputTarget(outputOptions);
           await runPlanAction({
             operation: "update",
             collection,
             documentId: id,
             dataStdin: opts.dataStdin,
             dataFile: opts.dataFile,
-            pretty: opts.pretty,
+            outputOptions,
             getClient: getClient2
           });
         } catch (error) {
-          exitWithAgentError(error, { pretty: Boolean(opts.pretty) });
+          exitWithAgentError(error, outputOptions);
         }
       }
     )
   );
   configureAgentParser(
-    plan.command("delete <collection> <id>").description("Plan a document delete").option("--pretty", "Print 2-space indented JSON").action(
-      async (collection, id, opts) => {
+    plan.command("delete <collection> <id>").description("Plan a document delete").option("--pretty", "Print 2-space indented success JSON").option(
+      "--output-file <path>",
+      "Write success JSON to a secure file and print a receipt"
+    ).action(
+      async (collection, id, opts, command) => {
+        const outputOptions = resolveAgentPrintOptions(command);
         try {
+          validateAgentOutputTarget(outputOptions);
           await runPlanAction({
             operation: "delete",
             collection,
             documentId: id,
-            pretty: opts.pretty,
+            outputOptions,
             getClient: getClient2
           });
         } catch (error) {
-          exitWithAgentError(error, { pretty: Boolean(opts.pretty) });
+          exitWithAgentError(error, outputOptions);
         }
       }
     )
   );
   configureAgentParser(
-    agent.command("confirm <planToken>").description("Execute a previously planned mutation").requiredOption("--hash <planHash>", "Plan hash from plan output").option("--pretty", "Print 2-space indented JSON").action(
-      async (planTokenRaw, opts) => {
+    agent.command("confirm <planToken>").description("Execute a previously planned mutation").requiredOption("--hash <planHash>", "Plan hash from plan output").option("--pretty", "Print 2-space indented success JSON").option(
+      "--output-file <path>",
+      "Write success JSON to a secure file and print a receipt"
+    ).action(
+      async (planTokenRaw, opts, command) => {
+        const outputOptions = resolveAgentPrintOptions(command);
         try {
+          validateAgentOutputTarget(outputOptions);
           const token = decodePlanToken(planTokenRaw);
           if (token.planHash !== opts.hash) {
             throw agentPlanError(
@@ -3335,10 +4666,10 @@ function registerAgentPlanCommands(agent, getClient2) {
               id: doc && typeof doc === "object" && "id" in doc ? String(doc.id) : plan2.documentId,
               doc
             },
-            { pretty: Boolean(opts.pretty) }
+            outputOptions
           );
         } catch (error) {
-          exitWithAgentError(error, { pretty: Boolean(opts.pretty) });
+          exitWithAgentError(error, outputOptions);
         }
       }
     )
@@ -3354,7 +4685,7 @@ function buildStableAgentFields() {
     updatedAt: { type: "string", queryable: true }
   };
 }
-function invalidInput2(message, field, value) {
+function invalidInput3(message, field, value) {
   const error = new Error(message);
   Object.assign(error, {
     type: "validation",
@@ -3367,13 +4698,13 @@ function invalidInput2(message, field, value) {
 function parsePositiveInteger(value, field) {
   if (value == null) return void 0;
   if (/^[1-9]\d*$/.test(value)) return Number(value);
-  throw invalidInput2(`--${field} must be a positive integer`, field, value);
+  throw invalidInput3(`--${field} must be a positive integer`, field, value);
 }
 function handleCommanderError2(error) {
   if (error.code === "commander.helpDisplayed") {
     process.exit(error.exitCode);
   }
-  exitWithAgentError(invalidInput2(error.message, "command"));
+  exitWithAgentError(invalidInput3(error.message, "command"));
 }
 function configureAgentParser2(command) {
   command.configureOutput({
@@ -3394,23 +4725,27 @@ function parseWhere(value) {
       return parsed;
     }
   } catch {
-    throw invalidInput2("--where must be a JSON object", "where", value);
+    throw invalidInput3("--where must be a JSON object", "where", value);
   }
-  throw invalidInput2("--where must be a JSON object", "where", value);
+  throw invalidInput3("--where must be a JSON object", "where", value);
 }
 var AGENT_READ_OPERATIONS = [
   "query",
   "get"
 ];
-var AGENT_PLAN_OPERATIONS = [
-  "plan:create",
-  "plan:update",
-  "plan:delete"
+var AGENT_PRODUCT_OPERATIONS = [
+  "detail"
 ];
 function buildAgentManifest() {
   const collections = {};
-  for (const collection of SERVER_COLLECTIONS3) {
-    const operations = isAgentPlanCollection(collection) ? [...AGENT_READ_OPERATIONS, ...AGENT_PLAN_OPERATIONS] : [...AGENT_READ_OPERATIONS];
+  for (const collection of SERVER_COLLECTIONS4) {
+    const operations = [
+      ...AGENT_READ_OPERATIONS,
+      ...collection === "products" ? AGENT_PRODUCT_OPERATIONS : [],
+      ...getAgentPlanOperations(collection).map(
+        (operation) => `plan:${operation}`
+      )
+    ];
     collections[collection] = {
       operations,
       fields: buildStableAgentFields()
@@ -3418,6 +4753,10 @@ function buildAgentManifest() {
   }
   return {
     version: AGENT_PROTOCOL_VERSION,
+    discovery: {
+      context: { counts: true },
+      schema: { mode: "effective" }
+    },
     collections
   };
 }
@@ -3426,27 +4765,75 @@ function validateAgentCollection(collection) {
     return validateCollection(collection);
   } catch (error) {
     const message = error instanceof Error ? error.message : `Unknown collection "${collection}".`;
-    throw invalidInput2(message, "collection", collection);
+    throw invalidInput3(message, "collection", collection);
   }
 }
 function registerAgentCommands(program2, getClient2) {
   const agent = configureAgentParser2(
-    program2.command("agent").description("Machine-stable CLI namespace for coding agents").addHelpText(
+    program2.command("agent").description("Machine-stable CLI namespace for coding agents").option("--pretty", "Print 2-space indented success JSON").option(
+      "--output-file <path>",
+      "Write success JSON to a secure file and print a receipt"
+    ).addHelpText(
       "after",
       "\nContract: docs/agent-cli-contract.md\nJSON only on stdout; no TTY effects."
     )
   );
   configureAgentParser2(
-    agent.command("manifest").description("Print the Agent CLI protocol manifest").option("--pretty", "Print 2-space indented JSON").action((opts) => {
-      printAgentSuccess(buildAgentManifest(), {
-        pretty: Boolean(opts.pretty)
-      });
+    agent.command("manifest").description("Print the Agent CLI protocol manifest").option("--pretty", "Print 2-space indented success JSON").option(
+      "--output-file <path>",
+      "Write success JSON to a secure file and print a receipt"
+    ).action((_opts, command) => {
+      const outputOptions = resolveAgentPrintOptions(command);
+      try {
+        validateAgentOutputTarget(outputOptions);
+        printAgentSuccess(buildAgentManifest(), outputOptions);
+      } catch (error) {
+        exitWithAgentError(error, outputOptions);
+      }
+    })
+  );
+  configureAgentParser2(
+    agent.command("context").description("Get the active tenant context").option("--counts", "Include collection document counts").option("--pretty", "Print 2-space indented success JSON").option(
+      "--output-file <path>",
+      "Write success JSON to a secure file and print a receipt"
+    ).action(async (opts, command) => {
+      const outputOptions = resolveAgentPrintOptions(command);
+      try {
+        validateAgentOutputTarget(outputOptions);
+        const client = getClient2();
+        const result = opts.counts ? await client.tenant.context({ includeCounts: true }) : await client.tenant.context();
+        printAgentSuccess(result, outputOptions);
+      } catch (error) {
+        exitWithAgentError(error, outputOptions);
+      }
+    })
+  );
+  configureAgentParser2(
+    agent.command("schema <collection>").description("Get the effective field schema for a collection").option("--pretty", "Print 2-space indented success JSON").option(
+      "--output-file <path>",
+      "Write success JSON to a secure file and print a receipt"
+    ).action(async (collection, _opts, command) => {
+      const outputOptions = resolveAgentPrintOptions(command);
+      try {
+        validateAgentOutputTarget(outputOptions);
+        const col = validateAgentCollection(collection);
+        const client = getClient2();
+        const result = await client.tenant.collectionSchema(col);
+        printAgentSuccess(result, outputOptions);
+      } catch (error) {
+        exitWithAgentError(error, outputOptions);
+      }
     })
   );
   configureAgentParser2(
-    agent.command("query <collection>").description("Query documents from a collection").option("--where <json>", "Filter conditions as a JSON object").option("--limit <n>", "Max results").option("--page <n>", "Page number").option("--sort <field>", "Sort field; prefix with - for descending").option("--select <fields>", "Comma-separated fields to select").option("--pretty", "Print 2-space indented JSON").action(
-      async (collection, opts) => {
+    agent.command("query <collection>").description("Query documents from a collection").option("--where <json>", "Filter conditions as a JSON object").option("--limit <n>", "Max results").option("--page <n>", "Page number").option("--sort <field>", "Sort field; prefix with - for descending").option("--select <fields>", "Comma-separated fields to select").option("--pretty", "Print 2-space indented success JSON").option(
+      "--output-file <path>",
+      "Write success JSON to a secure file and print a receipt"
+    ).action(
+      async (collection, opts, command) => {
+        const outputOptions = resolveAgentPrintOptions(command);
         try {
+          validateAgentOutputTarget(outputOptions);
           const col = validateAgentCollection(collection);
           const options = {};
           const where = parseWhere(opts.where);
@@ -3459,28 +4846,55 @@ function registerAgentCommands(program2, getClient2) {
           if (opts.select) options.select = parseSelect(opts.select);
           const client = getClient2();
           const result = await client.collections.from(col).find(options);
-          printAgentSuccess(result, { pretty: Boolean(opts.pretty) });
+          printAgentSuccess(result, outputOptions);
         } catch (error) {
-          exitWithAgentError(error, { pretty: Boolean(opts.pretty) });
+          exitWithAgentError(error, outputOptions);
         }
       }
     )
   );
   configureAgentParser2(
-    agent.command("get <collection> [id]").description("Get a document by ID").option("--select <fields>", "Comma-separated fields to select").option("--pretty", "Print 2-space indented JSON").action(
-      async (collection, id, opts) => {
+    agent.command("get <collection> [id]").description("Get a document by ID").option("--select <fields>", "Comma-separated fields to select").option("--pretty", "Print 2-space indented success JSON").option(
+      "--output-file <path>",
+      "Write success JSON to a secure file and print a receipt"
+    ).action(
+      async (collection, id, opts, command) => {
+        const outputOptions = resolveAgentPrintOptions(command);
         try {
+          validateAgentOutputTarget(outputOptions);
           const col = validateAgentCollection(collection);
           if (!id) {
-            throw invalidInput2("Missing required argument: id", "id");
+            throw invalidInput3("Missing required argument: id", "id");
           }
           const options = {};
           if (opts.select) options.select = parseSelect(opts.select);
           const client = getClient2();
           const result = await client.collections.from(col).findById(id, options);
-          printAgentSuccess(result, { pretty: Boolean(opts.pretty) });
+          printAgentSuccess(result, outputOptions);
+        } catch (error) {
+          exitWithAgentError(error, outputOptions);
+        }
+      }
+    )
+  );
+  const product = configureAgentParser2(
+    agent.command("product").description("Shaped product reads")
+  );
+  configureAgentParser2(
+    product.command("detail").description("Get shaped product detail by slug or ID").option("--slug <slug>", "Product slug").option("--id <id>", "Product ID").option("--market <market>", "Market slug").option("--locale <locale>", "Locale: ko, en, or all").option("--fallback-locale <locale>", "Fallback locale: ko, en, or none").option("--pretty", "Print 2-space indented success JSON").option(
+      "--output-file <path>",
+      "Write success JSON to a secure file and print a receipt"
+    ).action(
+      async (opts, command) => {
+        const outputOptions = resolveAgentPrintOptions(command);
+        try {
+          validateAgentOutputTarget(outputOptions);
+          const params = productDetailParamsFromOptions(opts);
+          const client = getClient2();
+          const result = await client.commerce.product.detail(params);
+          printAgentSuccess(result, outputOptions);
         } catch (error) {
-          exitWithAgentError(error, { pretty: Boolean(opts.pretty) });
+          exitWithAgentError(error, outputOptions);
         }
       }
     )
@@ -3510,7 +4924,7 @@ registerOrderCommands(program, getClient, getFormat);
 registerReturnCommands(program, getClient, getFormat);
 registerCartCommands(program, getClient, getFormat);
 registerStockCommands(program, getClient, getFormat);
-registerTransactionCommands(program, getClient, getFormat);
+registerCommerceSessionCommands(program, getClient, getFormat);
 registerProductCommands(program, getClient, getFormat);
 registerDiscountCommands(program, getClient, getFormat);
 registerShippingCommands(program, getClient, getFormat);