@saasicat/nest 1.0.0-rc.2 → 1.0.0-rc.21

package/dist/{chunk-6Z7JR4EW.js → chunk-M47BNEY2.js}

@@ -1,75 +1,126 @@
+import {
+  AdminAuditService
+} from "./chunk-OOTEXP47.js";
 import {
   PromoCodesService
-} from "./chunk-VXEYLNIB.js";
+} from "./chunk-3RLWML2S.js";
 import {
   SubscriptionContractService
-} from "./chunk-KFT5AIIH.js";
+} from "./chunk-NDLC5GYK.js";
 import {
-  AUDIT_CONTEXT_RESOLVER_TOKEN,
-  PENDING_PLAN_QUERY_PORT_TOKEN,
-  SUBSCRIPTION_USAGE_PORT_TOKEN,
-  SUBSCRIPTION_WRITE_PORT_TOKEN,
-  TENANT_AUTH_GUARDS_TOKEN,
-  TENANT_ID_RESOLVER_TOKEN,
-  TRIAL_PROJECTION_PORT_TOKEN,
-  USAGE_SNAPSHOT_PORT_TOKEN,
-  USER_EMAIL_RESOLVER_TOKEN,
-  USER_ID_RESOLVER_TOKEN
-} from "./chunk-N3L3AICU.js";
-import {
-  AdminAuditService
-} from "./chunk-O2J2HDXA.js";
-import {
-  SaaSiCatPublicRoute
-} from "./chunk-YSC46BGM.js";
+  resolveBundlePriceNet
+} from "./chunk-KPEMTBOP.js";
 import {
   EntitlementService,
   SUBSCRIPTION_BUNDLE_CONFIG_TOKEN,
   SUBSCRIPTION_BUNDLE_REPOSITORY_TOKEN,
+  cancellationHasLanded,
   toEffectiveLimitsSnapshot
-} from "./chunk-VIJ5NJWC.js";
+} from "./chunk-G6EZWECL.js";
+import {
+  ENTITLEMENT_SERVICE_TOKEN
+} from "./chunk-OUDSQ3PU.js";
 import {
-  PLAN_CATALOG_TOKEN,
   findPlan,
   getMarketedPlans,
-  getPlanPriceNet
-} from "./chunk-DQKCK7DX.js";
+  getPlanPriceNet,
+  isPlanNotSoldInCycle,
+  listPriceNet,
+  planNotSoldInCycle
+} from "./chunk-TBBZWZQT.js";
 import {
   SUBSCRIPTION_CONTRACT_REPOSITORY_TOKEN
 } from "./chunk-VBRYPU7V.js";
 import {
-  codedError
-} from "./chunk-57V6ZTI6.js";
-import {
-  ENTITLEMENT_SERVICE_TOKEN
-} from "./chunk-OUDSQ3PU.js";
+  assertContractWindow,
+  assertNoNegativeDiscount,
+  assertOnePlanLine,
+  assertTaxRatePercent,
+  contractTotalsOf,
+  recordContractLinesMoney
+} from "./chunk-6PJE7EWO.js";
 import {
   BUNDLE_REPOSITORY_TOKEN,
   CATALOG_ENTRY_REPOSITORY_TOKEN,
   PLAN_REPOSITORY_TOKEN
-} from "./chunk-AOQJEYOL.js";
+} from "./chunk-3QVGA6JX.js";
+import {
+  ComposedTenantAuthGuard,
+  holdsTenantAdminRole
+} from "./chunk-5CKC7O52.js";
+import {
+  AUDIT_CONTEXT_RESOLVER_TOKEN,
+  CANCELLATION_NOTICE_DAYS_TOKEN,
+  PENDING_PLAN_QUERY_PORT_TOKEN,
+  SUBSCRIPTION_USAGE_PORT_TOKEN,
+  SUBSCRIPTION_WRITE_PORT_TOKEN,
+  TENANT_AUTH_GUARDS_TOKEN,
+  TENANT_ID_RESOLVER_TOKEN,
+  TRIAL_PROJECTION_PORT_TOKEN,
+  USAGE_SNAPSHOT_PORT_TOKEN,
+  USER_EMAIL_RESOLVER_TOKEN,
+  USER_ID_RESOLVER_TOKEN
+} from "./chunk-GPQWGA6B.js";
 import {
-  asProvider
-} from "./chunk-SABTXESR.js";
+  subscriberProviders
+} from "./chunk-WOEJ6K7M.js";
+import {
+  SaaSiCatPublicRoute
+} from "./chunk-YSC46BGM.js";
+import {
+  PLAN_CATALOG_SETTINGS_TOKEN,
+  PLAN_CATALOG_SOURCE_TOKEN,
+  planDefFromVersion
+} from "./chunk-FEQZCWUL.js";
+import {
+  asProvider,
+  codedError
+} from "./chunk-J7NJRK3K.js";
 import {
   __name
 } from "./chunk-SHUYVCID.js";
 
 // src/billing/billing-period.ts
-function advanceOneCycle(d, cycle) {
+function advanceOneCycle(d, cycle, anchorDay) {
+  const year = d.getUTCFullYear() + (cycle === "YEARLY" ? 1 : 0);
+  const month = d.getUTCMonth() + (cycle === "YEARLY" ? 0 : 1);
+  const day = Math.min(usableAnchor(anchorDay) ?? d.getUTCDate(), daysInMonth(year, month));
   const out = new Date(d);
-  if (cycle === "YEARLY") {
-    out.setUTCFullYear(out.getUTCFullYear() + 1);
-  } else {
-    out.setUTCMonth(out.getUTCMonth() + 1);
-  }
+  out.setUTCFullYear(year, month, day);
   return out;
 }
 __name(advanceOneCycle, "advanceOneCycle");
-function periodEndAfter(startedAt, cycle, after) {
-  let candidate = new Date(startedAt ?? after);
+function retreatOneCycle(d, cycle, anchorDay) {
+  const year = d.getUTCFullYear() - (cycle === "YEARLY" ? 1 : 0);
+  const month = d.getUTCMonth() - (cycle === "YEARLY" ? 0 : 1);
+  const normalisedYear = year + Math.floor(month / 12);
+  const normalisedMonth = (month % 12 + 12) % 12;
+  const day = Math.min(usableAnchor(anchorDay) ?? d.getUTCDate(), daysInMonth(normalisedYear, normalisedMonth));
+  const out = new Date(d);
+  out.setUTCFullYear(normalisedYear, normalisedMonth, day);
+  return out;
+}
+__name(retreatOneCycle, "retreatOneCycle");
+function billingAnchorDay(windowStart) {
+  return windowStart.getUTCDate();
+}
+__name(billingAnchorDay, "billingAnchorDay");
+function usableAnchor(anchorDay) {
+  if (anchorDay === void 0) return void 0;
+  if (!Number.isInteger(anchorDay) || anchorDay < 1 || anchorDay > 31) return void 0;
+  return anchorDay;
+}
+__name(usableAnchor, "usableAnchor");
+function daysInMonth(year, month) {
+  return new Date(Date.UTC(year, month + 1, 0)).getUTCDate();
+}
+__name(daysInMonth, "daysInMonth");
+function periodEndAfter(startedAt, cycle, after, anchorDay) {
+  const start = new Date(startedAt ?? after);
+  const anchor = usableAnchor(anchorDay) ?? billingAnchorDay(start);
+  let candidate = start;
   while (candidate <= after) {
-    candidate = advanceOneCycle(candidate, cycle);
+    candidate = advanceOneCycle(candidate, cycle, anchor);
   }
   return candidate;
 }
@@ -81,16 +132,182 @@ function initialPeriodWindow(startedAt, cycle) {
   };
 }
 __name(initialPeriodWindow, "initialPeriodWindow");
-function periodEndWithMinLead(startedAt, cycle, now, minLeadDays = 42) {
+function periodEndWithMinLead(startedAt, cycle, now, minLeadDays = 42, anchorDay) {
   const minLeadMs = minLeadDays * 864e5;
-  let candidate = periodEndAfter(startedAt, cycle, now);
+  const anchor = usableAnchor(anchorDay) ?? billingAnchorDay(new Date(startedAt ?? now));
+  let candidate = periodEndAfter(startedAt, cycle, now, anchor);
   while (candidate.getTime() - now.getTime() < minLeadMs) {
-    candidate = advanceOneCycle(candidate, cycle);
+    candidate = advanceOneCycle(candidate, cycle, anchor);
   }
   return candidate;
 }
 __name(periodEndWithMinLead, "periodEndWithMinLead");
 
+// src/billing/bundle-period.ts
+function daysInMonth2(year, month) {
+  return new Date(Date.UTC(year, month + 1, 0)).getUTCDate();
+}
+__name(daysInMonth2, "daysInMonth");
+function onDayOfMonth(reference, day, timeOfDay) {
+  const year = reference.getUTCFullYear();
+  const month = reference.getUTCMonth();
+  const out = new Date(reference);
+  out.setUTCFullYear(year, month, Math.min(day, daysInMonth2(year, month)));
+  out.setUTCHours(timeOfDay.getUTCHours(), timeOfDay.getUTCMinutes(), timeOfDay.getUTCSeconds(), timeOfDay.getUTCMilliseconds());
+  return out;
+}
+__name(onDayOfMonth, "onDayOfMonth");
+function resolvePlanAnchorDay(source) {
+  const stored = source.billingAnchorDay;
+  if (stored != null && Number.isInteger(stored) && stored >= 1 && stored <= 31) {
+    return stored;
+  }
+  const windowStart = source.currentPeriodStart ?? source.startedAt;
+  return windowStart ? windowStart.getUTCDate() : null;
+}
+__name(resolvePlanAnchorDay, "resolvePlanAnchorDay");
+function bundleFirstPeriodEnd(input) {
+  const { startedAt, cycle, planPeriodEnd, planAnchorDay } = input;
+  if (planPeriodEnd == null) return null;
+  if (cycle === "YEARLY") {
+    return planPeriodEnd > startedAt ? planPeriodEnd : advanceOneCycle(planPeriodEnd, "YEARLY");
+  }
+  const anchor = planAnchorDay ?? planPeriodEnd.getUTCDate();
+  const thisMonth = onDayOfMonth(startedAt, anchor, planPeriodEnd);
+  if (thisMonth > startedAt) return thisMonth;
+  return advanceOneCycle(thisMonth, "MONTHLY", anchor);
+}
+__name(bundleFirstPeriodEnd, "bundleFirstPeriodEnd");
+function bundleFirstPeriodStart(firstPeriodEnd, cycle, planAnchorDay) {
+  return retreatOneCycle(firstPeriodEnd, cycle, planAnchorDay ?? void 0);
+}
+__name(bundleFirstPeriodStart, "bundleFirstPeriodStart");
+function bundleNextPeriodEnd(currentPeriodEnd, cycle, planAnchorDay) {
+  return advanceOneCycle(currentPeriodEnd, cycle, planAnchorDay ?? void 0);
+}
+__name(bundleNextPeriodEnd, "bundleNextPeriodEnd");
+var DEFAULT_BUNDLE_MINIMUM_TERM_MONTHS = 0;
+function bundleCycleFitsPlan(bundleCycle, planCycle) {
+  return !(bundleCycle === "YEARLY" && planCycle === "MONTHLY");
+}
+__name(bundleCycleFitsPlan, "bundleCycleFitsPlan");
+function computeNextBundlePeriod(booking, plan, now) {
+  const endsAt = earliest(plan.endsAt, booking.canceledEffectiveAt ?? booking.canceledAt);
+  if (endsAt !== null && endsAt <= now) return null;
+  const window = booking.currentPeriodEnd === null ? openFirstWindow(booking, plan, now) : rollNextWindow(booking, plan, now);
+  if (window === null) return null;
+  if (endsAt !== null && endsAt <= window.currentPeriodStart) return null;
+  return endsAt !== null && endsAt < window.currentPeriodEnd ? {
+    currentPeriodStart: window.currentPeriodStart,
+    currentPeriodEnd: endsAt
+  } : window;
+}
+__name(computeNextBundlePeriod, "computeNextBundlePeriod");
+function earliest(a, b) {
+  if (a === null) return b;
+  if (b === null) return a;
+  return a <= b ? a : b;
+}
+__name(earliest, "earliest");
+function openFirstWindow(booking, plan, now) {
+  if (booking.billingCycle === null) return null;
+  const planPeriodEnd = plan.currentPeriodEnd ?? null;
+  if (planPeriodEnd === null) return null;
+  const currentPeriodStart = plan.currentPeriodStart ?? now;
+  const firstEnd = bundleFirstPeriodEnd({
+    startedAt: currentPeriodStart,
+    cycle: booking.billingCycle,
+    planPeriodEnd,
+    planAnchorDay: plan.billingAnchorDay
+  });
+  if (firstEnd === null) return null;
+  const currentPeriodEnd = firstEnd > now ? firstEnd : periodEndAfter(firstEnd, booking.billingCycle, now, plan.billingAnchorDay ?? void 0);
+  return {
+    currentPeriodStart,
+    currentPeriodEnd
+  };
+}
+__name(openFirstWindow, "openFirstWindow");
+function rollNextWindow(booking, plan, now) {
+  const currentPeriodStart = booking.currentPeriodEnd;
+  if (currentPeriodStart === null || currentPeriodStart > now) return null;
+  const cycle = booking.billingCycle ?? plan.billingCycle;
+  return {
+    currentPeriodStart,
+    currentPeriodEnd: periodEndAfter(currentPeriodStart, cycle, now, plan.billingAnchorDay ?? void 0)
+  };
+}
+__name(rollNextWindow, "rollNextWindow");
+
+// src/billing/cancellation.ts
+var DAY_MS = 864e5;
+function decideCancellation(input) {
+  const { now, currentPeriodEnd, minimumTermUntil, billingCycle, noticePeriodDays } = input;
+  const anchorDay = input.billingAnchorDay ?? void 0;
+  const candidates = [
+    minimumTermUntil,
+    currentPeriodEnd
+  ].filter((date) => date !== null);
+  const termEndsAt = candidates.length ? new Date(Math.max(...candidates.map((date) => date.getTime()))) : now;
+  if (termEndsAt <= now) {
+    return {
+      effectiveAt: now,
+      termEndsAt,
+      afterNoticeDeadline: false,
+      noticeDeadline: null
+    };
+  }
+  if (noticePeriodDays <= 0) {
+    return {
+      effectiveAt: termEndsAt,
+      termEndsAt,
+      afterNoticeDeadline: false,
+      noticeDeadline: null
+    };
+  }
+  const noticeDeadline = new Date(termEndsAt.getTime() - noticePeriodDays * DAY_MS);
+  if (now <= noticeDeadline) {
+    return {
+      effectiveAt: termEndsAt,
+      termEndsAt,
+      afterNoticeDeadline: false,
+      noticeDeadline
+    };
+  }
+  const steppingAnchor = anchorDay ?? billingAnchorDay(termEndsAt);
+  let effectiveAt = advanceOneCycle(termEndsAt, billingCycle, steppingAnchor);
+  while (effectiveAt.getTime() - now.getTime() < noticePeriodDays * DAY_MS) {
+    effectiveAt = advanceOneCycle(effectiveAt, billingCycle, steppingAnchor);
+  }
+  return {
+    effectiveAt,
+    termEndsAt,
+    afterNoticeDeadline: true,
+    noticeDeadline
+  };
+}
+__name(decideCancellation, "decideCancellation");
+var NO_NOTICE_PERIOD = {
+  monthly: 0,
+  yearly: 0
+};
+function noticeDaysFor(periods, billingCycle) {
+  return billingCycle === "YEARLY" ? periods.yearly : periods.monthly;
+}
+__name(noticeDaysFor, "noticeDaysFor");
+function decideCancellationFor(sub, now, noticePeriodDays) {
+  const isTrial = sub.status === "TRIAL";
+  return decideCancellation({
+    now,
+    currentPeriodEnd: isTrial ? sub.trialEndsAt ?? sub.currentPeriodEnd : sub.currentPeriodEnd,
+    minimumTermUntil: isTrial ? null : sub.minimumTermUntil,
+    billingCycle: sub.billingCycle,
+    noticePeriodDays: isTrial ? 0 : noticePeriodDays,
+    billingAnchorDay: sub.billingAnchorDay
+  });
+}
+__name(decideCancellationFor, "decideCancellationFor");
+
 // src/billing/feature-guard-marker.ts
 var FEATURE_GUARD_MARKER = /* @__PURE__ */ Symbol.for("saasicat/nest/feature-guard");
 function isPlatformFeatureGuard(target) {
@@ -107,11 +324,417 @@ var REQUIRE_FEATURE_KEY = "require-feature";
 var RequireFeature = /* @__PURE__ */ __name((...features) => SetMetadata(REQUIRE_FEATURE_KEY, features), "RequireFeature");
 
 // src/billing/public-catalog.tokens.ts
-var PUBLIC_CATALOG_PROJECT_KEY_TOKEN = /* @__PURE__ */ Symbol.for("saasicat/nest/PublicCatalogProjectKey");
 var PUBLIC_CATALOG_BUNDLE_REPOSITORY_TOKEN = /* @__PURE__ */ Symbol.for("saasicat/nest/PublicCatalogBundleRepository");
 var PUBLIC_CATALOG_MARKETING_REPOSITORY_TOKEN = /* @__PURE__ */ Symbol.for("saasicat/nest/PublicCatalogMarketingRepository");
 var PUBLIC_CATALOG_CATALOG_ENTRY_REPOSITORY_TOKEN = /* @__PURE__ */ Symbol.for("saasicat/nest/PublicCatalogCatalogEntryRepository");
 
+// src/billing/plan-catalog-loader.ts
+import { readFileSync } from "fs";
+import { resolve as resolvePath } from "path";
+import yaml from "js-yaml";
+import Ajv2020 from "ajv/dist/2020.js";
+import addFormats from "ajv-formats";
+import { planCatalogSchema } from "@saasicat/spec";
+
+// src/billing/plan-catalog-environment.ts
+var EnvironmentResolutionFailure = class extends Error {
+  static {
+    __name(this, "EnvironmentResolutionFailure");
+  }
+  problems;
+  constructor(problems) {
+    super(problems.map((p) => p.message).join("\n")), this.problems = problems;
+    this.name = "EnvironmentResolutionFailure";
+  }
+};
+var CREDENTIAL_WORDS = /* @__PURE__ */ new Set([
+  "SECRET",
+  "SECRETS",
+  "TOKEN",
+  "TOKENS",
+  "PASSWORD",
+  "PASSWORDS",
+  "PASSWD",
+  "PWD",
+  "CREDENTIAL",
+  "CREDENTIALS"
+]);
+var CREDENTIAL_KEY_QUALIFIERS = /* @__PURE__ */ new Set([
+  "PRIVATE",
+  "API",
+  "ACCESS",
+  "SIGNING",
+  "SECRET",
+  "AUTH"
+]);
+function namesACredential(variable) {
+  const parts = variable.toUpperCase().split("_");
+  if (parts.some((part) => CREDENTIAL_WORDS.has(part))) return true;
+  return parts.some((part, index) => part === "KEY" && CREDENTIAL_KEY_QUALIFIERS.has(parts[index - 1] ?? ""));
+}
+__name(namesACredential, "namesACredential");
+function isNameStart(ch) {
+  return ch >= "A" && ch <= "Z" || ch >= "a" && ch <= "z" || ch === "_";
+}
+__name(isNameStart, "isNameStart");
+function isNameChar(ch) {
+  return isNameStart(ch) || ch >= "0" && ch <= "9";
+}
+__name(isNameChar, "isNameChar");
+function splitReferences(value) {
+  const segments = [];
+  let literal = "";
+  let index = 0;
+  while (index < value.length) {
+    const ch = value[index];
+    if (ch !== "$") {
+      literal += ch;
+      index += 1;
+      continue;
+    }
+    const reference = readReference(value, index);
+    if (reference === null) {
+      literal += ch;
+      index += 1;
+      continue;
+    }
+    if (literal !== "") segments.push({
+      text: literal
+    });
+    literal = "";
+    segments.push({
+      reference: reference.reference
+    });
+    index = reference.end;
+  }
+  if (literal !== "") segments.push({
+    text: literal
+  });
+  return segments;
+}
+__name(splitReferences, "splitReferences");
+function readReference(value, start) {
+  if (value[start + 1] !== "{") return null;
+  let cursor = start + 2;
+  if (!isNameStart(value[cursor] ?? "")) return null;
+  while (cursor < value.length && isNameChar(value[cursor])) cursor += 1;
+  const name = value.slice(start + 2, cursor);
+  if (value[cursor] === "}") {
+    return {
+      reference: {
+        name,
+        fallback: null
+      },
+      end: cursor + 1
+    };
+  }
+  if (value.startsWith(":-", cursor)) {
+    const close = value.indexOf("}", cursor + 2);
+    if (close === -1) return null;
+    return {
+      reference: {
+        name,
+        fallback: value.slice(cursor + 2, close)
+      },
+      end: close + 1
+    };
+  }
+  return null;
+}
+__name(readReference, "readReference");
+function schemaAt(root, path) {
+  let node = root;
+  for (const segment of path) {
+    if (node === null) return null;
+    node = deref(root, node);
+    if (node.properties && segment in node.properties) {
+      node = node.properties[segment];
+    } else if (node.items && /^\d+$/.test(segment)) {
+      node = node.items;
+    } else if (node.patternProperties) {
+      node = Object.values(node.patternProperties)[0] ?? null;
+    } else if (typeof node.additionalProperties === "object") {
+      node = node.additionalProperties;
+    } else {
+      return null;
+    }
+  }
+  return node === null ? null : deref(root, node);
+}
+__name(schemaAt, "schemaAt");
+function deref(root, node) {
+  if (!node.$ref) return node;
+  const prefix = "#/$defs/";
+  if (!node.$ref.startsWith(prefix)) {
+    throw new Error(`plan-catalog.schema.json uses a $ref this resolver cannot follow: ${node.$ref}`);
+  }
+  const target = root.$defs?.[node.$ref.slice(prefix.length)];
+  if (!target) {
+    throw new Error(`plan-catalog.schema.json refers to a missing definition: ${node.$ref}`);
+  }
+  return target;
+}
+__name(deref, "deref");
+function declaredTypes(node) {
+  if (!node?.type) return /* @__PURE__ */ new Set();
+  return new Set(Array.isArray(node.type) ? node.type : [
+    node.type
+  ]);
+}
+__name(declaredTypes, "declaredTypes");
+var INTEGER_TEXT = /^-?\d+$/;
+var NUMBER_TEXT = /^-?\d+(\.\d+)?$/;
+function readAs(text, types) {
+  if (types.has("string") || types.size === 0) return text;
+  if (types.has("integer") && INTEGER_TEXT.test(text)) return finiteOrUndefined(Number(text));
+  if (types.has("number") && NUMBER_TEXT.test(text)) return finiteOrUndefined(Number(text));
+  if (types.has("boolean") && (text === "true" || text === "false")) return text === "true";
+  if (types.has("null") && text === "null") return null;
+  return void 0;
+}
+__name(readAs, "readAs");
+function finiteOrUndefined(value) {
+  return Number.isFinite(value) ? value : void 0;
+}
+__name(finiteOrUndefined, "finiteOrUndefined");
+function describeTypes(types) {
+  return [
+    ...types
+  ].join(" or ");
+}
+__name(describeTypes, "describeTypes");
+function describeStructure(types) {
+  const shapes = [
+    types.has("array") ? "a list" : null,
+    types.has("object") ? "a block" : null
+  ];
+  return shapes.filter((shape) => shape !== null).join(" or ");
+}
+__name(describeStructure, "describeStructure");
+function pointer(path) {
+  return path.length === 0 ? "" : `/${path.join("/")}`;
+}
+__name(pointer, "pointer");
+function resolveEnvironmentReferences(document, schema, env) {
+  const problems = [];
+  const resolved = walk(document, [], schema, env, problems);
+  if (problems.length > 0) throw new EnvironmentResolutionFailure(problems);
+  return resolved;
+}
+__name(resolveEnvironmentReferences, "resolveEnvironmentReferences");
+function walk(value, path, schema, env, problems) {
+  if (typeof value === "string") {
+    return resolveString(value, path, schema, env, problems);
+  }
+  if (Array.isArray(value)) {
+    return value.map((item, index) => walk(item, [
+      ...path,
+      String(index)
+    ], schema, env, problems));
+  }
+  if (value !== null && typeof value === "object") {
+    const out = {};
+    for (const [key, member] of Object.entries(value)) {
+      Object.defineProperty(out, key, {
+        value: walk(member, [
+          ...path,
+          key
+        ], schema, env, problems),
+        enumerable: true,
+        writable: true,
+        configurable: true
+      });
+    }
+    return out;
+  }
+  return value;
+}
+__name(walk, "walk");
+function resolveString(value, path, schema, env, problems) {
+  const segments = splitReferences(value);
+  const references = segments.flatMap((segment) => "reference" in segment ? [
+    segment.reference
+  ] : []);
+  if (references.length === 0) return value;
+  const instancePath = pointer(path);
+  const named = references.map((r) => `\${${r.name}}`).join(" and ");
+  if (env === null) {
+    for (const { name } of references) {
+      problems.push({
+        instancePath,
+        params: {
+          envVar: name
+        },
+        message: `refers to \${${name}}. References to the environment are resolved only when the platform reads its own configuration file, and this document arrived another way.`
+      });
+    }
+    return value;
+  }
+  const types = declaredTypes(schemaAt(schema, path));
+  let text = "";
+  let complete = true;
+  for (const segment of segments) {
+    if ("text" in segment) {
+      text += segment.text;
+      continue;
+    }
+    const { name, fallback } = segment.reference;
+    if (namesACredential(name)) {
+      problems.push({
+        instancePath,
+        params: {
+          envVar: name
+        },
+        message: `\${${name}} names a credential, and a value the file resolves becomes part of the catalogue \u2014 shown, logged and recorded. Credentials stay in the environment and are read where they are used. Rename the variable if it holds no secret.`
+      });
+      complete = false;
+      continue;
+    }
+    const fromEnv = Object.hasOwn(env, name) ? env[name] : void 0;
+    if (fromEnv !== void 0 && (fromEnv !== "" || fallback === null)) {
+      text += fromEnv;
+    } else if (fallback !== null) {
+      text += fallback;
+    } else {
+      problems.push({
+        instancePath,
+        params: {
+          envVar: name
+        },
+        message: `refers to \${${name}}, which is not set. Set it in the environment, or write a default into the file as \${${name}:-<value>}.`
+      });
+      complete = false;
+    }
+  }
+  if (!complete) return value;
+  const envVar = references[0].name;
+  if (types.has("array") || types.has("object")) {
+    problems.push({
+      instancePath,
+      params: {
+        envVar
+      },
+      message: `${named} stands where the field takes ${describeStructure(types)}. A variable stands in for a single value: write the structure in the file and refer to a variable per entry.`
+    });
+    return value;
+  }
+  const converted = readAs(text, types);
+  if (converted === void 0) {
+    problems.push({
+      instancePath,
+      params: {
+        envVar
+      },
+      message: `${named} resolves to ${JSON.stringify(text)}, and the field takes ${describeTypes(types)}.`
+    });
+    return value;
+  }
+  return converted;
+}
+__name(resolveString, "resolveString");
+
+// src/billing/plan-catalog-loader.ts
+function locate(error) {
+  const segments = (error.instancePath ?? "").split("/").filter(Boolean);
+  const named = error.params?.missingProperty ?? error.params?.additionalProperty;
+  if (named) segments.push(named);
+  return segments.length > 0 ? segments.join(".") : "(document root)";
+}
+__name(locate, "locate");
+var PLAN_CATALOG_UNREADABLE_ERROR = "PlanCatalogUnreadableError";
+var PlanCatalogValidationError = class extends Error {
+  static {
+    __name(this, "PlanCatalogValidationError");
+  }
+  source;
+  errors;
+  constructor(source, errors) {
+    const messages = errors.map((e) => `${locate(e)}: ${e.message ?? "unknown"}`).join("\n  ");
+    super(`Plan catalog validation failed for ${source}:
+  ${messages}`), this.source = source, this.errors = errors;
+    this.name = "PlanCatalogValidationError";
+  }
+};
+function loadPlanCatalogFromFile(opts) {
+  const absolutePath = resolvePath(opts.path);
+  const raw = readFileSync(absolutePath, "utf-8");
+  const catalog = loadPlanCatalogFromString(raw, {
+    source: absolutePath,
+    crossFieldChecks: opts.crossFieldChecks ?? true,
+    // `??` would turn an explicit `null` — refuse every reference — into
+    // the process environment, the one thing that value asks not to read.
+    env: opts.env === void 0 ? process.env : opts.env
+  });
+  SOURCES.set(catalog, absolutePath);
+  return catalog;
+}
+__name(loadPlanCatalogFromFile, "loadPlanCatalogFromFile");
+var SOURCES = /* @__PURE__ */ new WeakMap();
+function catalogSource(catalog) {
+  return SOURCES.get(catalog) ?? null;
+}
+__name(catalogSource, "catalogSource");
+function loadPlanCatalogFromString(yamlContent, opts) {
+  const parsed = yaml.load(yamlContent);
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    const error = new Error(`The YAML content of ${opts.source} is not an object`);
+    error.name = PLAN_CATALOG_UNREADABLE_ERROR;
+    throw error;
+  }
+  const resolved = resolveReferences(parsed, opts.source, opts.env ?? null);
+  const ajv = new Ajv2020({
+    strict: false,
+    allErrors: true
+  });
+  addFormats.default(ajv);
+  const validate = ajv.compile(planCatalogSchema);
+  if (!validate(resolved)) {
+    throw new PlanCatalogValidationError(opts.source, validate.errors ?? []);
+  }
+  const catalog = resolved;
+  if (opts.crossFieldChecks ?? true) {
+    validateConsistency(catalog, opts.source);
+  }
+  return catalog;
+}
+__name(loadPlanCatalogFromString, "loadPlanCatalogFromString");
+function resolveReferences(parsed, source, env) {
+  try {
+    return resolveEnvironmentReferences(parsed, planCatalogSchema, env);
+  } catch (error) {
+    if (error instanceof EnvironmentResolutionFailure) {
+      throw new PlanCatalogValidationError(source, error.problems);
+    }
+    throw error;
+  }
+}
+__name(resolveReferences, "resolveReferences");
+function validateConsistency(catalog, source) {
+  const errors = [];
+  const declaredFeatureKeys = new Set((catalog.features ?? []).map((f) => f.key));
+  const planIds = /* @__PURE__ */ new Set();
+  for (const plan of catalog.plans ?? []) {
+    if (planIds.has(plan.id)) {
+      errors.push(`plans[].id: duplicate plan id "${plan.id}"`);
+    }
+    planIds.add(plan.id);
+    if (catalog.features) {
+      for (const fk of plan.features) {
+        if (!declaredFeatureKeys.has(fk)) {
+          errors.push(`plans[id=${plan.id}].features: Unknown featureKey "${fk}" \u2014 not declared in catalog.features`);
+        }
+      }
+    }
+  }
+  if (errors.length > 0) {
+    const err = new Error(`Plan catalog consistency error in ${source}:
+  ${errors.join("\n  ")}`);
+    err.name = "PlanCatalogConsistencyError";
+    throw err;
+  }
+}
+__name(validateConsistency, "validateConsistency");
+
 // src/billing/feature-ui-registry.tokens.ts
 var BILLING_FEATURE_UI_REGISTRY_TOKEN = /* @__PURE__ */ Symbol.for("saasicat/nest/BillingFeatureUiRegistry");
 
@@ -139,23 +762,21 @@ var PublicCatalogController = class {
   static {
     __name(this, "PublicCatalogController");
   }
-  planCatalog;
+  planCatalogs;
   featureRegistry;
-  projectKey;
   marketingRepo;
   bundleRepo;
   catalogEntryRepo;
-  constructor(planCatalog, featureRegistry, projectKey = null, marketingRepo = null, bundleRepo = null, catalogEntryRepo = null) {
-    this.planCatalog = planCatalog;
+  constructor(planCatalogs, featureRegistry, marketingRepo = null, bundleRepo = null, catalogEntryRepo = null) {
+    this.planCatalogs = planCatalogs;
     this.featureRegistry = featureRegistry;
-    this.projectKey = projectKey;
     this.marketingRepo = marketingRepo;
     this.bundleRepo = bundleRepo;
     this.catalogEntryRepo = catalogEntryRepo;
   }
   async listPlans(lang, localeParam = "de") {
     const locale = lang || localeParam;
-    const plans = getMarketedPlans(this.planCatalog).map((plan) => ({
+    const plans = getMarketedPlans(await this.planCatalogs.current()).map((plan) => ({
       id: plan.id,
       name: plan.name ?? plan.id,
       tagline: plan.tagline ?? "",
@@ -169,12 +790,10 @@ var PublicCatalogController = class {
     return plans;
   }
   async listFeatureRegistry() {
-    if (!this.catalogEntryRepo || !this.projectKey) return this.featureRegistry;
+    if (!this.catalogEntryRepo) return this.featureRegistry;
     let rows;
     try {
-      rows = await this.catalogEntryRepo.listFeatures({
-        projectKey: this.projectKey
-      });
+      rows = await this.catalogEntryRepo.listFeatures({});
     } catch {
       return this.featureRegistry;
     }
@@ -210,10 +829,8 @@ var PublicCatalogController = class {
    */
   async listBundles(lang, localeParam = "de") {
     const locale = lang || localeParam;
-    if (!this.bundleRepo || !this.projectKey) return [];
-    const stems = await this.bundleRepo.list({
-      projectKey: this.projectKey
-    });
+    if (!this.bundleRepo) return [];
+    const stems = await this.bundleRepo.list({});
     const requiresIndex = await this.loadFeatureRequiresIndex();
     const out = [];
     for (const stem of stems) {
@@ -232,20 +849,17 @@ var PublicCatalogController = class {
    * `requiresFeatures` then stays conservatively empty.
    */
   async loadFeatureRequiresIndex() {
-    if (!this.catalogEntryRepo || !this.projectKey) return /* @__PURE__ */ new Map();
+    if (!this.catalogEntryRepo) return /* @__PURE__ */ new Map();
     try {
-      const rows = await this.catalogEntryRepo.listFeatures({
-        projectKey: this.projectKey
-      });
+      const rows = await this.catalogEntryRepo.listFeatures({});
       return buildFeatureRequiresIndex(rows);
     } catch {
       return /* @__PURE__ */ new Map();
     }
   }
   async lookupMarketing(targetType, targetVersionId, locale) {
-    if (!this.marketingRepo || !this.projectKey) return void 0;
+    if (!this.marketingRepo) return void 0;
     const rows = await this.marketingRepo.list({
-      projectKey: this.projectKey,
       targetType,
       targetVersionId,
       locale
@@ -313,23 +927,20 @@ _ts_decorate([
 PublicCatalogController = _ts_decorate([
   Controller("billing"),
   SaaSiCatPublicRoute(),
-  _ts_param(0, Inject(PLAN_CATALOG_TOKEN)),
+  _ts_param(0, Inject(PLAN_CATALOG_SOURCE_TOKEN)),
   _ts_param(1, Inject(BILLING_FEATURE_UI_REGISTRY_TOKEN)),
   _ts_param(2, Optional()),
-  _ts_param(2, Inject(PUBLIC_CATALOG_PROJECT_KEY_TOKEN)),
+  _ts_param(2, Inject(PUBLIC_CATALOG_MARKETING_REPOSITORY_TOKEN)),
   _ts_param(3, Optional()),
-  _ts_param(3, Inject(PUBLIC_CATALOG_MARKETING_REPOSITORY_TOKEN)),
+  _ts_param(3, Inject(PUBLIC_CATALOG_BUNDLE_REPOSITORY_TOKEN)),
   _ts_param(4, Optional()),
-  _ts_param(4, Inject(PUBLIC_CATALOG_BUNDLE_REPOSITORY_TOKEN)),
-  _ts_param(5, Optional()),
-  _ts_param(5, Inject(PUBLIC_CATALOG_CATALOG_ENTRY_REPOSITORY_TOKEN)),
+  _ts_param(4, Inject(PUBLIC_CATALOG_CATALOG_ENTRY_REPOSITORY_TOKEN)),
   _ts_metadata("design:type", Function),
   _ts_metadata("design:paramtypes", [
-    typeof PlanCatalog === "undefined" ? Object : PlanCatalog,
+    typeof PlanCatalogSource === "undefined" ? Object : PlanCatalogSource,
     typeof FeatureUiRegistry === "undefined" ? Object : FeatureUiRegistry,
     Object,
     Object,
-    Object,
     Object
   ])
 ], PublicCatalogController);
@@ -355,12 +966,6 @@ var PublicCatalogModule = class _PublicCatalogModule {
         useValue: options.featureUiRegistry
       }
     ];
-    if (options.projectKey !== void 0) {
-      providers.push({
-        provide: PUBLIC_CATALOG_PROJECT_KEY_TOKEN,
-        useValue: options.projectKey
-      });
-    }
     if (options.bundleRepository) {
       providers.push(asProvider(PUBLIC_CATALOG_BUNDLE_REPOSITORY_TOKEN, options.bundleRepository));
     }
@@ -387,8 +992,8 @@ PublicCatalogModule = _ts_decorate2([
   Module({})
 ], PublicCatalogModule);
 
-// src/billing/composed-tenant-auth.guard.ts
-import { ForbiddenException, Inject as Inject2, Injectable, Optional as Optional2 } from "@nestjs/common";
+// src/billing/tenant-admin.guard.ts
+import { ForbiddenException, Injectable } from "@nestjs/common";
 import { AUTH_ERROR_CODES } from "@saasicat/core";
 function _ts_decorate3(decorators, target, key, desc) {
   var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
@@ -397,86 +1002,22 @@ function _ts_decorate3(decorators, target, key, desc) {
   return c > 3 && r && Object.defineProperty(target, key, r), r;
 }
 __name(_ts_decorate3, "_ts_decorate");
-function _ts_metadata2(k, v) {
-  if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
-}
-__name(_ts_metadata2, "_ts_metadata");
-function _ts_param2(paramIndex, decorator) {
-  return function(target, key) {
-    decorator(target, key, paramIndex);
-  };
-}
-__name(_ts_param2, "_ts_param");
-var ComposedTenantAuthGuard = class {
-  static {
-    __name(this, "ComposedTenantAuthGuard");
-  }
-  guards;
-  constructor(guards = null) {
-    this.guards = guards;
-  }
-  async canActivate(context) {
-    if (!this.guards || this.guards.length === 0) {
-      throw new ForbiddenException({
-        code: AUTH_ERROR_CODES.AUTH_GUARDS_NOT_CONFIGURED,
-        message: "TenantBillingModule.forRoot.authGuards is not configured."
-      });
-    }
-    for (const guard of this.guards) {
-      const result = await Promise.resolve(guard.canActivate(context));
-      if (!result) return false;
-    }
-    return true;
-  }
-};
-ComposedTenantAuthGuard = _ts_decorate3([
-  Injectable(),
-  _ts_param2(0, Optional2()),
-  _ts_param2(0, Inject2(TENANT_AUTH_GUARDS_TOKEN)),
-  _ts_metadata2("design:type", Function),
-  _ts_metadata2("design:paramtypes", [
-    Object
-  ])
-], ComposedTenantAuthGuard);
-
-// src/billing/tenant-admin.guard.ts
-import { ForbiddenException as ForbiddenException2, Injectable as Injectable2 } from "@nestjs/common";
-import { AUTH_ERROR_CODES as AUTH_ERROR_CODES2 } from "@saasicat/core";
-function _ts_decorate4(decorators, target, key, desc) {
-  var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
-  if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
-  else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
-  return c > 3 && r && Object.defineProperty(target, key, r), r;
-}
-__name(_ts_decorate4, "_ts_decorate");
-var ADMIN_ROLES = /* @__PURE__ */ new Set([
-  "TENANT_ADMIN",
-  "SUPER_ADMIN"
-]);
 var TenantAdminGuard = class {
   static {
     __name(this, "TenantAdminGuard");
   }
   canActivate(context) {
-    const request = context.switchToHttp().getRequest();
-    if (!request.user) {
-      throw new ForbiddenException2({
-        code: AUTH_ERROR_CODES2.NOT_AUTHENTICATED,
-        message: "Not authenticated"
-      });
-    }
-    const role = request.user.platformRole ?? request.user.role;
-    if (!role || !ADMIN_ROLES.has(role)) {
-      throw new ForbiddenException2({
-        code: AUTH_ERROR_CODES2.TENANT_ADMIN_REQUIRED,
+    if (!holdsTenantAdminRole(context)) {
+      throw new ForbiddenException({
+        code: AUTH_ERROR_CODES.TENANT_ADMIN_REQUIRED,
         message: "This action requires the TENANT_ADMIN role."
       });
     }
     return true;
   }
 };
-TenantAdminGuard = _ts_decorate4([
-  Injectable2()
+TenantAdminGuard = _ts_decorate3([
+  Injectable()
 ], TenantAdminGuard);
 
 // src/billing/self-service-policy.ts
@@ -484,12 +1025,13 @@ var SELF_SERVICE_BLOCKED_PLANS_TOKEN = /* @__PURE__ */ Symbol.for("saasicat/nest
 var SELF_SERVICE_BLOCKED_BUNDLES_TOKEN = /* @__PURE__ */ Symbol.for("saasicat/nest/SelfServiceBlockedBundles");
 
 // src/billing/proration.ts
-var DAY_MS = 864e5;
+var DAY_MS2 = 864e5;
 function computeProration(input) {
   const { periodStart, periodEnd, now, currentPriceNet, targetPriceNet } = input;
-  const daysInPeriod = Math.max(1, Math.round((periodEnd.getTime() - periodStart.getTime()) / DAY_MS));
-  const daysRemaining = Math.max(0, Math.min(daysInPeriod, Math.round((periodEnd.getTime() - now.getTime()) / DAY_MS)));
-  const prorataDeltaNet = round2((targetPriceNet - currentPriceNet) * daysRemaining / daysInPeriod);
+  const daysInPeriod = Math.max(1, Math.round((periodEnd.getTime() - periodStart.getTime()) / DAY_MS2));
+  const daysRemaining = Math.max(0, Math.min(daysInPeriod, Math.round((periodEnd.getTime() - now.getTime()) / DAY_MS2)));
+  const rawDeltaNet = round2((targetPriceNet - currentPriceNet) * daysRemaining / daysInPeriod);
+  const prorataDeltaNet = Math.max(0, rawDeltaNet);
   return {
     daysRemainingInPeriod: daysRemaining,
     daysInPeriod,
@@ -497,7 +1039,9 @@ function computeProration(input) {
     periodEnd,
     currentPriceNet,
     targetPriceNet,
-    prorataDeltaNet
+    prorataDeltaNet,
+    rawDeltaNet,
+    isFree: rawDeltaNet < 0
   };
 }
 __name(computeProration, "computeProration");
@@ -507,42 +1051,44 @@ function round2(n) {
 __name(round2, "round2");
 
 // src/billing/plan-change-preview.service.ts
-import { Inject as Inject3, Injectable as Injectable3, NotFoundException, Optional as Optional3 } from "@nestjs/common";
+import { Inject as Inject2, Injectable as Injectable2, NotFoundException, Optional as Optional2 } from "@nestjs/common";
 import { BILLING_ERROR_CODES } from "@saasicat/core";
-function _ts_decorate5(decorators, target, key, desc) {
+function _ts_decorate4(decorators, target, key, desc) {
   var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
   if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
   else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
   return c > 3 && r && Object.defineProperty(target, key, r), r;
 }
-__name(_ts_decorate5, "_ts_decorate");
-function _ts_metadata3(k, v) {
+__name(_ts_decorate4, "_ts_decorate");
+function _ts_metadata2(k, v) {
   if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 }
-__name(_ts_metadata3, "_ts_metadata");
-function _ts_param3(paramIndex, decorator) {
+__name(_ts_metadata2, "_ts_metadata");
+function _ts_param2(paramIndex, decorator) {
   return function(target, key) {
     decorator(target, key, paramIndex);
   };
 }
-__name(_ts_param3, "_ts_param");
+__name(_ts_param2, "_ts_param");
 var PlanChangePreviewService = class {
   static {
     __name(this, "PlanChangePreviewService");
   }
-  catalog;
+  catalogs;
   entitlements;
   subscriptions;
   usageSnapshot;
   blockedPlans;
   trialProjection;
-  constructor(catalog, entitlements, subscriptions, usageSnapshot, blockedPlans = null, trialProjection = null) {
-    this.catalog = catalog;
+  subscriptionBundles;
+  constructor(catalogs, entitlements, subscriptions, usageSnapshot, blockedPlans = null, trialProjection = null, subscriptionBundles = null) {
+    this.catalogs = catalogs;
     this.entitlements = entitlements;
     this.subscriptions = subscriptions;
     this.usageSnapshot = usageSnapshot;
     this.blockedPlans = blockedPlans;
     this.trialProjection = trialProjection;
+    this.subscriptionBundles = subscriptionBundles;
   }
   async preview(tenantId, targetPlan, targetCycle, now = /* @__PURE__ */ new Date()) {
     const sub = await this.subscriptions.findForTenant(tenantId);
@@ -555,21 +1101,24 @@ var PlanChangePreviewService = class {
         }
       });
     }
-    const targetPlanDef = findPlan(this.catalog, targetPlan);
+    const catalog = await this.catalogs.current();
+    const targetPlanDef = findPlan(catalog, targetPlan);
     if (!targetPlanDef) {
       throw new NotFoundException({
         code: BILLING_ERROR_CODES.PLAN_NOT_IN_CATALOG,
-        message: `Plan "${targetPlan}" is not in the catalog (${this.catalog.projectKey})`,
+        message: `Plan "${targetPlan}" is not in the catalog`,
         params: {
-          planKey: targetPlan,
-          projectKey: this.catalog.projectKey
+          planKey: targetPlan
         }
       });
     }
     const ctx = {
       currentPeriodStart: sub.currentPeriodStart,
       currentPeriodEnd: sub.currentPeriodEnd,
+      minimumTermUntil: sub.minimumTermUntil ?? null,
       trialEndsAt: sub.trialEndsAt,
+      canceledAt: sub.canceledAt ?? null,
+      canceledEffectiveAt: sub.canceledEffectiveAt ?? null,
       status: sub.status,
       currentBillingCycle: sub.billingCycle,
       currentPlan: sub.plan,
@@ -579,24 +1128,24 @@ var PlanChangePreviewService = class {
       this.entitlements.computeLimits(tenantId, now),
       this.usageSnapshot.snapshot(tenantId)
     ]);
-    const currentPlanDef = findPlan(this.catalog, currentLimits.plan);
+    const currentPlanDef = findPlan(catalog, currentLimits.plan);
     const currentSnap = {
       id: currentLimits.plan,
       name: currentPlanDef?.name ?? currentLimits.plan,
-      monthlyNet: getPlanPriceNet(this.catalog, currentLimits.plan, "MONTHLY"),
-      yearlyNet: getPlanPriceNet(this.catalog, currentLimits.plan, "YEARLY"),
+      monthlyNet: getPlanPriceNet(catalog, currentLimits.plan, "MONTHLY"),
+      yearlyNet: getPlanPriceNet(catalog, currentLimits.plan, "YEARLY"),
       quotas: currentLimits.quotas,
       features: Array.from(currentLimits.features).sort()
     };
     const targetSnap = {
       id: targetPlanDef.id,
       name: targetPlanDef.name ?? targetPlanDef.id,
-      monthlyNet: getPlanPriceNet(this.catalog, targetPlan, "MONTHLY"),
-      yearlyNet: getPlanPriceNet(this.catalog, targetPlan, "YEARLY"),
+      monthlyNet: getPlanPriceNet(catalog, targetPlan, "MONTHLY"),
+      yearlyNet: getPlanPriceNet(catalog, targetPlan, "YEARLY"),
       quotas: targetPlanDef.quotas,
       features: targetPlanDef.features.slice().sort()
     };
-    const changeType = this.classify(sub.plan, sub.billingCycle, targetPlan, targetCycle);
+    const changeType = this.classify(catalog, sub.plan, sub.billingCycle, targetPlan, targetCycle);
     const limitsCheck = {};
     const quotaKeys = /* @__PURE__ */ new Set([
       ...Object.keys(currentLimits.quotas),
@@ -619,45 +1168,103 @@ var PlanChangePreviewService = class {
     const targetFeatureSet = new Set(targetSnap.features);
     const featuresLost = Array.from(currentFeatureSet).filter((f) => !targetFeatureSet.has(f)).sort();
     const featuresGained = targetSnap.features.filter((f) => !currentFeatureSet.has(f));
-    const isImmediate = changeType === "UPGRADE";
+    const planDirection = this.planDirection(catalog, sub.plan, targetPlan);
+    const cycleDirection = this.cycleDirection(sub.billingCycle, targetCycle);
+    const commits = ctx.status !== "TRIAL";
+    const isImmediate = planDirection === "UP" && (!commits || cycleDirection !== "SHORTER");
     const effectiveAt = isImmediate ? null : this.resolveEffectiveAt(ctx, now);
     const proration = isImmediate && ctx.status !== "TRIAL" ? this.computeProration(ctx, now, currentSnap, targetSnap, sub.billingCycle, targetCycle) : null;
     const blockers = [];
     const warnings = [];
+    const landsAt = ctx.canceledEffectiveAt ?? ctx.canceledAt;
+    if (landsAt !== null && landsAt <= now) {
+      blockers.push({
+        code: BILLING_ERROR_CODES.SUBSCRIPTION_ENDED,
+        message: "This subscription has ended. Its plan can no longer be changed."
+      });
+    } else if (landsAt !== null && cycleDirection !== "SAME") {
+      blockers.push({
+        code: BILLING_ERROR_CODES.CANCELLATION_LOCKS_THE_CYCLE,
+        message: "This subscription is cancelled, so its billing cycle cannot change. The plan can."
+      });
+    }
     const blockedTargets = this.blockedPlans?.asTarget ?? [];
     const blockedSources = this.blockedPlans?.asSource ?? [];
+    if (isPlanNotSoldInCycle(targetPlanDef, targetCycle)) {
+      blockers.push(planNotSoldInCycle(targetPlanDef, targetCycle));
+    }
     if (blockedTargets.includes(targetPlan)) {
       blockers.push({
-        code: `${targetPlan}_NOT_SELF_SERVICE`,
-        message: `${targetSnap.name} is only activated via a special contract. Please contact the contract manager.`
+        code: BILLING_ERROR_CODES.PLAN_NOT_SELF_SERVICE,
+        message: `${targetSnap.name} is only activated via a special contract. Please contact the contract manager.`,
+        params: {
+          planName: targetSnap.name,
+          planKey: targetPlan
+        }
       });
     }
     if (blockedSources.includes(sub.plan)) {
       blockers.push({
-        code: `${sub.plan}_LOCKED`,
-        message: `Active ${currentSnap.name} special contract \u2014 please contact the contract manager to change plans.`
+        code: BILLING_ERROR_CODES.PLAN_LOCKED,
+        message: `Active ${currentSnap.name} special contract \u2014 please contact the contract manager to change plans.`,
+        params: {
+          planName: currentSnap.name,
+          planKey: sub.plan
+        }
       });
     }
     for (const [key, row] of Object.entries(limitsCheck)) {
       if (!row.exceeded) continue;
       const usedDisplay = isFloatQuota(key) ? row.used.toFixed(1) : row.used.toString();
       blockers.push({
-        code: `${key.toUpperCase()}_OVER_TARGET`,
-        message: `Current usage ${usedDisplay} exceeds the target limit ${row.targetMax} (${key}) in the ${targetSnap.name} plan. Please reduce usage first.`
+        code: BILLING_ERROR_CODES.QUOTA_OVER_TARGET,
+        message: `Current usage ${usedDisplay} exceeds the target limit ${row.targetMax} (${key}) in the ${targetSnap.name} plan. Please reduce usage first.`,
+        params: {
+          used: usedDisplay,
+          targetMax: row.targetMax,
+          quotaKey: key,
+          planName: targetSnap.name
+        }
       });
     }
     if (featuresLost.length > 0) {
       warnings.push({
-        code: "FEATURES_LOST",
-        message: `Switching means losing access to ${featuresLost.length} feature${featuresLost.length === 1 ? "" : "s"}. Existing data is retained and never deleted \u2014 upgrading again unlocks it.`
+        code: featuresLost.length === 1 ? BILLING_ERROR_CODES.FEATURE_LOST : BILLING_ERROR_CODES.FEATURES_LOST,
+        message: `Switching means losing access to ${featuresLost.length} feature${featuresLost.length === 1 ? "" : "s"}. Existing data is retained and never deleted \u2014 upgrading again unlocks it.`,
+        params: {
+          count: featuresLost.length
+        }
       });
     }
     if (changeType === "NOOP") {
       warnings.push({
-        code: "NO_CHANGE",
+        code: BILLING_ERROR_CODES.NO_CHANGE,
         message: "Target plan and billing cycle already match the current state."
       });
     }
+    if (planDirection === "UP" && cycleDirection === "SHORTER") {
+      warnings.push({
+        code: BILLING_ERROR_CODES.CYCLE_SHORTENS_AT_TERM_END,
+        message: `A ${targetCycle.toLowerCase()} ${targetSnap.name} cannot start inside the ${sub.billingCycle.toLowerCase()} term you are in. The upgrade takes effect when that term ends; to have it today, keep the ${sub.billingCycle.toLowerCase()} cycle.`,
+        params: {
+          targetCycle: targetCycle.toLowerCase(),
+          currentCycle: sub.billingCycle.toLowerCase(),
+          planName: targetSnap.name
+        }
+      });
+    }
+    const changeLandsAt = effectiveAt ?? now;
+    for (const booking of await this.bookingsOutlastingCycle(sub, targetCycle, changeLandsAt)) {
+      blockers.push({
+        code: BILLING_ERROR_CODES.BUNDLE_BOOKING_OUTLASTS_TARGET_CYCLE,
+        message: `A yearly bundle is booked until ${booking.until}. A monthly plan cannot carry it \u2014 cancel the bundle first, or keep the yearly cycle.`,
+        params: {
+          billingCycle: "yearly",
+          planCycle: targetCycle.toLowerCase(),
+          until: booking.until
+        }
+      });
+    }
     const projectedTrialEndsAt = this.trialProjection && sub.status === "TRIAL" ? await this.trialProjection.projectTrialEndsAt({
       currentPlan: sub.plan,
       targetPlan,
@@ -667,6 +1274,8 @@ var PlanChangePreviewService = class {
     }) : null;
     return {
       changeType,
+      planDirection,
+      cycleDirection,
       current: {
         plan: currentSnap,
         billingCycle: sub.billingCycle
@@ -692,16 +1301,53 @@ var PlanChangePreviewService = class {
     const dto = await this.preview(tenantId, targetPlan, targetCycle, now);
     return dto.blockers;
   }
-  classify(currentPlan, currentCycle, targetPlan, targetCycle) {
+  /** Catalog order decides which plan is higher; equal keys are `SAME`. */
+  planDirection(catalog, currentPlan, targetPlan) {
+    if (currentPlan === targetPlan) return "SAME";
+    return this.planRank(catalog, targetPlan) > this.planRank(catalog, currentPlan) ? "UP" : "DOWN";
+  }
+  /**
+   * YEARLY is the longer commitment; anything else is compared against it.
+   *
+   * Written as a comparison rather than a pair of equality checks so a third
+   * cycle — quarterly is the one that keeps being asked for — orders itself
+   * instead of falling into `SAME` and quietly becoming immediate.
+   */
+  cycleDirection(currentCycle, targetCycle) {
+    const rank = /* @__PURE__ */ __name((cycle) => cycle === "YEARLY" ? 1 : 0, "rank");
+    const [from, to] = [
+      rank(currentCycle),
+      rank(targetCycle)
+    ];
+    if (to === from) return "SAME";
+    return to > from ? "LONGER" : "SHORTER";
+  }
+  /**
+   * Active bookings whose own rhythm would not fit `targetCycle`.
+   *
+   * Reads the booking's stored rhythm, not the plan's: a booking with none
+   * follows the plan and therefore fits any plan by construction. Empty
+   * without the bundle module, which is a consumer that has no bookings at
+   * all rather than one whose bookings are being ignored.
+   */
+  async bookingsOutlastingCycle(sub, targetCycle, now) {
+    const subscriptionId = sub.id;
+    if (!this.subscriptionBundles || !subscriptionId) return [];
+    const active = await this.subscriptionBundles.listActiveBySubscription(subscriptionId, now);
+    return active.filter((booking) => booking.billingCycle != null && !bundleCycleFitsPlan(booking.billingCycle, targetCycle)).map((booking) => ({
+      until: (booking.currentPeriodEnd ?? booking.minimumTermEndsAt ?? now).toISOString().slice(0, 10)
+    }));
+  }
+  classify(catalog, currentPlan, currentCycle, targetPlan, targetCycle) {
     if (currentPlan === targetPlan && currentCycle === targetCycle) return "NOOP";
     if (currentPlan === targetPlan) return "CYCLE_CHANGE";
-    const currentRank = this.planRank(currentPlan);
-    const targetRank = this.planRank(targetPlan);
+    const currentRank = this.planRank(catalog, currentPlan);
+    const targetRank = this.planRank(catalog, targetPlan);
     return targetRank > currentRank ? "UPGRADE" : "DOWNGRADE";
   }
   /** Catalog order = rank. Non-marketed plans go to the end. */
-  planRank(planId) {
-    const plans = this.catalog.plans ?? [];
+  planRank(catalog, planId) {
+    const plans = catalog.plans ?? [];
     const idx = plans.findIndex((p) => p.id === planId);
     if (idx === -1) return Number.POSITIVE_INFINITY;
     const plan = plans[idx];
@@ -710,8 +1356,9 @@ var PlanChangePreviewService = class {
   }
   resolveEffectiveAt(ctx, now) {
     if (ctx.status === "TRIAL" && ctx.trialEndsAt) return ctx.trialEndsAt;
-    if (ctx.currentPeriodEnd) return ctx.currentPeriodEnd;
-    return periodEndAfter(ctx.startedAt, ctx.currentBillingCycle, now);
+    const periodEnd = ctx.currentPeriodEnd ?? periodEndAfter(ctx.startedAt, ctx.currentBillingCycle, now);
+    if (ctx.minimumTermUntil && ctx.minimumTermUntil > periodEnd) return ctx.minimumTermUntil;
+    return periodEnd;
   }
   computeProration(ctx, now, current, target, currentCycle, targetCycle) {
     const periodStart = ctx.currentPeriodStart ?? ctx.startedAt ?? now;
@@ -725,23 +1372,26 @@ var PlanChangePreviewService = class {
     });
   }
 };
-PlanChangePreviewService = _ts_decorate5([
-  Injectable3(),
-  _ts_param3(0, Inject3(PLAN_CATALOG_TOKEN)),
-  _ts_param3(1, Inject3(ENTITLEMENT_SERVICE_TOKEN)),
-  _ts_param3(2, Inject3(SUBSCRIPTION_USAGE_PORT_TOKEN)),
-  _ts_param3(3, Inject3(USAGE_SNAPSHOT_PORT_TOKEN)),
-  _ts_param3(4, Optional3()),
-  _ts_param3(4, Inject3(SELF_SERVICE_BLOCKED_PLANS_TOKEN)),
-  _ts_param3(5, Optional3()),
-  _ts_param3(5, Inject3(TRIAL_PROJECTION_PORT_TOKEN)),
-  _ts_metadata3("design:type", Function),
-  _ts_metadata3("design:paramtypes", [
-    typeof PlanCatalog === "undefined" ? Object : PlanCatalog,
+PlanChangePreviewService = _ts_decorate4([
+  Injectable2(),
+  _ts_param2(0, Inject2(PLAN_CATALOG_SOURCE_TOKEN)),
+  _ts_param2(1, Inject2(ENTITLEMENT_SERVICE_TOKEN)),
+  _ts_param2(2, Inject2(SUBSCRIPTION_USAGE_PORT_TOKEN)),
+  _ts_param2(3, Inject2(USAGE_SNAPSHOT_PORT_TOKEN)),
+  _ts_param2(4, Optional2()),
+  _ts_param2(4, Inject2(SELF_SERVICE_BLOCKED_PLANS_TOKEN)),
+  _ts_param2(5, Optional2()),
+  _ts_param2(5, Inject2(TRIAL_PROJECTION_PORT_TOKEN)),
+  _ts_param2(6, Optional2()),
+  _ts_param2(6, Inject2(SUBSCRIPTION_BUNDLE_REPOSITORY_TOKEN)),
+  _ts_metadata2("design:type", Function),
+  _ts_metadata2("design:paramtypes", [
+    typeof PlanCatalogSource === "undefined" ? Object : PlanCatalogSource,
     typeof EntitlementService === "undefined" ? Object : EntitlementService,
     typeof SubscriptionUsagePort === "undefined" ? Object : SubscriptionUsagePort,
     typeof UsageSnapshotPort === "undefined" ? Object : UsageSnapshotPort,
     Object,
+    Object,
     Object
   ])
 ], PlanChangePreviewService);
@@ -757,27 +1407,26 @@ __name(isFloatQuota, "isFloatQuota");
 // src/billing/contract-freeze.tokens.ts
 var CONTRACT_FREEZE_PORT_TOKEN = /* @__PURE__ */ Symbol.for("saasicat/nest/ContractFreezePort");
 var CONTRACT_FREEZE_SOURCE_PORT_TOKEN = /* @__PURE__ */ Symbol.for("saasicat/nest/ContractFreezeSourcePort");
-var CONTRACT_FREEZE_PROJECT_KEY_TOKEN = /* @__PURE__ */ Symbol.for("saasicat/nest/ContractFreezeProjectKey");
 
 // src/billing/pending-plan-materialization.service.ts
-import { Inject as Inject4, Injectable as Injectable4, Logger, Optional as Optional4 } from "@nestjs/common";
-function _ts_decorate6(decorators, target, key, desc) {
+import { Inject as Inject3, Injectable as Injectable3, Logger, Optional as Optional3 } from "@nestjs/common";
+function _ts_decorate5(decorators, target, key, desc) {
   var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
   if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
   else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
   return c > 3 && r && Object.defineProperty(target, key, r), r;
 }
-__name(_ts_decorate6, "_ts_decorate");
-function _ts_metadata4(k, v) {
+__name(_ts_decorate5, "_ts_decorate");
+function _ts_metadata3(k, v) {
   if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 }
-__name(_ts_metadata4, "_ts_metadata");
-function _ts_param4(paramIndex, decorator) {
+__name(_ts_metadata3, "_ts_metadata");
+function _ts_param3(paramIndex, decorator) {
   return function(target, key) {
     decorator(target, key, paramIndex);
   };
 }
-__name(_ts_param4, "_ts_param");
+__name(_ts_param3, "_ts_param");
 var PendingPlanMaterializationService = class _PendingPlanMaterializationService {
   static {
     __name(this, "PendingPlanMaterializationService");
@@ -796,50 +1445,63 @@ var PendingPlanMaterializationService = class _PendingPlanMaterializationService
   async materializeDuePlanChanges(now = /* @__PURE__ */ new Date()) {
     const due = await this.query.findDuePendingPlanChanges(now);
     let applied = 0;
+    let declined = 0;
     for (const change of due) {
+      if (cancellationHasLanded(change, now)) {
+        declined += 1;
+        continue;
+      }
       const cycle = change.pendingBillingCycle ?? "MONTHLY";
       const period = initialPeriodWindow(now, cycle);
       try {
-        await this.subscriptionWrite.changePlanImmediate(change.tenantId, {
+        const result = await this.subscriptionWrite.changePlanImmediate(change.tenantId, {
           planId: change.pendingPlan,
           cycle,
           periodStart: period.start,
           periodEnd: period.end,
           // Status stays (ACTIVE/PAST_DUE etc.) — only the plan is materialized.
-          nextStatus: null
+          nextStatus: null,
+          expectedCanceledAt: change.canceledAt
         });
+        if (!result.claimed) {
+          declined += 1;
+          continue;
+        }
         this.entitlements.invalidateTenant(change.tenantId);
         applied += 1;
       } catch (err) {
         this.logger.error(`Pending plan materialisation failed (tenant ${change.tenantId}): ${String(err)}`);
         continue;
       }
-      await this.tryFreeze(change.tenantId, change.pendingPlan, cycle, now);
+      await this.tryFreeze(change.tenantId, change.pendingPlan, cycle, now, change.canceledEffectiveAt ?? change.canceledAt);
     }
     if (applied > 0) {
       this.logger.log(`Pending plan materialisation: applied ${applied} scheduled plan change(s).`);
     }
+    if (declined > 0) {
+      this.logger.log(`Pending plan materialisation: declined ${declined} change(s) on subscriptions whose cancellation has taken effect.`);
+    }
     return {
       applied
     };
   }
-  async tryFreeze(tenantId, plan, cycle, now) {
+  async tryFreeze(tenantId, plan, cycle, now, endsAt) {
     if (!this.contractFreeze) return;
     try {
-      await this.contractFreeze.freezeOnPlanChange(tenantId, plan, cycle, now);
+      await this.contractFreeze.freezeOnPlanChange(tenantId, plan, cycle, now, endsAt);
     } catch (err) {
       this.logger.error(`Contract freeze after materialisation failed (tenant ${tenantId}): ${String(err)}`);
     }
   }
 };
-PendingPlanMaterializationService = _ts_decorate6([
-  Injectable4(),
-  _ts_param4(0, Inject4(PENDING_PLAN_QUERY_PORT_TOKEN)),
-  _ts_param4(1, Inject4(SUBSCRIPTION_WRITE_PORT_TOKEN)),
-  _ts_param4(3, Optional4()),
-  _ts_param4(3, Inject4(CONTRACT_FREEZE_PORT_TOKEN)),
-  _ts_metadata4("design:type", Function),
-  _ts_metadata4("design:paramtypes", [
+PendingPlanMaterializationService = _ts_decorate5([
+  Injectable3(),
+  _ts_param3(0, Inject3(PENDING_PLAN_QUERY_PORT_TOKEN)),
+  _ts_param3(1, Inject3(SUBSCRIPTION_WRITE_PORT_TOKEN)),
+  _ts_param3(3, Optional3()),
+  _ts_param3(3, Inject3(CONTRACT_FREEZE_PORT_TOKEN)),
+  _ts_metadata3("design:type", Function),
+  _ts_metadata3("design:paramtypes", [
     typeof PendingPlanQueryPort === "undefined" ? Object : PendingPlanQueryPort,
     typeof TenantSubscriptionWritePort === "undefined" ? Object : TenantSubscriptionWritePort,
     typeof EntitlementService === "undefined" ? Object : EntitlementService,
@@ -848,84 +1510,134 @@ PendingPlanMaterializationService = _ts_decorate6([
 ], PendingPlanMaterializationService);
 
 // src/billing/subscription-contract-freeze.service.ts
-import { Inject as Inject5, Injectable as Injectable5 } from "@nestjs/common";
-function _ts_decorate7(decorators, target, key, desc) {
+import { Inject as Inject4, Injectable as Injectable4, Optional as Optional4, UnprocessableEntityException } from "@nestjs/common";
+function _ts_decorate6(decorators, target, key, desc) {
   var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
   if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
   else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
   return c > 3 && r && Object.defineProperty(target, key, r), r;
 }
-__name(_ts_decorate7, "_ts_decorate");
-function _ts_metadata5(k, v) {
+__name(_ts_decorate6, "_ts_decorate");
+function _ts_metadata4(k, v) {
   if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 }
-__name(_ts_metadata5, "_ts_metadata");
-function _ts_param5(paramIndex, decorator) {
+__name(_ts_metadata4, "_ts_metadata");
+function _ts_param4(paramIndex, decorator) {
   return function(target, key) {
     decorator(target, key, paramIndex);
   };
 }
-__name(_ts_param5, "_ts_param");
+__name(_ts_param4, "_ts_param");
 var SubscriptionContractFreezeService = class {
   static {
     __name(this, "SubscriptionContractFreezeService");
   }
-  catalog;
+  catalogs;
   entitlements;
   contracts;
-  projectKey;
   source;
-  constructor(catalog, entitlements, contracts, projectKey, source) {
-    this.catalog = catalog;
+  constructor(catalogs, entitlements, contracts, source, writes = null) {
+    this.catalogs = catalogs;
     this.entitlements = entitlements;
     this.contracts = contracts;
-    this.projectKey = projectKey;
     this.source = source;
+    if (writes?.bindsPlanVersion === false) {
+      throw new Error("The contract freeze records the plan version a subscription is bound to, and this installation's subscription write does not bind it on a plan change. With @saasicat/adapter-prisma, leave `tenantSubscription.synchronizePlanVersion` at its default of true \u2014 or do not configure `contractFreeze`.");
+    }
+  }
+  assertPartyFor(tenantId) {
+    return this.contracts.assertPartyFor(tenantId);
+  }
+  async endOnCancellation(tenantId, effectiveAt) {
+    const active = await this.contracts.findActiveByTenantId(tenantId, effectiveAt);
+    if (!active) return;
+    await this.contracts.terminate(active.id, {
+      effectiveUntil: effectiveAt,
+      // Only when it is already over. An ordinary cancellation lands at
+      // the term end, months out, and the customer is under this contract
+      // until then — the invoice side has to keep finding it, and the
+      // window in `findActiveByTenantId` is what stops it afterwards.
+      status: effectiveAt <= /* @__PURE__ */ new Date() ? "terminated" : null
+    });
+    this.entitlements.invalidateTenant(tenantId);
   }
-  async freezeOnPlanChange(tenantId, newPlan, billingCycle, effectiveFrom) {
+  async freezeOnPlanChange(tenantId, newPlan, billingCycle, effectiveFrom, endsAt = null) {
     const cycle = billingCycle === "YEARLY" ? "yearly" : "monthly";
-    const vatRate = this.catalog.vatRate;
-    const bundles = await this.source.loadBookedBundles(tenantId, cycle, vatRate);
-    const livePlanVersionId = await this.source.findLivePlanVersionId(newPlan);
-    const previous = await this.contracts.findActiveByTenantId(tenantId, effectiveFrom);
-    if (previous) {
-      await this.contracts.terminate(previous.id, {
-        effectiveUntil: effectiveFrom,
-        status: "superseded"
-      });
-    }
-    this.entitlements.invalidateTenant(tenantId);
-    const limits = await this.entitlements.computeLimits(tenantId, effectiveFrom);
-    const planDef = findPlan(this.catalog, newPlan);
-    const planPriceNet = getPlanPriceNet(this.catalog, newPlan, billingCycle) ?? 0;
+    const catalog = await this.catalogs.current();
+    const vatRate = catalog.vatRate;
+    assertTaxRatePercent("catalog.vatRate", vatRate);
+    assertContractWindow(effectiveFrom, endsAt);
+    const bound = await this.source.findBoundPlanVersion(tenantId);
+    if (!bound || bound.planId !== newPlan) {
+      throw new Error(`The contract for tenant ${tenantId} was asked to record plan '${newPlan}', but the subscription is bound to ${bound ? `'${bound.planId}' (version ${bound.id})` : "no plan version"}. Bind the plan version on the subscription before the contract is frozen.`);
+    }
+    const stem = findPlan(catalog, newPlan);
+    const planDef = planDefFromVersion({
+      id: newPlan,
+      name: stem?.name ?? newPlan,
+      tagline: stem?.tagline
+    }, bound);
+    if (isPlanNotSoldInCycle(planDef, billingCycle)) {
+      throw new UnprocessableEntityException(planNotSoldInCycle(planDef, billingCycle));
+    }
+    await this.contracts.assertPartyFor(tenantId);
+    const bundles = await this.source.loadBookedBundles(tenantId, cycle);
+    const planPriceNet = listPriceNet(planDef, billingCycle) ?? 0;
     const planLineItem = {
       kind: "plan",
       sourceKey: newPlan,
-      sourceVersionId: livePlanVersionId,
-      titleSnapshot: planDef?.name ?? newPlan,
-      descriptionSnapshot: planDef?.tagline ?? null,
+      sourceVersionId: bound.id,
+      titleSnapshot: planDef.name ?? newPlan,
+      descriptionSnapshot: planDef.tagline ?? null,
       quantity: 1,
       unit: null,
       priceNet: planPriceNet,
-      priceGross: round22(planPriceNet * (1 + vatRate / 100)),
       billingCycle: cycle,
       minimumTermUntil: null,
-      featuresSnapshot: planDef?.features ?? [],
-      quotaEffectsSnapshot: planDef?.quotas ?? {},
+      featuresSnapshot: planDef.features,
+      quotaEffectsSnapshot: planDef.quotas,
       metadata: null
     };
-    const lineItems = [
+    const lineItems = recordContractLinesMoney([
       planLineItem,
       ...bundles.lineItems
-    ];
-    const subtotalNet = round22(lineItems.reduce((sum, li) => sum + li.priceNet, 0));
+    ], {
+      currency: catalog.currency,
+      taxRate: vatRate
+    });
+    const totals = contractTotalsOf(lineItems, cycle);
+    const priceSnapshot = {
+      currency: catalog.currency,
+      billingCycle: cycle,
+      subtotalNet: totals.subtotalNet,
+      discountNet: totals.discountNet,
+      totalNet: totals.totalNet,
+      vatRate,
+      totalGross: totals.totalGross
+    };
+    assertOnePlanLine(lineItems);
+    assertNoNegativeDiscount({
+      priceSnapshot
+    });
+    const previous = await this.contracts.findActiveByTenantId(tenantId, effectiveFrom);
+    if (previous) {
+      await this.contracts.terminate(previous.id, {
+        effectiveUntil: effectiveFrom,
+        status: "superseded"
+      });
+    }
+    this.entitlements.invalidateTenant(tenantId);
+    const limits = await this.entitlements.computeLimits(tenantId, effectiveFrom, catalog);
     const data = {
-      projectKey: this.projectKey,
       tenantId,
       status: "active",
       effectiveFrom,
-      effectiveUntil: null,
-      originalPlanVersionId: livePlanVersionId,
+      // The successor inherits the ending. A cancellation capped the
+      // contract that was running when it was declared; every contract
+      // after it ends on the same date, or the repair lasts exactly until
+      // the next plan change.
+      effectiveUntil: endsAt,
+      originalPlanVersionId: bound.id,
       originalBundleVersionIds: bundles.bundleVersionIds,
       entitlementSnapshot: {
         plan: limits.plan,
@@ -936,55 +1648,44 @@ var SubscriptionContractFreezeService = class {
           ...limits.features
         ]
       },
-      priceSnapshot: {
-        currency: this.catalog.currency,
-        billingCycle: cycle,
-        subtotalNet,
-        discountNet: 0,
-        totalNet: subtotalNet,
-        vatRate,
-        totalGross: round22(subtotalNet * (1 + vatRate / 100))
-      },
+      priceSnapshot,
       lineItems
     };
     await this.contracts.create(data);
     this.entitlements.invalidateTenant(tenantId);
   }
 };
-SubscriptionContractFreezeService = _ts_decorate7([
-  Injectable5(),
-  _ts_param5(0, Inject5(PLAN_CATALOG_TOKEN)),
-  _ts_param5(1, Inject5(ENTITLEMENT_SERVICE_TOKEN)),
-  _ts_param5(2, Inject5(SubscriptionContractService)),
-  _ts_param5(3, Inject5(CONTRACT_FREEZE_PROJECT_KEY_TOKEN)),
-  _ts_param5(4, Inject5(CONTRACT_FREEZE_SOURCE_PORT_TOKEN)),
-  _ts_metadata5("design:type", Function),
-  _ts_metadata5("design:paramtypes", [
-    typeof PlanCatalog === "undefined" ? Object : PlanCatalog,
+SubscriptionContractFreezeService = _ts_decorate6([
+  Injectable4(),
+  _ts_param4(0, Inject4(PLAN_CATALOG_SOURCE_TOKEN)),
+  _ts_param4(1, Inject4(ENTITLEMENT_SERVICE_TOKEN)),
+  _ts_param4(2, Inject4(SubscriptionContractService)),
+  _ts_param4(3, Inject4(CONTRACT_FREEZE_SOURCE_PORT_TOKEN)),
+  _ts_param4(4, Optional4()),
+  _ts_param4(4, Inject4(SUBSCRIPTION_WRITE_PORT_TOKEN)),
+  _ts_metadata4("design:type", Function),
+  _ts_metadata4("design:paramtypes", [
+    typeof PlanCatalogSource === "undefined" ? Object : PlanCatalogSource,
     typeof EntitlementService === "undefined" ? Object : EntitlementService,
     typeof SubscriptionContractService === "undefined" ? Object : SubscriptionContractService,
-    String,
-    typeof ContractFreezeSourcePort === "undefined" ? Object : ContractFreezeSourcePort
+    typeof ContractFreezeSourcePort === "undefined" ? Object : ContractFreezeSourcePort,
+    Object
   ])
 ], SubscriptionContractFreezeService);
-function round22(value) {
-  return Math.round(value * 100) / 100;
-}
-__name(round22, "round2");
 
 // src/billing/dto/tenant-billing.dto.ts
-import { IsBoolean, IsOptional, IsString, Matches } from "class-validator";
-function _ts_decorate8(decorators, target, key, desc) {
+import { IsISO8601, IsOptional, IsString, Matches } from "class-validator";
+function _ts_decorate7(decorators, target, key, desc) {
   var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
   if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
   else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
   return c > 3 && r && Object.defineProperty(target, key, r), r;
 }
-__name(_ts_decorate8, "_ts_decorate");
-function _ts_metadata6(k, v) {
+__name(_ts_decorate7, "_ts_decorate");
+function _ts_metadata5(k, v) {
   if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 }
-__name(_ts_metadata6, "_ts_metadata");
+__name(_ts_metadata5, "_ts_metadata");
 var PLAN_OR_CYCLE_PATTERN = /^[A-Z][A-Z0-9_]*$/;
 var PreviewPlanChangeDto = class {
   static {
@@ -993,58 +1694,62 @@ var PreviewPlanChangeDto = class {
   plan;
   billingCycle;
 };
-_ts_decorate8([
+_ts_decorate7([
   IsString(),
   Matches(PLAN_OR_CYCLE_PATTERN, {
     message: "plan must be SCREAMING_SNAKE_CASE"
   }),
-  _ts_metadata6("design:type", String)
+  _ts_metadata5("design:type", String)
 ], PreviewPlanChangeDto.prototype, "plan", void 0);
-_ts_decorate8([
+_ts_decorate7([
   IsString(),
   Matches(PLAN_OR_CYCLE_PATTERN, {
     message: "billingCycle must be SCREAMING_SNAKE_CASE (e.g. MONTHLY, YEARLY)"
   }),
-  _ts_metadata6("design:type", String)
+  _ts_metadata5("design:type", String)
 ], PreviewPlanChangeDto.prototype, "billingCycle", void 0);
 var ChangePlanDto = class extends PreviewPlanChangeDto {
   static {
     __name(this, "ChangePlanDto");
   }
-  /** Immediate change (true) vs. change at period end (false/undefined). */
-  effectiveImmediately;
 };
-_ts_decorate8([
-  IsOptional(),
-  IsBoolean(),
-  _ts_metadata6("design:type", Boolean)
-], ChangePlanDto.prototype, "effectiveImmediately", void 0);
 var CancelSubscriptionDto = class {
   static {
     __name(this, "CancelSubscriptionDto");
   }
-  /** true = cancel immediately (status CANCELED). false/undefined = at period end. */
-  immediately;
+  /**
+   * The effective date the page showed before the customer confirmed.
+   *
+   * Optional, and checked rather than trusted: if the server's own decision
+   * differs, the request is refused with the new date so the page can ask
+   * again. The window is small and the consequence is not — a dialog opened
+   * before a notice deadline and confirmed after it promises January 2027 and
+   * would deliver January 2028.
+   *
+   * This is the caller telling the server what only the caller knows: what
+   * the human actually agreed to.
+   */
+  expectedEffectiveAt;
 };
-_ts_decorate8([
+_ts_decorate7([
   IsOptional(),
-  IsBoolean(),
-  _ts_metadata6("design:type", Boolean)
-], CancelSubscriptionDto.prototype, "immediately", void 0);
+  IsISO8601(),
+  _ts_metadata5("design:type", String)
+], CancelSubscriptionDto.prototype, "expectedEffectiveAt", void 0);
 
 // src/billing/dto/onboarding-subscription.dto.ts
 import { ArrayMaxSize, IsArray, IsOptional as IsOptional2, IsString as IsString2, IsUUID, Matches as Matches2 } from "class-validator";
-function _ts_decorate9(decorators, target, key, desc) {
+function _ts_decorate8(decorators, target, key, desc) {
   var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
   if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
   else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
   return c > 3 && r && Object.defineProperty(target, key, r), r;
 }
-__name(_ts_decorate9, "_ts_decorate");
-function _ts_metadata7(k, v) {
+__name(_ts_decorate8, "_ts_decorate");
+function _ts_metadata6(k, v) {
   if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 }
-__name(_ts_metadata7, "_ts_metadata");
+__name(_ts_metadata6, "_ts_metadata");
 var PLAN_OR_CYCLE_PATTERN2 = /^[A-Z][A-Z0-9_]*$/;
 var PROMO_CODE_PATTERN = /^[A-Z0-9_-]{4,32}$/i;
 var CompleteOnboardingSubscriptionDto = class {
@@ -1057,47 +1762,188 @@ var CompleteOnboardingSubscriptionDto = class {
   /**
    * Optional — UUIDs of the BundleVersions that should be booked
    * together with the plan (P11.7.3). Per bundle, the platform
-   * default minimum term (12 months) is set. Bundles are added
+   * default minimum term (none) is set. Bundles are added
    * best-effort **after** the plan change — an error on an individual
    * bundle (e.g. incompatible with the chosen plan) lands as a
    * warning in the response, without rolling back the plan change.
    */
   bundleVersionIds;
 };
-_ts_decorate9([
+_ts_decorate8([
   IsString2(),
   Matches2(PLAN_OR_CYCLE_PATTERN2, {
     message: "plan must be SCREAMING_SNAKE_CASE"
   }),
-  _ts_metadata7("design:type", String)
+  _ts_metadata6("design:type", String)
 ], CompleteOnboardingSubscriptionDto.prototype, "plan", void 0);
-_ts_decorate9([
+_ts_decorate8([
   IsString2(),
   Matches2(PLAN_OR_CYCLE_PATTERN2, {
     message: "billingCycle must be SCREAMING_SNAKE_CASE (e.g. MONTHLY, YEARLY)"
   }),
-  _ts_metadata7("design:type", String)
+  _ts_metadata6("design:type", String)
 ], CompleteOnboardingSubscriptionDto.prototype, "billingCycle", void 0);
+_ts_decorate8([
+  IsOptional2(),
+  IsString2(),
+  Matches2(PROMO_CODE_PATTERN, {
+    message: 'promoCode must consist of A\u2013Z, 0\u20139, "-", "_" (4\u201332 characters)'
+  }),
+  _ts_metadata6("design:type", String)
+], CompleteOnboardingSubscriptionDto.prototype, "promoCode", void 0);
+_ts_decorate8([
+  IsOptional2(),
+  IsArray(),
+  ArrayMaxSize(10),
+  IsUUID("all", {
+    each: true
+  }),
+  _ts_metadata6("design:type", Array)
+], CompleteOnboardingSubscriptionDto.prototype, "bundleVersionIds", void 0);
+
+// src/billing/dto/subscription-bundles.dto.ts
+import { ArrayMaxSize as ArrayMaxSize2, IsArray as IsArray2, IsIn, IsInt, IsOptional as IsOptional3, IsUUID as IsUUID2, Matches as Matches3, Max, Min } from "class-validator";
+import { BUNDLE_PRICE_LOOKUP_LIMIT } from "@saasicat/core";
+function _ts_decorate9(decorators, target, key, desc) {
+  var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+  if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+  else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+  return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+__name(_ts_decorate9, "_ts_decorate");
+function _ts_metadata7(k, v) {
+  if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+}
+__name(_ts_metadata7, "_ts_metadata");
+var ISO_DATE_PATTERN = /^\d{4}-\d{2}-\d{2}(T.*)?$/;
+var AddSubscriptionBundleDto = class {
+  static {
+    __name(this, "AddSubscriptionBundleDto");
+  }
+  bundleVersionId;
+  /**
+   * Optional — override for the minimum term (months). `0` = no
+   * minimum term. Default comes from the `SubscriptionBundleConfig`
+   * (platform = no commitment).
+   */
+  minimumTermMonths;
+  /**
+   * The rhythm to bill this bundle in. Defaults to the plan's.
+   *
+   * A bundle may run in a shorter rhythm than its plan — monthly beside a
+   * yearly plan is the interesting case — but never a longer one. A yearly
+   * bundle on a monthly plan is refused rather than modelled: it has no
+   * boundary to meet, and every one of the plan's twelve period ends is a
+   * moment the plan could stop and leave the bundle committed with nothing to
+   * grant.
+   */
+  billingCycle;
+};
+_ts_decorate9([
+  IsUUID2(),
+  _ts_metadata7("design:type", String)
+], AddSubscriptionBundleDto.prototype, "bundleVersionId", void 0);
+_ts_decorate9([
+  IsOptional3(),
+  IsInt(),
+  Min(0),
+  Max(120),
+  _ts_metadata7("design:type", Number)
+], AddSubscriptionBundleDto.prototype, "minimumTermMonths", void 0);
+_ts_decorate9([
+  IsOptional3(),
+  IsIn([
+    "MONTHLY",
+    "YEARLY"
+  ]),
+  _ts_metadata7("design:type", String)
+], AddSubscriptionBundleDto.prototype, "billingCycle", void 0);
+var PreviewSubscriptionBundleDto = class {
+  static {
+    __name(this, "PreviewSubscriptionBundleDto");
+  }
+  /** Add preview: BundleVersion to be booked. */
+  bundleVersionId;
+  /** Cancel preview: existing Bundle booking. */
+  subscriptionBundleId;
+  /** Add preview only — override analogous to `AddSubscriptionBundleDto`. */
+  minimumTermMonths;
+  /**
+   * Add preview only — the rhythm to quote, analogous to
+   * `AddSubscriptionBundleDto`. Defaults to the plan's.
+   *
+   * The booking has taken this since bundles gained a rhythm of their own.
+   * The preview not taking it meant a tenant asking for a monthly bundle on a
+   * yearly plan was quoted the yearly one and then charged the monthly one —
+   * a preview describing a different contract from the one written, which is
+   * the one thing a preview may never do.
+   */
+  billingCycle;
+};
+_ts_decorate9([
+  IsOptional3(),
+  IsUUID2(),
+  _ts_metadata7("design:type", String)
+], PreviewSubscriptionBundleDto.prototype, "bundleVersionId", void 0);
+_ts_decorate9([
+  IsOptional3(),
+  IsUUID2(),
+  _ts_metadata7("design:type", String)
+], PreviewSubscriptionBundleDto.prototype, "subscriptionBundleId", void 0);
+_ts_decorate9([
+  IsOptional3(),
+  IsInt(),
+  Min(0),
+  Max(120),
+  _ts_metadata7("design:type", Number)
+], PreviewSubscriptionBundleDto.prototype, "minimumTermMonths", void 0);
+_ts_decorate9([
+  IsOptional3(),
+  IsIn([
+    "MONTHLY",
+    "YEARLY"
+  ]),
+  _ts_metadata7("design:type", String)
+], PreviewSubscriptionBundleDto.prototype, "billingCycle", void 0);
+var CancelSubscriptionBundleDto = class {
+  static {
+    __name(this, "CancelSubscriptionBundleDto");
+  }
+  /**
+   * Optional — default = `new Date()` server-side. Format: ISO-8601
+   * (`YYYY-MM-DD` or full timestamp). Usually not set by the tenant
+   * self-service.
+   */
+  canceledAt;
+};
 _ts_decorate9([
-  IsOptional2(),
-  IsString2(),
-  Matches2(PROMO_CODE_PATTERN, {
-    message: 'promoCode must consist of A\u2013Z, 0\u20139, "-", "_" (4\u201332 characters)'
+  IsOptional3(),
+  Matches3(ISO_DATE_PATTERN, {
+    message: "canceledAt must be an ISO date (YYYY-MM-DD)"
   }),
   _ts_metadata7("design:type", String)
-], CompleteOnboardingSubscriptionDto.prototype, "promoCode", void 0);
+], CancelSubscriptionBundleDto.prototype, "canceledAt", void 0);
+var BundlePriceLookupDto = class {
+  static {
+    __name(this, "BundlePriceLookupDto");
+  }
+  /**
+   * Capped rather than unbounded: the caller names what it is displaying, and
+   * a page shows a catalogue, not a database. Each id costs a lookup.
+   */
+  bundleVersionIds;
+};
 _ts_decorate9([
-  IsOptional2(),
-  IsArray(),
-  ArrayMaxSize(10),
-  IsUUID("all", {
+  IsArray2(),
+  ArrayMaxSize2(BUNDLE_PRICE_LOOKUP_LIMIT),
+  IsUUID2("4", {
     each: true
   }),
   _ts_metadata7("design:type", Array)
-], CompleteOnboardingSubscriptionDto.prototype, "bundleVersionIds", void 0);
+], BundlePriceLookupDto.prototype, "bundleVersionIds", void 0);
 
 // src/billing/subscription-bundles.service.ts
-import { Inject as Inject6, Injectable as Injectable6, NotFoundException as NotFoundException2, Optional as Optional5, UnprocessableEntityException } from "@nestjs/common";
+import { Inject as Inject5, Injectable as Injectable5, NotFoundException as NotFoundException2, Optional as Optional5, UnprocessableEntityException as UnprocessableEntityException2 } from "@nestjs/common";
 import { BILLING_ERROR_CODES as BILLING_ERROR_CODES2, CATALOG_ERROR_CODES } from "@saasicat/core";
 function _ts_decorate10(decorators, target, key, desc) {
   var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
@@ -1110,12 +1956,12 @@ function _ts_metadata8(k, v) {
   if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 }
 __name(_ts_metadata8, "_ts_metadata");
-function _ts_param6(paramIndex, decorator) {
+function _ts_param5(paramIndex, decorator) {
   return function(target, key) {
     decorator(target, key, paramIndex);
   };
 }
-__name(_ts_param6, "_ts_param");
+__name(_ts_param5, "_ts_param");
 var SubscriptionBundlesService = class {
   static {
     __name(this, "SubscriptionBundlesService");
@@ -1128,21 +1974,58 @@ var SubscriptionBundlesService = class {
     this.repo = repo;
     this.bundles = bundles;
     this.blockedBundles = blockedBundles;
-    this.defaultMinTermMonths = config.defaultMinimumTermMonths ?? 12;
+    this.defaultMinTermMonths = config.defaultMinimumTermMonths ?? DEFAULT_BUNDLE_MINIMUM_TERM_MONTHS;
   }
   /** All bundle bookings of a subscription (for the "My Bundles" page). */
-  async listForSubscription(subscriptionId) {
+  /**
+  * The tenant's bookings, with the price each one is actually billed at.
+  *
+  * `planKey` is required because a price is not a property of a bundle
+  * alone: a `BundlePricingOverride` can set a different one per plan, and
+  * the rhythm decides which of the two figures applies. Returning the base
+  * monthly price regardless — which this did until 2026-08-27 — puts a
+  * number on the tenant's screen that nobody is charged, and on a yearly
+  * booking it was out by whatever the yearly price is.
+  */
+  async listForSubscription(subscriptionId, planKey, planCycle) {
     const records = await this.repo.listBySubscription(subscriptionId);
     return Promise.all(records.map(async (r) => {
       const bv = await this.bundles.findVersionById(r.bundleVersionId);
+      const cycle = r.billingCycle ?? planCycle;
       return {
         ...r,
         bundleKey: bv?.bundleKey ?? null,
         label: bv?.label ?? null,
-        monthlyNet: bv?.monthlyNet ?? null
+        priceNet: bv ? resolveBundlePriceNet(bv, planKey, cycle) : null
       };
     }));
   }
+  /**
+   * List prices for the given bundle versions, in both rhythms, resolved for
+   * one plan.
+   *
+   * The public catalogue cannot answer this: it has no tenant and therefore
+   * no plan, so it serves the base prices and a bundle priced only through an
+   * override reads as having no price at all. A tenant UI that treated those
+   * fields as final hid such a bundle behind "not available in this rhythm"
+   * while the booking would have gone through.
+   */
+  async resolvePricesFor(planKey, bundleVersionIds) {
+    const entries = await Promise.all(bundleVersionIds.map(async (id) => {
+      const bv = await this.bundles.findVersionById(id);
+      if (!bv || !isLive(bv)) return null;
+      const stem = await this.bundles.findById(bv.bundleId);
+      if (!stem || stem.deletedAt !== null) return null;
+      return [
+        id,
+        {
+          monthlyNet: resolveBundlePriceNet(bv, planKey, "MONTHLY"),
+          yearlyNet: resolveBundlePriceNet(bv, planKey, "YEARLY")
+        }
+      ];
+    }));
+    return Object.fromEntries(entries.filter((entry) => entry !== null));
+  }
   async addBundleToSubscription(input) {
     const bundleVersion = await this.bundles.findVersionById(input.bundleVersionId);
     if (!bundleVersion) {
@@ -1155,7 +2038,7 @@ var SubscriptionBundlesService = class {
       });
     }
     if (bundleVersion.publishedAt === null) {
-      throw new UnprocessableEntityException({
+      throw new UnprocessableEntityException2({
         code: CATALOG_ERROR_CODES.BUNDLE_VERSION_NOT_PUBLISHED,
         message: `BundleVersion '${input.bundleVersionId}' is not published and cannot be booked.`,
         params: {
@@ -1164,7 +2047,7 @@ var SubscriptionBundlesService = class {
       });
     }
     if (bundleVersion.supersededAt !== null) {
-      throw new UnprocessableEntityException({
+      throw new UnprocessableEntityException2({
         code: CATALOG_ERROR_CODES.BUNDLE_VERSION_SUPERSEDED,
         message: `BundleVersion '${input.bundleVersionId}' has been superseded by a newer version.`,
         params: {
@@ -1173,7 +2056,7 @@ var SubscriptionBundlesService = class {
       });
     }
     if (this.blockedBundles?.bundleKeys?.includes(bundleVersion.bundleKey)) {
-      throw new UnprocessableEntityException({
+      throw new UnprocessableEntityException2({
         code: BILLING_ERROR_CODES2.BUNDLE_NOT_SELF_SERVICE,
         message: `Bundle '${bundleVersion.bundleKey}' is only activated via a special contract. Please contact the contract manager.`,
         params: {
@@ -1183,7 +2066,7 @@ var SubscriptionBundlesService = class {
     }
     const planIds = bundleVersion.compatibility?.planIds ?? [];
     if (planIds.length > 0 && !planIds.includes(input.currentPlanKey)) {
-      throw new UnprocessableEntityException({
+      throw new UnprocessableEntityException2({
         code: BILLING_ERROR_CODES2.BUNDLE_INCOMPATIBLE_WITH_PLAN,
         message: `BundleVersion '${input.bundleVersionId}' is not compatible with plan '${input.currentPlanKey}'. Allowed: [${planIds.join(", ")}].`,
         params: {
@@ -1195,7 +2078,7 @@ var SubscriptionBundlesService = class {
     }
     const active = await this.repo.listActiveBySubscription(input.subscriptionId);
     if (active.some((b) => b.bundleVersionId === input.bundleVersionId)) {
-      throw new UnprocessableEntityException({
+      throw new UnprocessableEntityException2({
         code: BILLING_ERROR_CODES2.BUNDLE_ALREADY_SUBSCRIBED,
         message: `Subscription '${input.subscriptionId}' has already actively booked this bundle.`,
         params: {
@@ -1204,13 +2087,48 @@ var SubscriptionBundlesService = class {
       });
     }
     const startedAt = input.startedAt ?? /* @__PURE__ */ new Date();
+    const billingCycle = input.billingCycle ?? input.planCycle;
+    if (resolveBundlePriceNet(bundleVersion, input.currentPlanKey, billingCycle) === null) {
+      throw new UnprocessableEntityException2({
+        code: BILLING_ERROR_CODES2.BUNDLE_NOT_PRICED_FOR_THIS_PLAN,
+        message: `This bundle has no ${billingCycle.toLowerCase()} price for the ${input.currentPlanKey} plan, so it cannot be booked.`,
+        params: {
+          billingCycle,
+          planKey: input.currentPlanKey
+        }
+      });
+    }
+    if (!bundleCycleFitsPlan(billingCycle, input.planCycle)) {
+      throw new UnprocessableEntityException2({
+        code: BILLING_ERROR_CODES2.BUNDLE_CYCLE_EXCEEDS_PLAN,
+        message: `A ${billingCycle.toLowerCase()} bundle cannot be booked on a ${input.planCycle.toLowerCase()} plan: its term would outlast the plan that pays for it.`,
+        params: {
+          billingCycle,
+          planCycle: input.planCycle
+        }
+      });
+    }
+    const currentPeriodEnd = bundleFirstPeriodEnd({
+      startedAt,
+      cycle: billingCycle,
+      planPeriodEnd: input.planPeriodEnd,
+      planAnchorDay: input.planAnchorDay
+    });
     const minimumTermMonths = input.minimumTermMonths ?? this.defaultMinTermMonths;
-    const minimumTermEndsAt = minimumTermMonths > 0 ? addMonths(startedAt, minimumTermMonths) : null;
+    const minimumTermEndsAt = clampToParent(minimumTermMonths > 0 ? addMonths(startedAt, minimumTermMonths) : null, input.parentEndsAt);
     return this.repo.add({
       subscriptionId: input.subscriptionId,
       bundleVersionId: input.bundleVersionId,
       startedAt,
-      minimumTermEndsAt
+      minimumTermEndsAt,
+      billingCycle,
+      // Both ends together or neither. A start without an end is a window
+      // that cannot be reasoned about: it is not running (nothing says
+      // when it stops) and it is not absent (something is written), and
+      // every reader would have to pick one. A booking made while its plan
+      // had no period has no period of its own either, and says so.
+      currentPeriodStart: currentPeriodEnd === null ? null : startedAt,
+      currentPeriodEnd
     });
   }
   async cancelBundleFromSubscription(input) {
@@ -1225,7 +2143,7 @@ var SubscriptionBundlesService = class {
       });
     }
     if (existing.canceledAt !== null) {
-      throw new UnprocessableEntityException({
+      throw new UnprocessableEntityException2({
         code: BILLING_ERROR_CODES2.SUBSCRIPTION_BUNDLE_ALREADY_CANCELLED,
         message: `SubscriptionBundle '${input.subscriptionBundleId}' is already cancelled.`,
         params: {
@@ -1236,8 +2154,15 @@ var SubscriptionBundlesService = class {
     const canceledAt = input.canceledAt ?? /* @__PURE__ */ new Date();
     const canceledEffectiveAt = resolveBundleCancelEffectiveAt({
       canceledAt,
-      currentPeriodEnd: input.currentPeriodEnd ?? null,
-      minimumTermEndsAt: existing.minimumTermEndsAt
+      // The booking's own period, not the plan's. A monthly bundle beside
+      // a yearly plan ends its month long before the plan ends its year,
+      // and reading the plan's boundary kept such a booking committed —
+      // and billed — until the annual renewal. The plan's boundary is the
+      // fallback for a booking made before bundles had periods, which is
+      // what those were billed against.
+      currentPeriodEnd: existing.currentPeriodEnd ?? input.currentPeriodEnd ?? null,
+      minimumTermEndsAt: existing.minimumTermEndsAt,
+      parentEndsAt: input.parentEndsAt
     });
     return this.repo.cancel(input.subscriptionBundleId, {
       canceledAt,
@@ -1260,7 +2185,7 @@ var SubscriptionBundlesService = class {
       });
     }
     if (existing.canceledAt === null) {
-      throw new UnprocessableEntityException({
+      throw new UnprocessableEntityException2({
         code: BILLING_ERROR_CODES2.SUBSCRIPTION_BUNDLE_NOT_CANCELLED,
         message: `SubscriptionBundle '${subscriptionBundleId}' is not cancelled.`,
         params: {
@@ -1269,7 +2194,7 @@ var SubscriptionBundlesService = class {
       });
     }
     if (existing.canceledEffectiveAt !== null && existing.canceledEffectiveAt <= /* @__PURE__ */ new Date()) {
-      throw new UnprocessableEntityException({
+      throw new UnprocessableEntityException2({
         code: BILLING_ERROR_CODES2.SUBSCRIPTION_BUNDLE_CANCELLATION_EFFECTIVE,
         message: "Cancellation already in effect \u2014 book the bundle again."
       });
@@ -1278,13 +2203,13 @@ var SubscriptionBundlesService = class {
   }
 };
 SubscriptionBundlesService = _ts_decorate10([
-  Injectable6(),
-  _ts_param6(0, Inject6(SUBSCRIPTION_BUNDLE_REPOSITORY_TOKEN)),
-  _ts_param6(1, Inject6(BUNDLE_REPOSITORY_TOKEN)),
-  _ts_param6(2, Optional5()),
-  _ts_param6(2, Inject6(SUBSCRIPTION_BUNDLE_CONFIG_TOKEN)),
-  _ts_param6(3, Optional5()),
-  _ts_param6(3, Inject6(SELF_SERVICE_BLOCKED_BUNDLES_TOKEN)),
+  Injectable5(),
+  _ts_param5(0, Inject5(SUBSCRIPTION_BUNDLE_REPOSITORY_TOKEN)),
+  _ts_param5(1, Inject5(BUNDLE_REPOSITORY_TOKEN)),
+  _ts_param5(2, Optional5()),
+  _ts_param5(2, Inject5(SUBSCRIPTION_BUNDLE_CONFIG_TOKEN)),
+  _ts_param5(3, Optional5()),
+  _ts_param5(3, Inject5(SELF_SERVICE_BLOCKED_BUNDLES_TOKEN)),
   _ts_metadata8("design:type", Function),
   _ts_metadata8("design:paramtypes", [
     typeof SubscriptionBundleRepository === "undefined" ? Object : SubscriptionBundleRepository,
@@ -1296,7 +2221,9 @@ SubscriptionBundlesService = _ts_decorate10([
 function resolveBundleCancelEffectiveAt(input) {
   const periodEnd = input.currentPeriodEnd ?? input.canceledAt;
   const minTermEnd = input.minimumTermEndsAt ?? input.canceledAt;
-  return periodEnd.getTime() >= minTermEnd.getTime() ? periodEnd : minTermEnd;
+  const later = periodEnd.getTime() >= minTermEnd.getTime() ? periodEnd : minTermEnd;
+  if (input.parentEndsAt === null) return later;
+  return later.getTime() <= input.parentEndsAt.getTime() ? later : input.parentEndsAt;
 }
 __name(resolveBundleCancelEffectiveAt, "resolveBundleCancelEffectiveAt");
 function addMonths(date, months) {
@@ -1305,10 +2232,19 @@ function addMonths(date, months) {
   return out;
 }
 __name(addMonths, "addMonths");
+function isLive(version) {
+  return version.publishedAt !== null && version.supersededAt === null;
+}
+__name(isLive, "isLive");
+function clampToParent(ownTermEndsAt, parentEndsAt) {
+  if (ownTermEndsAt === null || parentEndsAt === null) return ownTermEndsAt;
+  return ownTermEndsAt < parentEndsAt ? ownTermEndsAt : parentEndsAt;
+}
+__name(clampToParent, "clampToParent");
 
 // src/billing/tenant-billing.controller.ts
-import { BadRequestException, Body, Controller as Controller2, ForbiddenException as ForbiddenException3, Get as Get2, HttpCode, HttpStatus, Inject as Inject7, Logger as Logger2, NotFoundException as NotFoundException3, Optional as Optional6, Post, Req, UseGuards } from "@nestjs/common";
-import { AUTH_ERROR_CODES as AUTH_ERROR_CODES3, BILLING_ERROR_CODES as BILLING_ERROR_CODES3 } from "@saasicat/core";
+import { BadRequestException, Body, Controller as Controller2, ForbiddenException as ForbiddenException2, Get as Get2, HttpCode, HttpStatus, Inject as Inject6, Logger as Logger2, ConflictException, NotFoundException as NotFoundException3, Optional as Optional6, Post, Req, UseGuards } from "@nestjs/common";
+import { AUTH_ERROR_CODES as AUTH_ERROR_CODES2, BILLING_ERROR_CODES as BILLING_ERROR_CODES3 } from "@saasicat/core";
 function _ts_decorate11(decorators, target, key, desc) {
   var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
   if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
@@ -1320,12 +2256,12 @@ function _ts_metadata9(k, v) {
   if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 }
 __name(_ts_metadata9, "_ts_metadata");
-function _ts_param7(paramIndex, decorator) {
+function _ts_param6(paramIndex, decorator) {
   return function(target, key) {
     decorator(target, key, paramIndex);
   };
 }
-__name(_ts_param7, "_ts_param");
+__name(_ts_param6, "_ts_param");
 var TenantBillingController = class _TenantBillingController {
   static {
     __name(this, "TenantBillingController");
@@ -1345,7 +2281,8 @@ var TenantBillingController = class _TenantBillingController {
   subscriptionBundles;
   contractFreeze;
   trialProjection;
-  constructor(entitlements, planPreview, subscriptionUsage, usageSnapshot, subscriptionWrite, tenantIdResolver = null, userIdResolver = null, blockedPlans = null, promoCodes = null, auditService = null, userEmailResolver = null, auditContextResolver = null, subscriptionBundles = null, contractFreeze = null, trialProjection = null) {
+  cancellationNoticeDays;
+  constructor(entitlements, planPreview, subscriptionUsage, usageSnapshot, subscriptionWrite, tenantIdResolver = null, userIdResolver = null, blockedPlans = null, promoCodes = null, auditService = null, userEmailResolver = null, auditContextResolver = null, subscriptionBundles = null, contractFreeze = null, trialProjection = null, cancellationNoticeDays = NO_NOTICE_PERIOD) {
     this.entitlements = entitlements;
     this.planPreview = planPreview;
     this.subscriptionUsage = subscriptionUsage;
@@ -1361,6 +2298,7 @@ var TenantBillingController = class _TenantBillingController {
     this.subscriptionBundles = subscriptionBundles;
     this.contractFreeze = contractFreeze;
     this.trialProjection = trialProjection;
+    this.cancellationNoticeDays = cancellationNoticeDays;
   }
   logger = new Logger2(_TenantBillingController.name);
   // ---------------------------------------------------------------------
@@ -1413,6 +2351,23 @@ var TenantBillingController = class _TenantBillingController {
       pendingPlanVersionEffectiveAt: sub.pendingPlanVersionEffectiveAt,
       pendingPlanVersionAccepted: sub.pendingPlanVersionAccepted,
       pendingPlanVersionAcceptedAt: sub.pendingPlanVersionAcceptedAt,
+      canceledAt: sub.canceledAt ?? null,
+      // The same fallback the renewal and the cancel route apply, for the
+      // same reason: on a row written before the two fields separated,
+      // `canceledAt` IS the effective date and the second column is
+      // genuinely null. Reading it strictly here told the page the
+      // subscription was never cancelled — so it hid the end date and
+      // went on offering to cancel something that already had been.
+      canceledEffectiveAt: sub.canceledEffectiveAt ?? sub.canceledAt ?? null,
+      // What a cancellation declared right now would do.
+      //
+      // Here rather than behind a second route, because the page has to
+      // state the date BEFORE the customer confirms, and the rule that
+      // produces it lives on this side: the minimum term and the notice
+      // period are not visible to a browser. With a window configured,
+      // four days of delay cost a whole period — a sentence that has to
+      // be read in the confirmation, not discovered in the receipt.
+      cancellation: this.projectCancellation(sub, /* @__PURE__ */ new Date()),
       limits: toEffectiveLimitsSnapshot(limits),
       usage,
       packageSnapshot: sub.packageSnapshot ?? null,
@@ -1434,10 +2389,21 @@ var TenantBillingController = class _TenantBillingController {
     const userId = this.requireUserId(req);
     const blockedTargets = this.blockedPlans?.asTarget ?? [];
     if (blockedTargets.includes(dto.plan)) {
-      throw new ForbiddenException3({
+      throw new ForbiddenException2({
         code: BILLING_ERROR_CODES3.PLAN_NOT_SELF_SERVICE,
-        message: `${dto.plan} is not activated via self-service.`,
+        // Says what the shipped catalogue says, so an app that has not
+        // translated this code and one that has do not refuse in two
+        // different sentences.
+        message: `${dto.plan} is only activated via a special contract. Please contact the contract manager.`,
+        // `planName` is the key here, and that is the best label this
+        // check has: it decides before any catalogue is read, from
+        // nothing but the key the request sent. The plan-change
+        // preview does have a catalogue and passes the real name,
+        // which is the one a tenant recognises. Either way the
+        // template's `{planName}` resolves to a word rather than a
+        // brace — `error-params-contract.test.js` holds that.
         params: {
+          planName: dto.plan,
           planKey: dto.plan
         }
       });
@@ -1452,17 +2418,45 @@ var TenantBillingController = class _TenantBillingController {
         }
       });
     }
-    const blockers = await this.planPreview.assertChangeAllowed(tenantId, dto.plan, dto.billingCycle);
-    if (blockers.length > 0) {
+    await this.contractFreeze?.assertPartyFor(tenantId);
+    if (cancellationHasLanded(sub, /* @__PURE__ */ new Date())) {
+      throw new ConflictException({
+        code: "SUBSCRIPTION_ENDED",
+        message: "This subscription has ended. Its plan can no longer be changed.",
+        canceledEffectiveAt: sub.canceledEffectiveAt ?? sub.canceledAt ?? null
+      });
+    }
+    const cancellationOutstanding = (sub.canceledEffectiveAt ?? sub.canceledAt) !== null;
+    if (cancellationOutstanding && dto.billingCycle !== sub.billingCycle) {
+      throw new ConflictException({
+        code: "CANCELLATION_LOCKS_THE_CYCLE",
+        message: "This subscription is cancelled, so its billing cycle cannot change. The plan can.",
+        canceledEffectiveAt: sub.canceledEffectiveAt ?? sub.canceledAt ?? null,
+        billingCycle: sub.billingCycle
+      });
+    }
+    const decision = await this.planPreview.preview(tenantId, dto.plan, dto.billingCycle);
+    if (decision.blockers.length > 0) {
       throw new BadRequestException({
         code: BILLING_ERROR_CODES3.PLAN_CHANGE_BLOCKED,
         message: "Plan change is blocked.",
-        blockers
+        blockers: decision.blockers
+      });
+    }
+    if (cancellationHasLanded(sub, /* @__PURE__ */ new Date())) {
+      throw new ConflictException({
+        code: "SUBSCRIPTION_ENDED",
+        message: "This subscription ended while the request was being decided.",
+        canceledEffectiveAt: sub.canceledEffectiveAt ?? sub.canceledAt ?? null
       });
     }
-    if (dto.effectiveImmediately) {
+    const changedUnderneath = {
+      code: BILLING_ERROR_CODES3.SUBSCRIPTION_CHANGED,
+      message: "This subscription changed while the request was being decided. Reload it."
+    };
+    if (decision.isImmediate) {
       const wasTrial = sub.status === "TRIAL";
-      const period = wasTrial ? null : initialPeriodWindow(/* @__PURE__ */ new Date(), dto.billingCycle);
+      const period = wasTrial || cancellationOutstanding ? null : initialPeriodWindow(/* @__PURE__ */ new Date(), dto.billingCycle);
       const trialEndsAt = wasTrial && this.trialProjection ? await this.trialProjection.projectTrialEndsAt({
         currentPlan: sub.plan,
         targetPlan: dto.plan,
@@ -1476,10 +2470,22 @@ var TenantBillingController = class _TenantBillingController {
         periodStart: period?.start ?? null,
         periodEnd: period?.end ?? null,
         nextStatus: wasTrial ? null : "ACTIVE",
-        trialEndsAt
+        trialEndsAt,
+        expectedCanceledAt: sub.canceledAt ?? null
       });
+      if (!result.claimed) {
+        throw new ConflictException(changedUnderneath);
+      }
       this.entitlements.invalidateTenant(tenantId);
-      await this.tryFreezeOnPlanChange(tenantId, dto.plan, dto.billingCycle, wasTrial);
+      await this.tryFreezeOnPlanChange(
+        tenantId,
+        dto.plan,
+        dto.billingCycle,
+        wasTrial,
+        // A plan change on a cancelled subscription is allowed; the
+        // contract it freezes still ends when the subscription does.
+        sub.canceledEffectiveAt ?? sub.canceledAt ?? null
+      );
       await this.auditLog(req, userId, "Subscription", tenantId, "CHANGE_PLAN", {
         fromPlan: sub.plan,
         fromCycle: sub.billingCycle,
@@ -1493,12 +2499,16 @@ var TenantBillingController = class _TenantBillingController {
         immediate: true
       };
     }
-    const effectiveAt = sub.status === "TRIAL" && sub.trialEndsAt ? sub.trialEndsAt : sub.currentPeriodEnd ?? /* @__PURE__ */ new Date();
-    await this.subscriptionWrite.schedulePlanChange(tenantId, {
+    const effectiveAt = decision.effectiveAt ?? sub.currentPeriodEnd ?? /* @__PURE__ */ new Date();
+    const scheduled = await this.subscriptionWrite.schedulePlanChange(tenantId, {
       pendingPlan: dto.plan,
       pendingBillingCycle: dto.billingCycle,
-      pendingEffectiveAt: effectiveAt
+      pendingEffectiveAt: effectiveAt,
+      expectedCanceledAt: sub.canceledAt ?? null
     });
+    if (!scheduled.claimed) {
+      throw new ConflictException(changedUnderneath);
+    }
     this.entitlements.invalidateTenant(tenantId);
     await this.auditLog(req, userId, "Subscription", tenantId, "SCHEDULE_PLAN_CHANGE", {
       fromPlan: sub.plan,
@@ -1526,10 +2536,12 @@ var TenantBillingController = class _TenantBillingController {
     const warnings = [];
     const blockedTargets = this.blockedPlans?.asTarget ?? [];
     if (blockedTargets.includes(dto.plan)) {
-      throw new ForbiddenException3({
+      throw new ForbiddenException2({
         code: BILLING_ERROR_CODES3.PLAN_NOT_SELF_SERVICE,
-        message: `${dto.plan} is not activated via self-service.`,
+        message: `${dto.plan} is only activated via a special contract. Please contact the contract manager.`,
+        // The key as the label — see the note on the plan-change route.
         params: {
+          planName: dto.plan,
           planKey: dto.plan
         }
       });
@@ -1544,6 +2556,13 @@ var TenantBillingController = class _TenantBillingController {
         }
       });
     }
+    if (cancellationHasLanded(sub, /* @__PURE__ */ new Date())) {
+      throw new ConflictException({
+        code: "SUBSCRIPTION_ENDED",
+        message: "This subscription has ended and cannot be activated again.",
+        canceledEffectiveAt: sub.canceledEffectiveAt ?? sub.canceledAt ?? null
+      });
+    }
     const blockers = await this.planPreview.assertChangeAllowed(tenantId, dto.plan, dto.billingCycle);
     if (blockers.length > 0) {
       throw new BadRequestException({
@@ -1562,6 +2581,7 @@ var TenantBillingController = class _TenantBillingController {
       email: userEmail ?? void 0
     }, tx) : null;
     let planResult;
+    let claimLost;
     let promoRedemption = null;
     if (this.subscriptionWrite.applyOnboardingSelection) {
       try {
@@ -1570,8 +2590,10 @@ var TenantBillingController = class _TenantBillingController {
           cycle: dto.billingCycle,
           periodStart: period?.start ?? null,
           periodEnd: period?.end ?? null,
-          nextStatus: wasTrial ? null : "ACTIVE"
+          nextStatus: wasTrial ? null : "ACTIVE",
+          expectedCanceledAt: sub.canceledAt ?? null
         }, redeemPromoCallback);
+        claimLost = !result.claimed;
         planResult = {
           plan: result.plan,
           billingCycle: result.billingCycle
@@ -1591,14 +2613,30 @@ var TenantBillingController = class _TenantBillingController {
           }
         });
       }
+      if (claimLost) {
+        throw new ConflictException({
+          code: BILLING_ERROR_CODES3.SUBSCRIPTION_CHANGED,
+          message: "This subscription changed while onboarding was being applied. Reload it."
+        });
+      }
     } else {
       planResult = await this.subscriptionWrite.changePlanImmediate(tenantId, {
         planId: dto.plan,
         cycle: dto.billingCycle,
         periodStart: period?.start ?? null,
         periodEnd: period?.end ?? null,
-        nextStatus: wasTrial ? null : "ACTIVE"
+        nextStatus: wasTrial ? null : "ACTIVE",
+        // What this route read, so a cancellation declared since then
+        // takes the row instead of being written over. A landed one was
+        // refused above; a pending one is legitimate and claims fine.
+        expectedCanceledAt: sub.canceledAt ?? null
       });
+      if (!planResult.claimed) {
+        throw new ConflictException({
+          code: BILLING_ERROR_CODES3.SUBSCRIPTION_CHANGED,
+          message: "This subscription changed while onboarding was being applied. Reload it."
+        });
+      }
       if (dto.promoCode) {
         if (!this.promoCodes) {
           warnings.push("A promo code was sent, but PromoCodesModule is not loaded \u2014 the code was NOT redeemed.");
@@ -1637,7 +2675,20 @@ var TenantBillingController = class _TenantBillingController {
           await this.subscriptionBundles.addBundleToSubscription({
             subscriptionId: sub.id,
             bundleVersionId,
-            currentPlanKey: planResult.plan
+            currentPlanKey: planResult.plan,
+            // Onboarding refuses an ended subscription above, and a
+            // cancellation still outstanding still caps the term.
+            parentEndsAt: sub.canceledEffectiveAt ?? sub.canceledAt ?? null,
+            // The bundle runs in step with the plan it is booked
+            // beside — the plan whose window onboarding just opened.
+            planCycle: dto.billingCycle,
+            planPeriodEnd: period?.end ?? null,
+            // The window onboarding just opened decides, not any
+            // anchor stored from the subscription's previous life —
+            // the plan change reset the rhythm.
+            planAnchorDay: resolvePlanAnchorDay({
+              currentPeriodStart: period?.start ?? null
+            })
           });
           bundlesAdded += 1;
         } catch (err) {
@@ -1674,6 +2725,13 @@ var TenantBillingController = class _TenantBillingController {
         }
       });
     }
+    if (cancellationHasLanded(sub, /* @__PURE__ */ new Date())) {
+      throw new ConflictException({
+        code: "SUBSCRIPTION_ENDED",
+        message: "This subscription has ended. There is nothing left to accept.",
+        canceledEffectiveAt: sub.canceledEffectiveAt ?? sub.canceledAt ?? null
+      });
+    }
     if (!sub.pendingPlanVersion) {
       throw new BadRequestException({
         code: BILLING_ERROR_CODES3.NO_PENDING_PLAN_VERSION,
@@ -1703,28 +2761,129 @@ var TenantBillingController = class _TenantBillingController {
   async cancelSubscription(req, dto) {
     const tenantId = this.requireTenantId(req);
     const userId = this.requireUserId(req);
-    const result = await this.subscriptionWrite.cancelSubscription(tenantId, !!dto.immediately, /* @__PURE__ */ new Date());
+    const now = /* @__PURE__ */ new Date();
+    const sub = await this.subscriptionUsage.findForTenant(tenantId);
+    if (!sub) {
+      throw new NotFoundException3({
+        code: BILLING_ERROR_CODES3.NO_SUBSCRIPTION,
+        message: "This tenant has no subscription to cancel."
+      });
+    }
+    const existing = sub.canceledEffectiveAt ?? sub.canceledAt ?? null;
+    if (existing) {
+      if (this.contractFreeze) {
+        try {
+          await this.contractFreeze.endOnCancellation(tenantId, existing);
+        } catch (err) {
+          this.logger.error(`Ending the contract for an existing cancellation failed (tenant ${tenantId}): ${String(err)}`);
+        }
+      }
+      return {
+        canceledAt: sub.canceledAt ?? null,
+        canceledEffectiveAt: existing,
+        status: sub.status,
+        // Null rather than recomputed, because the three below explain a
+        // decision that was taken once and is not stored. Deriving them
+        // from the effective date tells the wrong story exactly where it
+        // matters: a declaration that landed a period late has an
+        // earlier term end and `afterNoticeDeadline: true`, and a retry
+        // would report the effective date as the term end and the late
+        // declaration as on time. Null says "not recomputed", which is
+        // the truth; the date, which is stored, is above.
+        termEndsAt: null,
+        noticeDeadline: null,
+        afterNoticeDeadline: null,
+        alreadyCanceled: true
+      };
+    }
+    const decision = this.projectCancellation(sub, now);
+    const expected = dto.expectedEffectiveAt ? new Date(dto.expectedEffectiveAt) : null;
+    const landsImmediately = decision.effectiveAt <= now;
+    const disagrees = expected !== null && (landsImmediately ? expected.getTime() > decision.effectiveAt.getTime() : expected.getTime() !== decision.effectiveAt.getTime());
+    if (disagrees) {
+      throw new ConflictException({
+        code: BILLING_ERROR_CODES3.CANCELLATION_TERMS_CHANGED,
+        message: "The effective date changed since it was shown. Confirm the new one.",
+        effectiveAt: decision.effectiveAt,
+        termEndsAt: decision.termEndsAt,
+        noticeDeadline: decision.noticeDeadline,
+        afterNoticeDeadline: decision.afterNoticeDeadline
+      });
+    }
+    const result = await this.subscriptionWrite.cancelSubscription(tenantId, {
+      canceledAt: now,
+      effectiveAt: decision.effectiveAt,
+      terminateNow: decision.effectiveAt <= now,
+      minimumTermUntil: decision.afterNoticeDeadline ? decision.effectiveAt : void 0
+    });
+    if (result.alreadyCanceled) {
+      return {
+        canceledAt: result.canceledAt,
+        canceledEffectiveAt: result.canceledEffectiveAt,
+        status: result.status,
+        termEndsAt: null,
+        noticeDeadline: null,
+        afterNoticeDeadline: null,
+        alreadyCanceled: true
+      };
+    }
     this.entitlements.invalidateTenant(tenantId);
+    if (this.contractFreeze) {
+      try {
+        await this.contractFreeze.endOnCancellation(tenantId, decision.effectiveAt);
+      } catch (err) {
+        this.logger.error(`Ending the contract after a cancellation failed (tenant ${tenantId}): ${String(err)}`);
+      }
+    }
     await this.auditLog(req, userId, "Subscription", tenantId, "CANCEL_SUBSCRIPTION", {
-      immediate: !!dto.immediately,
-      canceledAt: result.canceledAt?.toISOString() ?? null,
+      canceledAt: now.toISOString(),
+      effectiveAt: decision.effectiveAt.toISOString(),
+      afterNoticeDeadline: decision.afterNoticeDeadline,
       status: result.status
     });
     return {
       canceledAt: result.canceledAt,
+      canceledEffectiveAt: result.canceledEffectiveAt,
       status: result.status,
-      immediate: !!dto.immediately
+      // What the page needs to say which period it landed in, and why.
+      termEndsAt: decision.termEndsAt,
+      noticeDeadline: decision.noticeDeadline,
+      afterNoticeDeadline: decision.afterNoticeDeadline,
+      alreadyCanceled: false
     };
   }
   // ---------------------------------------------------------------------
   // Helpers
   // ---------------------------------------------------------------------
+  /**
+   * What a cancellation declared at `now` would do. One method, because the
+   * page states the date and this route applies it, and two constructions of
+   * the same input are two chances to disagree about a rule the customer
+   * meets once.
+   */
+  projectCancellation(sub, now) {
+    return decideCancellationFor(
+      {
+        status: sub.status,
+        billingCycle: sub.billingCycle,
+        currentPeriodEnd: sub.currentPeriodEnd ?? null,
+        minimumTermUntil: sub.minimumTermUntil ?? null,
+        trialEndsAt: sub.trialEndsAt ?? null,
+        billingAnchorDay: sub.billingAnchorDay ?? null
+      },
+      now,
+      // The rhythm of the CONTRACT, not of the plan somebody is looking
+      // at: a customer on a yearly subscription is owed the yearly
+      // notice even where the same plan is also sold monthly.
+      noticeDaysFor(this.cancellationNoticeDays, sub.billingCycle)
+    );
+  }
   requireTenantId(req) {
     const resolver = this.tenantIdResolver ?? ((r) => r.user?.tenantId ?? null);
     const tenantId = resolver(req);
     if (!tenantId) {
       throw new NotFoundException3({
-        code: AUTH_ERROR_CODES3.TENANT_CONTEXT_MISSING,
+        code: AUTH_ERROR_CODES2.TENANT_CONTEXT_MISSING,
         message: "No tenant ID found on the request"
       });
     }
@@ -1735,7 +2894,7 @@ var TenantBillingController = class _TenantBillingController {
     const userId = resolver(req);
     if (!userId) {
       throw new NotFoundException3({
-        code: AUTH_ERROR_CODES3.TENANT_CONTEXT_MISSING,
+        code: AUTH_ERROR_CODES2.TENANT_CONTEXT_MISSING,
         message: "No user ID found on the request"
       });
     }
@@ -1790,10 +2949,10 @@ var TenantBillingController = class _TenantBillingController {
    * the freeze happens on the transition to ACTIVE, i.e. on materialization).
    * Without a configured `contractFreeze` hook the call is a no-op.
    */
-  async tryFreezeOnPlanChange(tenantId, plan, cycle, wasTrial) {
+  async tryFreezeOnPlanChange(tenantId, plan, cycle, wasTrial, endsAt = null) {
     if (wasTrial || !this.contractFreeze) return;
     try {
-      await this.contractFreeze.freezeOnPlanChange(tenantId, plan, cycle, /* @__PURE__ */ new Date());
+      await this.contractFreeze.freezeOnPlanChange(tenantId, plan, cycle, /* @__PURE__ */ new Date(), endsAt);
     } catch (err) {
       this.logger.error(`Contract freeze after plan change failed (tenant ${tenantId}): ${String(err)}`);
     }
@@ -1819,7 +2978,7 @@ var TenantBillingController = class _TenantBillingController {
 };
 _ts_decorate11([
   Get2("entitlement"),
-  _ts_param7(0, Req()),
+  _ts_param6(0, Req()),
   _ts_metadata9("design:type", Function),
   _ts_metadata9("design:paramtypes", [
     typeof RequestLike === "undefined" ? Object : RequestLike
@@ -1828,7 +2987,7 @@ _ts_decorate11([
 ], TenantBillingController.prototype, "getEntitlement", null);
 _ts_decorate11([
   Get2("usage"),
-  _ts_param7(0, Req()),
+  _ts_param6(0, Req()),
   _ts_metadata9("design:type", Function),
   _ts_metadata9("design:paramtypes", [
     typeof RequestLike === "undefined" ? Object : RequestLike
@@ -1839,8 +2998,8 @@ _ts_decorate11([
   Post("plan/preview"),
   HttpCode(HttpStatus.OK),
   UseGuards(TenantAdminGuard),
-  _ts_param7(0, Req()),
-  _ts_param7(1, Body()),
+  _ts_param6(0, Req()),
+  _ts_param6(1, Body()),
   _ts_metadata9("design:type", Function),
   _ts_metadata9("design:paramtypes", [
     typeof RequestLike === "undefined" ? Object : RequestLike,
@@ -1851,8 +3010,8 @@ _ts_decorate11([
 _ts_decorate11([
   Post("plan"),
   UseGuards(TenantAdminGuard),
-  _ts_param7(0, Req()),
-  _ts_param7(1, Body()),
+  _ts_param6(0, Req()),
+  _ts_param6(1, Body()),
   _ts_metadata9("design:type", Function),
   _ts_metadata9("design:paramtypes", [
     typeof RequestLike === "undefined" ? Object : RequestLike,
@@ -1863,8 +3022,8 @@ _ts_decorate11([
 _ts_decorate11([
   Post("onboarding/initial-subscription"),
   UseGuards(TenantAdminGuard),
-  _ts_param7(0, Req()),
-  _ts_param7(1, Body()),
+  _ts_param6(0, Req()),
+  _ts_param6(1, Body()),
   _ts_metadata9("design:type", Function),
   _ts_metadata9("design:paramtypes", [
     typeof RequestLike === "undefined" ? Object : RequestLike,
@@ -1875,7 +3034,7 @@ _ts_decorate11([
 _ts_decorate11([
   Post("subscription/accept-pending-version"),
   UseGuards(TenantAdminGuard),
-  _ts_param7(0, Req()),
+  _ts_param6(0, Req()),
   _ts_metadata9("design:type", Function),
   _ts_metadata9("design:paramtypes", [
     typeof RequestLike === "undefined" ? Object : RequestLike
@@ -1885,8 +3044,8 @@ _ts_decorate11([
 _ts_decorate11([
   Post("cancel"),
   UseGuards(TenantAdminGuard),
-  _ts_param7(0, Req()),
-  _ts_param7(1, Body()),
+  _ts_param6(0, Req()),
+  _ts_param6(1, Body()),
   _ts_metadata9("design:type", Function),
   _ts_metadata9("design:paramtypes", [
     typeof RequestLike === "undefined" ? Object : RequestLike,
@@ -1897,31 +3056,33 @@ _ts_decorate11([
 TenantBillingController = _ts_decorate11([
   Controller2("billing"),
   UseGuards(ComposedTenantAuthGuard),
-  _ts_param7(0, Inject7(ENTITLEMENT_SERVICE_TOKEN)),
-  _ts_param7(1, Inject7(PlanChangePreviewService)),
-  _ts_param7(2, Inject7(SUBSCRIPTION_USAGE_PORT_TOKEN)),
-  _ts_param7(3, Inject7(USAGE_SNAPSHOT_PORT_TOKEN)),
-  _ts_param7(4, Inject7(SUBSCRIPTION_WRITE_PORT_TOKEN)),
-  _ts_param7(5, Optional6()),
-  _ts_param7(5, Inject7(TENANT_ID_RESOLVER_TOKEN)),
-  _ts_param7(6, Optional6()),
-  _ts_param7(6, Inject7(USER_ID_RESOLVER_TOKEN)),
-  _ts_param7(7, Optional6()),
-  _ts_param7(7, Inject7(SELF_SERVICE_BLOCKED_PLANS_TOKEN)),
-  _ts_param7(8, Optional6()),
-  _ts_param7(8, Inject7(PromoCodesService)),
-  _ts_param7(9, Optional6()),
-  _ts_param7(9, Inject7(AdminAuditService)),
-  _ts_param7(10, Optional6()),
-  _ts_param7(10, Inject7(USER_EMAIL_RESOLVER_TOKEN)),
-  _ts_param7(11, Optional6()),
-  _ts_param7(11, Inject7(AUDIT_CONTEXT_RESOLVER_TOKEN)),
-  _ts_param7(12, Optional6()),
-  _ts_param7(12, Inject7(SubscriptionBundlesService)),
-  _ts_param7(13, Optional6()),
-  _ts_param7(13, Inject7(CONTRACT_FREEZE_PORT_TOKEN)),
-  _ts_param7(14, Optional6()),
-  _ts_param7(14, Inject7(TRIAL_PROJECTION_PORT_TOKEN)),
+  _ts_param6(0, Inject6(ENTITLEMENT_SERVICE_TOKEN)),
+  _ts_param6(1, Inject6(PlanChangePreviewService)),
+  _ts_param6(2, Inject6(SUBSCRIPTION_USAGE_PORT_TOKEN)),
+  _ts_param6(3, Inject6(USAGE_SNAPSHOT_PORT_TOKEN)),
+  _ts_param6(4, Inject6(SUBSCRIPTION_WRITE_PORT_TOKEN)),
+  _ts_param6(5, Optional6()),
+  _ts_param6(5, Inject6(TENANT_ID_RESOLVER_TOKEN)),
+  _ts_param6(6, Optional6()),
+  _ts_param6(6, Inject6(USER_ID_RESOLVER_TOKEN)),
+  _ts_param6(7, Optional6()),
+  _ts_param6(7, Inject6(SELF_SERVICE_BLOCKED_PLANS_TOKEN)),
+  _ts_param6(8, Optional6()),
+  _ts_param6(8, Inject6(PromoCodesService)),
+  _ts_param6(9, Optional6()),
+  _ts_param6(9, Inject6(AdminAuditService)),
+  _ts_param6(10, Optional6()),
+  _ts_param6(10, Inject6(USER_EMAIL_RESOLVER_TOKEN)),
+  _ts_param6(11, Optional6()),
+  _ts_param6(11, Inject6(AUDIT_CONTEXT_RESOLVER_TOKEN)),
+  _ts_param6(12, Optional6()),
+  _ts_param6(12, Inject6(SubscriptionBundlesService)),
+  _ts_param6(13, Optional6()),
+  _ts_param6(13, Inject6(CONTRACT_FREEZE_PORT_TOKEN)),
+  _ts_param6(14, Optional6()),
+  _ts_param6(14, Inject6(TRIAL_PROJECTION_PORT_TOKEN)),
+  _ts_param6(15, Optional6()),
+  _ts_param6(15, Inject6(CANCELLATION_NOTICE_DAYS_TOKEN)),
   _ts_metadata9("design:type", Function),
   _ts_metadata9("design:paramtypes", [
     typeof EntitlementService === "undefined" ? Object : EntitlementService,
@@ -1938,12 +3099,14 @@ TenantBillingController = _ts_decorate11([
     Object,
     Object,
     Object,
-    Object
+    Object,
+    typeof CancellationNoticePeriods === "undefined" ? Object : CancellationNoticePeriods
   ])
 ], TenantBillingController);
 
 // src/billing/tenant-billing.module.ts
 import { Module as Module2 } from "@nestjs/common";
+import { planCatalogSchema as planCatalogSchema2 } from "@saasicat/spec";
 function _ts_decorate12(decorators, target, key, desc) {
   var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
   if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
@@ -1951,6 +3114,27 @@ function _ts_decorate12(decorators, target, key, desc) {
   return c > 3 && r && Object.defineProperty(target, key, r), r;
 }
 __name(_ts_decorate12, "_ts_decorate");
+function settingFromCatalog(catalog, key) {
+  const settings = catalog.tenantBilling;
+  const value = settings?.[key];
+  if (value === void 0) {
+    throw new Error(`The plan catalogue carries no tenantBilling.${key}. It is a required section of config/saas.yaml and the loader refuses a file without it, so a catalogue that reaches here without one was built in code: check the object passed to \`planCatalog\`.`);
+  }
+  return value;
+}
+__name(settingFromCatalog, "settingFromCatalog");
+var MOVED_TO_THE_FILE = Object.keys(planCatalogSchema2.properties?.tenantBilling?.properties ?? // Refuses to guess rather than falling back to an empty list: an empty
+// one would turn this guard off without saying so.
+(() => {
+  throw new Error("plan-catalog.schema.json declares no tenantBilling properties \u2014 @saasicat/spec and @saasicat/nest are out of step.");
+})());
+function assertNoMovedOptions(options) {
+  const given = options;
+  const passed = MOVED_TO_THE_FILE.filter((key) => given[key] !== void 0);
+  if (passed.length === 0) return;
+  throw new Error(`TenantBillingModule.forRoot() no longer accepts ${passed.join(" and ")} \u2014 this moved to config/saas.yaml under \`tenantBilling:\`. Move the value there (both members of each setting are required) and delete it here. The file is the one place these live, so a fallback here would be the second home that change exists to close. See docs/guides/upgrade-to-1.0.md.`);
+}
+__name(assertNoMovedOptions, "assertNoMovedOptions");
 var TenantBillingModule = class _TenantBillingModule {
   static {
     __name(this, "TenantBillingModule");
@@ -1965,11 +3149,22 @@ var TenantBillingModule = class _TenantBillingModule {
       TenantAdminGuard,
       PlanChangePreviewService
     ];
-    if (options.selfServiceBlockedPlans) {
-      providers.push({
-        provide: SELF_SERVICE_BLOCKED_PLANS_TOKEN,
-        useValue: options.selfServiceBlockedPlans
-      });
+    assertNoMovedOptions(options);
+    providers.push({
+      provide: CANCELLATION_NOTICE_DAYS_TOKEN,
+      useFactory: /* @__PURE__ */ __name((catalog) => settingFromCatalog(catalog, "cancellationNoticeDays"), "useFactory"),
+      inject: [
+        PLAN_CATALOG_SETTINGS_TOKEN
+      ]
+    }, {
+      provide: SELF_SERVICE_BLOCKED_PLANS_TOKEN,
+      useFactory: /* @__PURE__ */ __name((catalog) => settingFromCatalog(catalog, "selfServiceBlockedPlans"), "useFactory"),
+      inject: [
+        PLAN_CATALOG_SETTINGS_TOKEN
+      ]
+    });
+    if (options.subscriptionBundleRepository) {
+      providers.push(asProvider(SUBSCRIPTION_BUNDLE_REPOSITORY_TOKEN, options.subscriptionBundleRepository));
     }
     if (options.trialProjectionPort) {
       providers.push(asProvider(TRIAL_PROJECTION_PORT_TOKEN, options.trialProjectionPort));
@@ -1980,10 +3175,10 @@ var TenantBillingModule = class _TenantBillingModule {
     }
     const hasContractFreeze = Boolean(options.contractFreeze);
     if (options.contractFreeze) {
-      providers.push({
-        provide: CONTRACT_FREEZE_PROJECT_KEY_TOKEN,
-        useValue: options.contractFreeze.projectKey
-      }, asProvider(CONTRACT_FREEZE_SOURCE_PORT_TOKEN, options.contractFreeze.sourcePort), asProvider(SUBSCRIPTION_CONTRACT_REPOSITORY_TOKEN, options.contractFreeze.subscriptionContractRepository), SubscriptionContractService, {
+      if (!options.contractFreeze.subscriberRepository) {
+        throw new Error("TenantBillingModule: `contractFreeze` needs `subscriberRepository` \u2014 a frozen contract names the subscriber it is concluded with, and a plan change for a tenant without one is refused before anything changes.");
+      }
+      providers.push(asProvider(CONTRACT_FREEZE_SOURCE_PORT_TOKEN, options.contractFreeze.sourcePort), asProvider(SUBSCRIPTION_CONTRACT_REPOSITORY_TOKEN, options.contractFreeze.subscriptionContractRepository), ...subscriberProviders(options.contractFreeze.subscriberRepository), SubscriptionContractService, {
         provide: CONTRACT_FREEZE_PORT_TOKEN,
         useClass: SubscriptionContractFreezeService
       });
@@ -2044,7 +3239,7 @@ TenantBillingModule = _ts_decorate12([
 ], TenantBillingModule);
 
 // src/billing/subscription-bundle-preview.service.ts
-import { Inject as Inject8, Injectable as Injectable7, NotFoundException as NotFoundException4, Optional as Optional7 } from "@nestjs/common";
+import { Inject as Inject7, Injectable as Injectable6, NotFoundException as NotFoundException4, Optional as Optional7 } from "@nestjs/common";
 import { BILLING_ERROR_CODES as BILLING_ERROR_CODES4, CATALOG_ERROR_CODES as CATALOG_ERROR_CODES2, buildFeatureRequiresIndex as buildFeatureRequiresIndex2, collectUnsatisfiedRequires as collectUnsatisfiedRequires2 } from "@saasicat/core";
 function _ts_decorate13(decorators, target, key, desc) {
   var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
@@ -2057,12 +3252,12 @@ function _ts_metadata10(k, v) {
   if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 }
 __name(_ts_metadata10, "_ts_metadata");
-function _ts_param8(paramIndex, decorator) {
+function _ts_param7(paramIndex, decorator) {
   return function(target, key) {
     decorator(target, key, paramIndex);
   };
 }
-__name(_ts_param8, "_ts_param");
+__name(_ts_param7, "_ts_param");
 var SubscriptionBundlePreviewService = class {
   static {
     __name(this, "SubscriptionBundlePreviewService");
@@ -2079,7 +3274,7 @@ var SubscriptionBundlePreviewService = class {
     this.plans = plans;
     this.catalogEntries = catalogEntries;
     this.blockedBundles = blockedBundles;
-    this.defaultMinTermMonths = config.defaultMinimumTermMonths ?? 12;
+    this.defaultMinTermMonths = config.defaultMinimumTermMonths ?? DEFAULT_BUNDLE_MINIMUM_TERM_MONTHS;
   }
   async previewAdd(ctx, input, now = /* @__PURE__ */ new Date()) {
     const bundleVersion = await this.bundles.findVersionById(input.bundleVersionId);
@@ -2094,33 +3289,72 @@ var SubscriptionBundlePreviewService = class {
     }
     const blockers = [];
     const warnings = [];
+    const planCycle = ctx.billingCycle;
+    const billingCycle = input.billingCycle ?? planCycle;
+    if (!bundleCycleFitsPlan(billingCycle, planCycle)) {
+      blockers.push({
+        code: BILLING_ERROR_CODES4.BUNDLE_CYCLE_EXCEEDS_PLAN,
+        message: `A ${billingCycle.toLowerCase()} bundle cannot run beside a ${planCycle.toLowerCase()} plan: it would still be committed on every day the plan could end.`
+      });
+    }
     this.collectBookabilityBlockers(bundleVersion, ctx.currentPlanKey, blockers);
     const activeBundleVersions = await this.loadActiveBundleVersions(ctx.subscriptionId);
     if (activeBundleVersions.some((bv) => bv.id === bundleVersion.id)) {
       blockers.push({
         code: "BUNDLE_ALREADY_SUBSCRIBED",
-        message: "This bundle is already actively booked."
+        message: "This bundle is already actively booked.",
+        params: {
+          subscriptionId: ctx.subscriptionId
+        }
       });
     }
     const planFeatures = new Set(await this.resolvePlanFeatures(ctx.currentPlanKey, now));
     const redundantFeatures = this.collectRedundantFeatures(bundleVersion, planFeatures, ctx.currentPlanKey, activeBundleVersions);
     if (redundantFeatures.length > 0) {
       warnings.push({
-        code: "REDUNDANT_FEATURES",
-        message: `${redundantFeatures.length} feature${redundantFeatures.length === 1 ? " is" : "s are"} already included in the plan or another booked bundle \u2014 the bundle would be paid for twice.`
+        code: BILLING_ERROR_CODES4.REDUNDANT_FEATURES,
+        message: `${redundantFeatures.length} feature${redundantFeatures.length === 1 ? " is" : "s are"} already included in the plan or another booked bundle \u2014 the bundle would be paid for twice.`,
+        params: {
+          count: redundantFeatures.length
+        }
       });
     }
     const missingRequires = await this.collectMissingRequires(bundleVersion, planFeatures, activeBundleVersions);
     if (missingRequires.length > 0) {
       blockers.push({
-        code: "BUNDLE_FEATURE_DEPENDENCY_UNSATISFIED",
-        message: `The bundle requires [${missingRequires.join(", ")}] \u2014 present neither in the plan nor in the active bundles.`
+        code: BILLING_ERROR_CODES4.BUNDLE_FEATURE_DEPENDENCY_UNSATISFIED,
+        message: `The bundle requires [${missingRequires.join(", ")}] \u2014 present neither in the plan nor in the active bundles.`,
+        params: {
+          features: missingRequires.join(", ")
+        }
+      });
+    }
+    const priceNet = resolveBundlePriceNet(bundleVersion, ctx.currentPlanKey, billingCycle);
+    if (priceNet === null) {
+      blockers.push({
+        code: BILLING_ERROR_CODES4.BUNDLE_NOT_PRICED_FOR_THIS_PLAN,
+        message: `This bundle has no ${billingCycle.toLowerCase()} price for the ${ctx.currentPlanKey} plan, so it cannot be booked from here.`,
+        params: {
+          billingCycle,
+          planKey: ctx.currentPlanKey
+        }
       });
     }
-    const priceNet = resolveBundlePriceNet(bundleVersion, ctx.currentPlanKey, ctx.billingCycle);
-    const proration = ctx.status !== "TRIAL" && priceNet !== null ? computeProration({
-      periodStart: ctx.currentPeriodStart ?? ctx.startedAt ?? now,
-      periodEnd: ctx.currentPeriodEnd ?? periodEndAfter(ctx.startedAt, ctx.billingCycle, now),
+    const planAnchorDay = resolvePlanAnchorDay({
+      billingAnchorDay: ctx.planAnchorDay,
+      currentPeriodStart: ctx.currentPeriodStart,
+      startedAt: ctx.startedAt
+    });
+    const planPeriodEnd = ctx.currentPeriodEnd;
+    const firstPeriodEnd = bundleFirstPeriodEnd({
+      startedAt: now,
+      cycle: billingCycle,
+      planPeriodEnd,
+      planAnchorDay
+    });
+    const proration = ctx.status !== "TRIAL" && priceNet !== null && firstPeriodEnd !== null ? computeProration({
+      periodStart: bundleFirstPeriodStart(firstPeriodEnd, billingCycle, planAnchorDay),
+      periodEnd: firstPeriodEnd,
       now,
       currentPriceNet: 0,
       targetPriceNet: priceNet
@@ -2129,11 +3363,15 @@ var SubscriptionBundlePreviewService = class {
     return {
       action: "add",
       bundle: toSnapshot(bundleVersion),
-      billingCycle: ctx.billingCycle,
+      billingCycle,
       proration,
       nextPeriodPriceNet: priceNet,
       minimumTermMonths,
-      minimumTermEndsAt: minimumTermMonths > 0 ? addMonths(now, minimumTermMonths) : null,
+      // The same cap the mutation applies, for the same reason and by the
+      // same rule: a zero-month term stays uncommitted.
+      minimumTermEndsAt: clampToParent(minimumTermMonths > 0 ? addMonths(now, minimumTermMonths) : null, ctx.parentEndsAt),
+      firstPeriodEnd,
+      endsWithPlanAt: ctx.parentEndsAt,
       redundantFeatures,
       missingRequires,
       blockers,
@@ -2166,28 +3404,34 @@ var SubscriptionBundlePreviewService = class {
     if (existing.canceledAt !== null) {
       blockers.push({
         code: BILLING_ERROR_CODES4.SUBSCRIPTION_BUNDLE_ALREADY_CANCELLED,
-        message: "This bundle booking is already cancelled."
+        message: "This bundle booking is already cancelled.",
+        params: {
+          subscriptionBundleId: existing.id
+        }
       });
     }
+    const bookingPeriodEnd = existing.currentPeriodEnd ?? ctx.currentPeriodEnd;
     const effectiveAt = resolveBundleCancelEffectiveAt({
+      parentEndsAt: ctx.parentEndsAt,
       canceledAt: now,
-      currentPeriodEnd: ctx.currentPeriodEnd,
+      currentPeriodEnd: bookingPeriodEnd,
       minimumTermEndsAt: existing.minimumTermEndsAt
     });
-    const periodEnd = ctx.currentPeriodEnd ?? now;
+    const periodEnd = bookingPeriodEnd ?? now;
     if (existing.minimumTermEndsAt && existing.minimumTermEndsAt.getTime() > periodEnd.getTime()) {
       warnings.push({
-        code: "MINIMUM_TERM_BINDS",
+        code: BILLING_ERROR_CODES4.MINIMUM_TERM_BINDS,
         message: "The minimum term extends beyond the end of the period \u2014 the cancellation only takes effect when the minimum term ends."
       });
     }
+    const bookedCycle = existing.billingCycle ?? ctx.billingCycle;
     return {
       action: "cancel",
       subscriptionBundleId: existing.id,
       bundle: toSnapshot(bundleVersion),
-      billingCycle: ctx.billingCycle,
+      billingCycle: bookedCycle,
       effectiveAt,
-      nextPeriodSavingsNet: resolveBundlePriceNet(bundleVersion, ctx.currentPlanKey, ctx.billingCycle),
+      nextPeriodSavingsNet: resolveBundlePriceNet(bundleVersion, ctx.currentPlanKey, bookedCycle),
       blockers,
       warnings
     };
@@ -2197,26 +3441,40 @@ var SubscriptionBundlePreviewService = class {
     if (bundleVersion.publishedAt === null) {
       blockers.push({
         code: "BUNDLE_VERSION_NOT_PUBLISHED",
-        message: "This bundle version is not published and cannot be booked."
+        message: "This bundle version is not published and cannot be booked.",
+        params: {
+          bundleVersionId: bundleVersion.id
+        }
       });
     }
     if (bundleVersion.supersededAt !== null) {
       blockers.push({
         code: "BUNDLE_VERSION_SUPERSEDED",
-        message: "This bundle version has been superseded by a newer one."
+        message: "This bundle version has been superseded by a newer one.",
+        params: {
+          bundleVersionId: bundleVersion.id
+        }
       });
     }
     const planIds = bundleVersion.compatibility?.planIds ?? [];
     if (planIds.length > 0 && !planIds.includes(currentPlanKey)) {
       blockers.push({
         code: "BUNDLE_INCOMPATIBLE_WITH_PLAN",
-        message: `The bundle is not compatible with plan '${currentPlanKey}'. Allowed: [${planIds.join(", ")}].`
+        message: `The bundle is not compatible with plan '${currentPlanKey}'. Allowed: [${planIds.join(", ")}].`,
+        params: {
+          bundleVersionId: bundleVersion.id,
+          planKey: currentPlanKey,
+          allowedPlanKeys: planIds.join(", ")
+        }
       });
     }
     if (this.blockedBundles?.bundleKeys?.includes(bundleVersion.bundleKey)) {
       blockers.push({
         code: "BUNDLE_NOT_SELF_SERVICE",
-        message: `Bundle '${bundleVersion.bundleKey}' is only activated via a special contract. Please contact the contract manager.`
+        message: `Bundle '${bundleVersion.bundleKey}' is only activated via a special contract. Please contact the contract manager.`,
+        params: {
+          bundleKey: bundleVersion.bundleKey
+        }
       });
     }
   }
@@ -2260,11 +3518,7 @@ var SubscriptionBundlePreviewService = class {
    */
   async collectMissingRequires(bundleVersion, planFeatures, activeBundleVersions) {
     if (!this.catalogEntries) return [];
-    const projectKey = await this.resolveProjectKey(bundleVersion);
-    if (!projectKey) return [];
-    const entries = await this.catalogEntries.listFeatures({
-      projectKey
-    });
+    const entries = await this.catalogEntries.listFeatures({});
     const requiresIndex = buildFeatureRequiresIndex2(entries);
     const covered = /* @__PURE__ */ new Set([
       ...planFeatures,
@@ -2272,24 +3526,19 @@ var SubscriptionBundlePreviewService = class {
     ]);
     return collectUnsatisfiedRequires2(bundleVersion.features ?? [], requiresIndex).filter((key) => !covered.has(key));
   }
-  /** `projectKey` lives on the bundle stem, not on the version. */
-  async resolveProjectKey(bundleVersion) {
-    const stem = await this.bundles.findById(bundleVersion.bundleId);
-    return stem?.projectKey ?? null;
-  }
 };
 SubscriptionBundlePreviewService = _ts_decorate13([
-  Injectable7(),
-  _ts_param8(0, Inject8(SUBSCRIPTION_BUNDLE_REPOSITORY_TOKEN)),
-  _ts_param8(1, Inject8(BUNDLE_REPOSITORY_TOKEN)),
-  _ts_param8(2, Optional7()),
-  _ts_param8(2, Inject8(PLAN_REPOSITORY_TOKEN)),
-  _ts_param8(3, Optional7()),
-  _ts_param8(3, Inject8(CATALOG_ENTRY_REPOSITORY_TOKEN)),
-  _ts_param8(4, Optional7()),
-  _ts_param8(4, Inject8(SELF_SERVICE_BLOCKED_BUNDLES_TOKEN)),
-  _ts_param8(5, Optional7()),
-  _ts_param8(5, Inject8(SUBSCRIPTION_BUNDLE_CONFIG_TOKEN)),
+  Injectable6(),
+  _ts_param7(0, Inject7(SUBSCRIPTION_BUNDLE_REPOSITORY_TOKEN)),
+  _ts_param7(1, Inject7(BUNDLE_REPOSITORY_TOKEN)),
+  _ts_param7(2, Optional7()),
+  _ts_param7(2, Inject7(PLAN_REPOSITORY_TOKEN)),
+  _ts_param7(3, Optional7()),
+  _ts_param7(3, Inject7(CATALOG_ENTRY_REPOSITORY_TOKEN)),
+  _ts_param7(4, Optional7()),
+  _ts_param7(4, Inject7(SELF_SERVICE_BLOCKED_BUNDLES_TOKEN)),
+  _ts_param7(5, Optional7()),
+  _ts_param7(5, Inject7(SUBSCRIPTION_BUNDLE_CONFIG_TOKEN)),
   _ts_metadata10("design:type", Function),
   _ts_metadata10("design:paramtypes", [
     typeof SubscriptionBundleRepository === "undefined" ? Object : SubscriptionBundleRepository,
@@ -2300,15 +3549,6 @@ SubscriptionBundlePreviewService = _ts_decorate13([
     typeof SubscriptionBundleConfig === "undefined" ? Object : SubscriptionBundleConfig
   ])
 ], SubscriptionBundlePreviewService);
-function resolveBundlePriceNet(bundleVersion, planKey, billingCycle) {
-  const override = (bundleVersion.pricingOverrides ?? []).find((o) => o.planId === planKey);
-  const yearly = billingCycle === "YEARLY";
-  const raw = yearly ? override?.yearlyNet !== void 0 ? override.yearlyNet : bundleVersion.yearlyNet : override?.monthlyNet !== void 0 ? override.monthlyNet : bundleVersion.monthlyNet;
-  if (raw === null || raw === void 0) return null;
-  const parsed = Number.parseFloat(raw);
-  return Number.isFinite(parsed) ? parsed : null;
-}
-__name(resolveBundlePriceNet, "resolveBundlePriceNet");
 function toSnapshot(bundleVersion) {
   return {
     bundleKey: bundleVersion.bundleKey,
@@ -2325,11 +3565,8 @@ function toSnapshot(bundleVersion) {
 __name(toSnapshot, "toSnapshot");
 
 // src/billing/tenant-subscription-bundles.controller.ts
-import { BadRequestException as BadRequestException2, Body as Body2, Controller as Controller3, Delete, Get as Get3, HttpCode as HttpCode2, HttpStatus as HttpStatus2, Inject as Inject9, Logger as Logger3, NotFoundException as NotFoundException5, Optional as Optional8, Param, ParseUUIDPipe, Post as Post2, Req as Req2, UseGuards as UseGuards2 } from "@nestjs/common";
-import { AUTH_ERROR_CODES as AUTH_ERROR_CODES4, BILLING_ERROR_CODES as BILLING_ERROR_CODES5 } from "@saasicat/core";
-
-// src/billing/dto/subscription-bundles.dto.ts
-import { IsInt, IsOptional as IsOptional3, IsUUID as IsUUID2, Matches as Matches3, Max, Min } from "class-validator";
+import { BadRequestException as BadRequestException2, Body as Body2, Controller as Controller3, Delete, Get as Get3, HttpCode as HttpCode2, HttpStatus as HttpStatus2, Inject as Inject8, Logger as Logger3, ConflictException as ConflictException2, NotFoundException as NotFoundException5, Optional as Optional8, Param, ParseUUIDPipe, Post as Post2, Req as Req2, UseGuards as UseGuards2 } from "@nestjs/common";
+import { AUTH_ERROR_CODES as AUTH_ERROR_CODES3, BILLING_ERROR_CODES as BILLING_ERROR_CODES5 } from "@saasicat/core";
 function _ts_decorate14(decorators, target, key, desc) {
   var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
   if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
@@ -2341,95 +3578,12 @@ function _ts_metadata11(k, v) {
   if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 }
 __name(_ts_metadata11, "_ts_metadata");
-var ISO_DATE_PATTERN = /^\d{4}-\d{2}-\d{2}(T.*)?$/;
-var AddSubscriptionBundleDto = class {
-  static {
-    __name(this, "AddSubscriptionBundleDto");
-  }
-  bundleVersionId;
-  /**
-   * Optional — override for the minimum term (months). `0` = no
-   * minimum term. Default comes from the `SubscriptionBundleConfig`
-   * (platform = 12 months).
-   */
-  minimumTermMonths;
-};
-_ts_decorate14([
-  IsUUID2(),
-  _ts_metadata11("design:type", String)
-], AddSubscriptionBundleDto.prototype, "bundleVersionId", void 0);
-_ts_decorate14([
-  IsOptional3(),
-  IsInt(),
-  Min(0),
-  Max(120),
-  _ts_metadata11("design:type", Number)
-], AddSubscriptionBundleDto.prototype, "minimumTermMonths", void 0);
-var PreviewSubscriptionBundleDto = class {
-  static {
-    __name(this, "PreviewSubscriptionBundleDto");
-  }
-  /** Add preview: BundleVersion to be booked. */
-  bundleVersionId;
-  /** Cancel preview: existing Bundle booking. */
-  subscriptionBundleId;
-  /** Add preview only — override analogous to `AddSubscriptionBundleDto`. */
-  minimumTermMonths;
-};
-_ts_decorate14([
-  IsOptional3(),
-  IsUUID2(),
-  _ts_metadata11("design:type", String)
-], PreviewSubscriptionBundleDto.prototype, "bundleVersionId", void 0);
-_ts_decorate14([
-  IsOptional3(),
-  IsUUID2(),
-  _ts_metadata11("design:type", String)
-], PreviewSubscriptionBundleDto.prototype, "subscriptionBundleId", void 0);
-_ts_decorate14([
-  IsOptional3(),
-  IsInt(),
-  Min(0),
-  Max(120),
-  _ts_metadata11("design:type", Number)
-], PreviewSubscriptionBundleDto.prototype, "minimumTermMonths", void 0);
-var CancelSubscriptionBundleDto = class {
-  static {
-    __name(this, "CancelSubscriptionBundleDto");
-  }
-  /**
-   * Optional — default = `new Date()` server-side. Format: ISO-8601
-   * (`YYYY-MM-DD` or full timestamp). Usually not set by the tenant
-   * self-service.
-   */
-  canceledAt;
-};
-_ts_decorate14([
-  IsOptional3(),
-  Matches3(ISO_DATE_PATTERN, {
-    message: "canceledAt must be an ISO date (YYYY-MM-DD)"
-  }),
-  _ts_metadata11("design:type", String)
-], CancelSubscriptionBundleDto.prototype, "canceledAt", void 0);
-
-// src/billing/tenant-subscription-bundles.controller.ts
-function _ts_decorate15(decorators, target, key, desc) {
-  var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
-  if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
-  else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
-  return c > 3 && r && Object.defineProperty(target, key, r), r;
-}
-__name(_ts_decorate15, "_ts_decorate");
-function _ts_metadata12(k, v) {
-  if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
-}
-__name(_ts_metadata12, "_ts_metadata");
-function _ts_param9(paramIndex, decorator) {
+function _ts_param8(paramIndex, decorator) {
   return function(target, key) {
     decorator(target, key, paramIndex);
   };
 }
-__name(_ts_param9, "_ts_param");
+__name(_ts_param8, "_ts_param");
 function buildTenantSubscriptionBundlesController(extraGuards = []) {
   let GeneratedTenantSubscriptionBundlesController = class GeneratedTenantSubscriptionBundlesController2 {
     static {
@@ -2452,17 +3606,44 @@ function buildTenantSubscriptionBundlesController(extraGuards = []) {
     }
     async list(req) {
       const sub = await this.requireSubscription(this.requireTenantId(req));
-      return this.service.listForSubscription(this.requireSubscriptionPk(sub));
+      return this.service.listForSubscription(this.requireSubscriptionPk(sub), sub.plan, sub.billingCycle);
+    }
+    /**
+     * List prices for the bundles the store is showing, resolved for this
+     * tenant's plan.
+     *
+     * A read with a body, like `preview` beside it: the caller names the
+     * bundle versions it is displaying. The public catalogue serves base
+     * prices and has no plan to resolve an override against, so a tenant UI
+     * pricing from it quotes a figure that may not be the one charged — and
+     * reads a bundle priced only through an override as having no price at
+     * all.
+     */
+    async prices(req, dto) {
+      const sub = await this.requireSubscription(this.requireTenantId(req));
+      return this.service.resolvePricesFor(sub.plan, dto.bundleVersionIds);
     }
     async add(req, dto) {
       const tenantId = this.requireTenantId(req);
-      const sub = await this.requireSubscription(tenantId);
+      const sub = await this.requireRunningSubscription(tenantId);
+      await this.contractFreeze?.assertPartyFor(tenantId);
       const result = await this.service.addBundleToSubscription({
         subscriptionId: this.requireSubscriptionPk(sub),
         bundleVersionId: dto.bundleVersionId,
         // Plan KEY (compatibility.planIds is key-based) — not the planVersion UUID.
         currentPlanKey: sub.plan,
-        minimumTermMonths: dto.minimumTermMonths
+        minimumTermMonths: dto.minimumTermMonths,
+        // A bundle cannot commit past the subscription paying for it.
+        parentEndsAt: sub.canceledEffectiveAt ?? sub.canceledAt ?? null,
+        // And it runs in the plan's rhythm, on the plan's day.
+        planCycle: sub.billingCycle,
+        planPeriodEnd: sub.currentPeriodEnd ?? null,
+        // Resolved rather than passed through: a null here would let
+        // the arithmetic read the period END, which a short month has
+        // already clamped — and the preview, which resolves, would then
+        // quote a different day from the one booked.
+        planAnchorDay: resolvePlanAnchorDay(sub),
+        billingCycle: dto.billingCycle
       });
       await this.refreezeContract(tenantId, sub);
       return result;
@@ -2476,7 +3657,7 @@ function buildTenantSubscriptionBundlesController(extraGuards = []) {
           message: "Exactly one of bundleVersionId (add preview) or subscriptionBundleId (cancel preview) must be given."
         });
       }
-      const sub = await this.requireSubscription(this.requireTenantId(req));
+      const sub = hasAdd ? await this.requireRunningSubscription(this.requireTenantId(req)) : await this.requireSubscription(this.requireTenantId(req));
       const ctx = {
         subscriptionId: this.requireSubscriptionPk(sub),
         // Plan KEY (compatibility.planIds is key-based) — not the planVersion UUID.
@@ -2485,11 +3666,17 @@ function buildTenantSubscriptionBundlesController(extraGuards = []) {
         status: sub.status,
         startedAt: sub.startedAt,
         currentPeriodStart: sub.currentPeriodStart,
-        currentPeriodEnd: sub.currentPeriodEnd
+        currentPeriodEnd: sub.currentPeriodEnd,
+        // The dialog states the term it will be committed to, and the
+        // booking caps that at the parent's end. Both, or the two
+        // describe different contracts.
+        parentEndsAt: sub.canceledEffectiveAt ?? sub.canceledAt ?? null,
+        planAnchorDay: resolvePlanAnchorDay(sub)
       };
       return hasAdd ? this.previewService.previewAdd(ctx, {
         bundleVersionId: dto.bundleVersionId,
-        minimumTermMonths: dto.minimumTermMonths
+        minimumTermMonths: dto.minimumTermMonths,
+        billingCycle: dto.billingCycle
       }) : this.previewService.previewCancel(ctx, {
         subscriptionBundleId: dto.subscriptionBundleId
       });
@@ -2500,6 +3687,9 @@ function buildTenantSubscriptionBundlesController(extraGuards = []) {
       const result = await this.service.cancelBundleFromSubscription({
         subscriptionBundleId,
         canceledAt: dto.canceledAt ? new Date(dto.canceledAt) : void 0,
+        // A bundle cannot be held past the plan that pays for it, and
+        // the plan may have been cancelled since this was booked.
+        parentEndsAt: sub.canceledEffectiveAt ?? sub.canceledAt ?? null,
         currentPeriodEnd: sub.currentPeriodEnd ?? void 0
       });
       await this.refreezeContract(tenantId, sub);
@@ -2507,7 +3697,8 @@ function buildTenantSubscriptionBundlesController(extraGuards = []) {
     }
     async reactivate(req, subscriptionBundleId) {
       const tenantId = this.requireTenantId(req);
-      const sub = await this.requireSubscription(tenantId);
+      const sub = await this.requireRunningSubscription(tenantId);
+      await this.contractFreeze?.assertPartyFor(tenantId);
       const result = await this.service.reactivateBundle(subscriptionBundleId);
       await this.refreezeContract(tenantId, sub);
       return result;
@@ -2522,7 +3713,7 @@ function buildTenantSubscriptionBundlesController(extraGuards = []) {
       const tenantId = this.tenantIdResolver(req);
       if (!tenantId) {
         throw new NotFoundException5({
-          code: AUTH_ERROR_CODES4.TENANT_CONTEXT_MISSING,
+          code: AUTH_ERROR_CODES3.TENANT_CONTEXT_MISSING,
           message: "No tenant ID found on the request"
         });
       }
@@ -2541,6 +3732,29 @@ function buildTenantSubscriptionBundlesController(extraGuards = []) {
       }
       return sub;
     }
+    /**
+     * The same subscription, refused once its cancellation has landed.
+     *
+     * A bundle is bought, priced and given a minimum term, and it grants
+     * its features through the parent subscription — which grants nothing
+     * once it has ended. Sold there, it is a commitment that can never
+     * deliver: charged, listed, and inert.
+     *
+     * Reading and cancelling stay open on purpose. A tenant whose
+     * subscription ended must still be able to see what they booked and
+     * tidy it up; what closes is the till.
+     */
+    async requireRunningSubscription(tenantId) {
+      const sub = await this.requireSubscription(tenantId);
+      if (cancellationHasLanded(sub, /* @__PURE__ */ new Date())) {
+        throw new ConflictException2({
+          code: "SUBSCRIPTION_ENDED",
+          message: "This subscription has ended. Bundles can no longer be booked for it.",
+          canceledEffectiveAt: sub.canceledEffectiveAt ?? sub.canceledAt ?? null
+        });
+      }
+      return sub;
+    }
     /**
      * Re-freeze with the unchanged plan after bundle add/cancel (#61) —
      * only if the consumer has wired the ContractFreezePort.
@@ -2553,82 +3767,106 @@ function buildTenantSubscriptionBundlesController(extraGuards = []) {
         }
         return;
       }
+      if (cancellationHasLanded(sub, /* @__PURE__ */ new Date())) return;
       try {
-        await this.contractFreeze.freezeOnPlanChange(tenantId, sub.planVersion.planId, sub.billingCycle, /* @__PURE__ */ new Date());
+        await this.contractFreeze.freezeOnPlanChange(
+          tenantId,
+          sub.planVersion.planId,
+          sub.billingCycle,
+          /* @__PURE__ */ new Date(),
+          // Cancelling a bundle stays open on a cancelled
+          // subscription, and it re-freezes: the replacement contract
+          // ends when the subscription does, like the one it succeeds.
+          sub.canceledEffectiveAt ?? sub.canceledAt ?? null
+        );
       } catch (err) {
         this.logger.error(`Contract freeze after bundle mutation failed (tenant ${tenantId}): ${String(err)}`);
       }
     }
   };
-  _ts_decorate15([
+  _ts_decorate14([
     Get3(),
-    _ts_param9(0, Req2()),
-    _ts_metadata12("design:type", Function),
-    _ts_metadata12("design:paramtypes", [
+    _ts_param8(0, Req2()),
+    _ts_metadata11("design:type", Function),
+    _ts_metadata11("design:paramtypes", [
       typeof RequestLike === "undefined" ? Object : RequestLike
     ]),
-    _ts_metadata12("design:returntype", Promise)
+    _ts_metadata11("design:returntype", Promise)
   ], GeneratedTenantSubscriptionBundlesController.prototype, "list", null);
-  _ts_decorate15([
+  _ts_decorate14([
+    Post2("prices"),
+    _ts_param8(0, Req2()),
+    _ts_param8(1, Body2()),
+    _ts_metadata11("design:type", Function),
+    _ts_metadata11("design:paramtypes", [
+      typeof RequestLike === "undefined" ? Object : RequestLike,
+      typeof BundlePriceLookupDto === "undefined" ? Object : BundlePriceLookupDto
+    ]),
+    _ts_metadata11("design:returntype", Promise)
+  ], GeneratedTenantSubscriptionBundlesController.prototype, "prices", null);
+  _ts_decorate14([
     Post2(),
-    _ts_param9(0, Req2()),
-    _ts_param9(1, Body2()),
-    _ts_metadata12("design:type", Function),
-    _ts_metadata12("design:paramtypes", [
+    UseGuards2(TenantAdminGuard),
+    _ts_param8(0, Req2()),
+    _ts_param8(1, Body2()),
+    _ts_metadata11("design:type", Function),
+    _ts_metadata11("design:paramtypes", [
       typeof RequestLike === "undefined" ? Object : RequestLike,
       typeof AddSubscriptionBundleDto === "undefined" ? Object : AddSubscriptionBundleDto
     ]),
-    _ts_metadata12("design:returntype", Promise)
+    _ts_metadata11("design:returntype", Promise)
   ], GeneratedTenantSubscriptionBundlesController.prototype, "add", null);
-  _ts_decorate15([
+  _ts_decorate14([
     Post2("preview"),
     HttpCode2(HttpStatus2.OK),
-    _ts_param9(0, Req2()),
-    _ts_param9(1, Body2()),
-    _ts_metadata12("design:type", Function),
-    _ts_metadata12("design:paramtypes", [
+    _ts_param8(0, Req2()),
+    _ts_param8(1, Body2()),
+    _ts_metadata11("design:type", Function),
+    _ts_metadata11("design:paramtypes", [
       typeof RequestLike === "undefined" ? Object : RequestLike,
       typeof PreviewSubscriptionBundleDto === "undefined" ? Object : PreviewSubscriptionBundleDto
     ]),
-    _ts_metadata12("design:returntype", Promise)
+    _ts_metadata11("design:returntype", Promise)
   ], GeneratedTenantSubscriptionBundlesController.prototype, "preview", null);
-  _ts_decorate15([
+  _ts_decorate14([
     Delete(":id"),
+    UseGuards2(TenantAdminGuard),
     HttpCode2(HttpStatus2.OK),
-    _ts_param9(0, Req2()),
-    _ts_param9(1, Param("id", new ParseUUIDPipe())),
-    _ts_param9(2, Body2()),
-    _ts_metadata12("design:type", Function),
-    _ts_metadata12("design:paramtypes", [
+    _ts_param8(0, Req2()),
+    _ts_param8(1, Param("id", new ParseUUIDPipe())),
+    _ts_param8(2, Body2()),
+    _ts_metadata11("design:type", Function),
+    _ts_metadata11("design:paramtypes", [
       typeof RequestLike === "undefined" ? Object : RequestLike,
       String,
       typeof CancelSubscriptionBundleDto === "undefined" ? Object : CancelSubscriptionBundleDto
     ]),
-    _ts_metadata12("design:returntype", Promise)
+    _ts_metadata11("design:returntype", Promise)
   ], GeneratedTenantSubscriptionBundlesController.prototype, "cancel", null);
-  _ts_decorate15([
+  _ts_decorate14([
     Post2(":id/reactivate"),
+    UseGuards2(TenantAdminGuard),
     HttpCode2(HttpStatus2.OK),
-    _ts_param9(0, Req2()),
-    _ts_param9(1, Param("id", new ParseUUIDPipe())),
-    _ts_metadata12("design:type", Function),
-    _ts_metadata12("design:paramtypes", [
+    _ts_param8(0, Req2()),
+    _ts_param8(1, Param("id", new ParseUUIDPipe())),
+    _ts_metadata11("design:type", Function),
+    _ts_metadata11("design:paramtypes", [
       typeof RequestLike === "undefined" ? Object : RequestLike,
       String
     ]),
-    _ts_metadata12("design:returntype", Promise)
+    _ts_metadata11("design:returntype", Promise)
   ], GeneratedTenantSubscriptionBundlesController.prototype, "reactivate", null);
-  GeneratedTenantSubscriptionBundlesController = _ts_decorate15([
+  GeneratedTenantSubscriptionBundlesController = _ts_decorate14([
     Controller3("billing/subscription-bundles"),
     UseGuards2(ComposedTenantAuthGuard, ...extraGuards),
-    _ts_param9(0, Inject9(SubscriptionBundlesService)),
-    _ts_param9(1, Inject9(SubscriptionBundlePreviewService)),
-    _ts_param9(2, Inject9(SUBSCRIPTION_USAGE_PORT_TOKEN)),
-    _ts_param9(3, Inject9(TENANT_ID_RESOLVER_TOKEN)),
-    _ts_param9(4, Optional8()),
-    _ts_param9(4, Inject9(CONTRACT_FREEZE_PORT_TOKEN)),
-    _ts_metadata12("design:type", Function),
-    _ts_metadata12("design:paramtypes", [
+    _ts_param8(0, Inject8(SubscriptionBundlesService)),
+    _ts_param8(1, Inject8(SubscriptionBundlePreviewService)),
+    _ts_param8(2, Inject8(SUBSCRIPTION_USAGE_PORT_TOKEN)),
+    _ts_param8(3, Inject8(TENANT_ID_RESOLVER_TOKEN)),
+    _ts_param8(4, Optional8()),
+    _ts_param8(4, Inject8(CONTRACT_FREEZE_PORT_TOKEN)),
+    _ts_metadata11("design:type", Function),
+    _ts_metadata11("design:paramtypes", [
       typeof SubscriptionBundlesService === "undefined" ? Object : SubscriptionBundlesService,
       typeof SubscriptionBundlePreviewService === "undefined" ? Object : SubscriptionBundlePreviewService,
       typeof SubscriptionUsagePort === "undefined" ? Object : SubscriptionUsagePort,
@@ -2642,13 +3880,13 @@ __name(buildTenantSubscriptionBundlesController, "buildTenantSubscriptionBundles
 
 // src/billing/subscription-bundles.module.ts
 import { Module as Module3 } from "@nestjs/common";
-function _ts_decorate16(decorators, target, key, desc) {
+function _ts_decorate15(decorators, target, key, desc) {
   var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
   if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
   else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
   return c > 3 && r && Object.defineProperty(target, key, r), r;
 }
-__name(_ts_decorate16, "_ts_decorate");
+__name(_ts_decorate15, "_ts_decorate");
 var SubscriptionBundleModule = class _SubscriptionBundleModule {
   static {
     __name(this, "SubscriptionBundleModule");
@@ -2661,8 +3899,14 @@ var SubscriptionBundleModule = class _SubscriptionBundleModule {
       ] : [],
       {
         provide: SUBSCRIPTION_BUNDLE_CONFIG_TOKEN,
+        // Handed over, not decided. The default belongs to the
+        // services, because a consumer can construct those directly and
+        // both paths have to answer the same — and a module filling the
+        // value in makes their default unreachable, which is what kept
+        // every add-on committed for twelve months after the default
+        // had already been changed to none.
         useValue: {
-          defaultMinimumTermMonths: options.defaultMinimumTermMonths ?? 12
+          defaultMinimumTermMonths: options.defaultMinimumTermMonths
         }
       },
       ...options.selfServiceBlockedBundles ? [
@@ -2704,26 +3948,43 @@ var SubscriptionBundleModule = class _SubscriptionBundleModule {
     };
   }
 };
-SubscriptionBundleModule = _ts_decorate16([
+SubscriptionBundleModule = _ts_decorate15([
   Module3({})
 ], SubscriptionBundleModule);
 
 export {
+  advanceOneCycle,
+  retreatOneCycle,
+  billingAnchorDay,
   periodEndAfter,
   initialPeriodWindow,
   periodEndWithMinLead,
+  resolvePlanAnchorDay,
+  bundleFirstPeriodEnd,
+  bundleFirstPeriodStart,
+  bundleNextPeriodEnd,
+  DEFAULT_BUNDLE_MINIMUM_TERM_MONTHS,
+  bundleCycleFitsPlan,
+  computeNextBundlePeriod,
+  decideCancellation,
+  NO_NOTICE_PERIOD,
+  noticeDaysFor,
+  decideCancellationFor,
   FEATURE_GUARD_MARKER,
   isPlatformFeatureGuard,
   REQUIRE_FEATURE_KEY,
   RequireFeature,
-  PUBLIC_CATALOG_PROJECT_KEY_TOKEN,
   PUBLIC_CATALOG_BUNDLE_REPOSITORY_TOKEN,
   PUBLIC_CATALOG_MARKETING_REPOSITORY_TOKEN,
   PUBLIC_CATALOG_CATALOG_ENTRY_REPOSITORY_TOKEN,
+  PLAN_CATALOG_UNREADABLE_ERROR,
+  PlanCatalogValidationError,
+  loadPlanCatalogFromFile,
+  catalogSource,
+  loadPlanCatalogFromString,
   BILLING_FEATURE_UI_REGISTRY_TOKEN,
   PublicCatalogController,
   PublicCatalogModule,
-  ComposedTenantAuthGuard,
   TenantAdminGuard,
   SELF_SERVICE_BLOCKED_PLANS_TOKEN,
   SELF_SERVICE_BLOCKED_BUNDLES_TOKEN,
@@ -2731,20 +3992,23 @@ export {
   PlanChangePreviewService,
   CONTRACT_FREEZE_PORT_TOKEN,
   CONTRACT_FREEZE_SOURCE_PORT_TOKEN,
-  CONTRACT_FREEZE_PROJECT_KEY_TOKEN,
   PendingPlanMaterializationService,
   SubscriptionContractFreezeService,
   PreviewPlanChangeDto,
   ChangePlanDto,
   CancelSubscriptionDto,
   CompleteOnboardingSubscriptionDto,
+  AddSubscriptionBundleDto,
+  PreviewSubscriptionBundleDto,
+  CancelSubscriptionBundleDto,
+  BundlePriceLookupDto,
   SubscriptionBundlesService,
   resolveBundleCancelEffectiveAt,
   addMonths,
+  clampToParent,
   TenantBillingController,
   TenantBillingModule,
   SubscriptionBundlePreviewService,
-  resolveBundlePriceNet,
   buildTenantSubscriptionBundlesController,
   SubscriptionBundleModule
 };