@farthershore/product 0.0.0

package/dist/bin.js

@@ -0,0 +1,2766 @@
+#!/usr/bin/env node
+import { createRequire as __createRequire } from "node:module";const require=__createRequire(import.meta.url);
+
+// src/bin.ts
+import { writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { tsImport } from "tsx/esm/api";
+
+// src/errors.ts
+var ManifestValidationError = class extends Error {
+  issues;
+  constructor(issues) {
+    const summary = issues.slice(0, 5).map((issue) => `  - ${issue.path || "(root)"}: ${issue.message}`).join("\n");
+    const more = issues.length > 5 ? `
+  \u2026and ${issues.length - 5} more` : "";
+    super(`Manifest validation failed:
+${summary}${more}`);
+    this.name = "ManifestValidationError";
+    this.issues = issues;
+  }
+};
+var ManifestBuilderError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ManifestBuilderError";
+  }
+};
+
+// ../contracts/dist/plans/limits-schema.js
+import { z } from "zod";
+var limitDimensionSchema = z.string().min(1);
+var namedWindowSchema = z.object({
+  type: z.literal("named"),
+  name: z.enum(["second", "minute", "hour", "day", "week", "month"])
+});
+var customWindowSchema = z.object({
+  type: z.literal("custom"),
+  seconds: z.number().int().positive(),
+  label: z.string().optional()
+});
+var limitWindowSpecSchema = z.discriminatedUnion("type", [
+  namedWindowSchema,
+  customWindowSchema
+]);
+var planLimitRuleSchema = z.object({
+  dimension: limitDimensionSchema,
+  window: limitWindowSpecSchema,
+  capacity: z.number().nonnegative(),
+  enforcement: z.enum(["enforce", "track"]).optional(),
+  /**
+   * Opt-out for the `LIMIT_METER_UNREACHABLE` cross-validation
+   * (Option B / v0.41.0). When `true`, the limit is allowed to
+   * reference a meter no granted route emits — useful for soft
+   * budgets on derived dimensions (e.g. `dollars` computed from
+   * sibling meters by the billing engine), or for out-of-band
+   * tracking the runtime path doesn't enforce.
+   */
+  acknowledgeUnreachable: z.boolean().optional()
+});
+var planLimitsSchema = z.array(planLimitRuleSchema).max(20);
+
+// ../contracts/dist/plans/spec/subscriber-change-policy.js
+import { z as z2 } from "zod";
+var subscriberChangeActionSchema = z2.enum([
+  "preserve_current_period",
+  "switch_immediately",
+  "switch_immediately_prorate",
+  "new_subscribers_only"
+]);
+var subscriberChangePolicySchema = z2.object({
+  default: subscriberChangeActionSchema.default("preserve_current_period"),
+  proration: z2.enum(["none", "prorate", "credit"]).default("none"),
+  when: z2.object({
+    price_increase: subscriberChangeActionSchema.optional(),
+    price_decrease: subscriberChangeActionSchema.optional(),
+    feature_added: subscriberChangeActionSchema.optional(),
+    feature_removed: subscriberChangeActionSchema.optional(),
+    limit_increased: subscriberChangeActionSchema.optional(),
+    limit_reduced: subscriberChangeActionSchema.optional(),
+    credit_increased: subscriberChangeActionSchema.optional(),
+    credit_reduced: subscriberChangeActionSchema.optional(),
+    rating_changed: subscriberChangeActionSchema.optional()
+  }).strict().default({
+    price_increase: "preserve_current_period",
+    price_decrease: "switch_immediately",
+    feature_added: "switch_immediately",
+    feature_removed: "preserve_current_period",
+    limit_increased: "switch_immediately",
+    limit_reduced: "preserve_current_period",
+    credit_increased: "switch_immediately",
+    credit_reduced: "preserve_current_period",
+    rating_changed: "preserve_current_period"
+  }),
+  allowImmediatePriceIncrease: z2.boolean().default(false),
+  allowImmediateEntitlementReduction: z2.boolean().default(false)
+}).strict().superRefine((policy, ctx) => {
+  const immediate = /* @__PURE__ */ new Set([
+    "switch_immediately",
+    "switch_immediately_prorate"
+  ]);
+  if (immediate.has(policy.when.price_increase ?? policy.default) && !policy.allowImmediatePriceIncrease) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["when", "price_increase"],
+      message: "price_increase cannot switch immediately without allowImmediatePriceIncrease: true"
+    });
+  }
+  for (const key of [
+    "feature_removed",
+    "limit_reduced",
+    "credit_reduced"
+  ]) {
+    if (immediate.has(policy.when[key] ?? policy.default) && !policy.allowImmediateEntitlementReduction) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["when", key],
+        message: `${key} cannot switch immediately without allowImmediateEntitlementReduction: true`
+      });
+    }
+  }
+});
+
+// ../contracts/dist/plans/spec/plan-pricing.js
+import { z as z4 } from "zod";
+
+// ../contracts/dist/plans/grants.js
+import { z as z3 } from "zod";
+var recurringGrantSchema = z3.object({
+  kind: z3.literal("recurring"),
+  amount_cents: z3.number().int().nonnegative()
+});
+var oneTimeGrantSchema = z3.object({
+  kind: z3.literal("one_time"),
+  amount_cents: z3.number().int().nonnegative()
+});
+var promotionalGrantSchema = z3.object({
+  kind: z3.literal("promotional"),
+  amount_cents: z3.number().int().nonnegative(),
+  label: z3.string().min(1).max(120),
+  expires_after_days: z3.number().int().positive().optional()
+});
+var trialGrantSchema = z3.object({
+  kind: z3.literal("trial")
+});
+var rolloverGrantSchema = z3.object({
+  kind: z3.literal("rollover"),
+  percent: z3.number().int().min(0).max(100)
+});
+var topUpGrantSchema = z3.object({
+  kind: z3.literal("top_up"),
+  /** Stable identifier surfaced to the customer (e.g. "tokens-50k"). */
+  sku: z3.string().min(1).max(120),
+  label: z3.string().min(1).max(200),
+  /** Price charged via Stripe checkout, in cents. */
+  price_cents: z3.number().int().positive(),
+  /** Credit balance granted when the pack is purchased, in cents.
+   *  Typically >= price_cents (the difference is the bulk discount). */
+  credit_cents: z3.number().int().positive()
+});
+var autoRechargeGrantSchema = z3.object({
+  kind: z3.literal("auto_recharge"),
+  /** When current balance < this many cents, trigger a refill. */
+  threshold_cents: z3.number().int().nonnegative(),
+  /** Charge + grant this much on each refill, in cents. */
+  refill_cents: z3.number().int().positive()
+});
+var grantSchema = z3.discriminatedUnion("kind", [
+  recurringGrantSchema,
+  oneTimeGrantSchema,
+  promotionalGrantSchema,
+  trialGrantSchema,
+  rolloverGrantSchema,
+  topUpGrantSchema,
+  autoRechargeGrantSchema
+]);
+function refineSingleCanonicalGrant(grants, ctx, path = ["grants"]) {
+  if (!grants)
+    return;
+  let recurringCount = 0;
+  let oneTimeCount = 0;
+  for (const g of grants) {
+    if (g.kind === "recurring")
+      recurringCount += 1;
+    else if (g.kind === "one_time")
+      oneTimeCount += 1;
+  }
+  if (recurringCount > 1) {
+    ctx.addIssue({
+      code: "custom",
+      message: "At most one `recurring` grant is allowed \u2014 recurring credit is a single canonical entry.",
+      path
+    });
+  }
+  if (oneTimeCount > 1) {
+    ctx.addIssue({
+      code: "custom",
+      message: "At most one `one_time` grant is allowed \u2014 one-time credit is a single canonical entry.",
+      path
+    });
+  }
+}
+
+// ../contracts/dist/plans/spec/plan-pricing.js
+var meterKindSchema = z4.enum(["linear", "active_count"]);
+var meterTierSchema = z4.object({
+  up_to: z4.number().int().positive().nullable(),
+  price_per_unit_micros: z4.number().int().nonnegative()
+});
+var tieredPricingSchema = z4.object({
+  strategy: z4.enum(["graduated", "volume"]),
+  tiers: z4.array(meterTierSchema).min(1).max(20)
+});
+var meterSchema = z4.object({
+  dimension: z4.string().min(1).max(64).regex(/^[a-z0-9_]+$/, "Meter dimension must be lowercase alphanumeric with underscores"),
+  /** Aggregation kind. `linear` (default) sums event quantities across
+   *  the period. `active_count` samples the latest quantity in the
+   *  period (use for seats / active-user / occupancy snapshots). */
+  kind: meterKindSchema.default("linear"),
+  /** Flat per-unit rate. Mutually exclusive with `tiered`. */
+  price_per_unit_micros: z4.number().int().nonnegative().default(0),
+  /** Tiered schedule. Mutually exclusive with a non-zero
+   *  `price_per_unit_micros`. */
+  tiered: tieredPricingSchema.optional(),
+  /** Per-meter included allotment: the first N units of this dimension
+   *  are free, every unit beyond N is billed at the flat
+   *  `price_per_unit_micros` rate (R may be 0). Compiles to a 2-tier
+   *  graduated schedule `[{up_to: N, micros: 0}, {up_to: null, micros: R}]`
+   *  and emits a tracking `quota` constraint so the gateway knows how
+   *  much is included.
+   *
+   *  Mutually exclusive with `tiered` — a tiered schedule already
+   *  expresses the full breakpoint ladder (model the free pool as a
+   *  zero-priced first tier instead). Only meaningful on a flat meter. */
+  included_units: z4.number().int().positive().optional()
+}).superRefine((m, ctx) => {
+  if (m.tiered && m.price_per_unit_micros > 0) {
+    ctx.addIssue({
+      code: "custom",
+      message: "`tiered` is mutually exclusive with a non-zero `price_per_unit_micros` \u2014 drop one",
+      path: ["tiered"]
+    });
+  }
+  if (m.included_units !== void 0 && m.tiered) {
+    ctx.addIssue({
+      code: "custom",
+      message: "`included_units` is mutually exclusive with `tiered` \u2014 a tiered schedule already expresses the included allotment as a zero-priced first tier",
+      path: ["included_units"]
+    });
+  }
+  if (m.tiered) {
+    let prevBound = 0;
+    let sawNull = false;
+    for (let i = 0; i < m.tiered.tiers.length; i++) {
+      const t = m.tiered.tiers[i];
+      if (sawNull) {
+        ctx.addIssue({
+          code: "custom",
+          message: "Open-ended tier (`up_to: null`) must be the final tier",
+          path: ["tiered", "tiers", i, "up_to"]
+        });
+        break;
+      }
+      if (t.up_to === null) {
+        sawNull = true;
+        continue;
+      }
+      if (t.up_to <= prevBound) {
+        ctx.addIssue({
+          code: "custom",
+          message: `Tier upper bounds must be strictly ascending (tier ${i} = ${t.up_to} <= previous ${prevBound})`,
+          path: ["tiered", "tiers", i, "up_to"]
+        });
+      }
+      prevBound = t.up_to;
+    }
+    if (!sawNull) {
+      ctx.addIssue({
+        code: "custom",
+        message: "The final tier of a `tiered` schedule must be open-ended (`up_to: null`)",
+        path: ["tiered", "tiers", m.tiered.tiers.length - 1, "up_to"]
+      });
+    }
+  }
+});
+var billingIntervalSchema = z4.enum(["month", "year"]);
+var planPricingSchema = z4.object({
+  /** Per-dimension price list. Empty array = no metered billing. */
+  meters: z4.array(meterSchema).default([]),
+  /** Flat subscription fee per period, in cents. 0 = no recurring fee. */
+  recurring_fee_cents: z4.number().int().nonnegative().default(0),
+  /** Billing cadence for the recurring fee + metered usage. Defaults to
+   *  `month`; set `year` for annual billing (drives both the Stripe price
+   *  `recurring.interval` and the spend-cap / quota billing-period window
+   *  length). */
+  billing_interval: billingIntervalSchema.default("month"),
+  /** Unified credit-grant array — the SINGLE credit surface. Recurring +
+   *  one-time credit are canonical entries here (the legacy scalar knobs
+   *  were removed). */
+  grants: z4.array(grantSchema).max(40).default([]),
+  /** Free-trial length in days. Trial enforcement runs through Stripe
+   *  webhooks → `lifecycle_block` constraint at runtime. */
+  trial_days: z4.number().int().nonnegative().default(0),
+  /** Optional hard cap on monthly spend, in cents. Orthogonal to the
+   *  billing math — the gateway blocks once this cap is reached even if
+   *  credit balance remains. Stripe doesn't enforce this; the runtime
+   *  does, via a `quota`-shaped constraint. */
+  max_monthly_spend_cents: z4.number().int().nonnegative().optional()
+});
+
+// ../contracts/dist/plans/spec/plan-variant.js
+import { z as z5 } from "zod";
+var proRationOnRollbackSchema = z5.enum(["NONE", "PRORATE", "CREDIT"]).default("NONE");
+var billingKnobsShape = {
+  meters: z5.array(meterSchema).default([]),
+  recurring_fee_cents: z5.number().int().nonnegative().default(0),
+  /** Billing cadence (`month` default / `year`). Drives the Stripe price
+   *  `recurring.interval` and the entitlement billing-period window. */
+  billing_interval: billingIntervalSchema.default("month"),
+  trial_days: z5.number().int().nonnegative().default(0),
+  /** Hard maximum on metered spend per period. Gateway blocks once
+   *  cumulative usage cost reaches this cap. Orthogonal to the
+   *  recurring fee — the fee is always charged. */
+  max_monthly_spend_cents: z5.number().int().nonnegative().optional(),
+  /** Minimum metered spend per period. When set, the invoice floors
+   *  the metered total at this value (Railway-style minimum-spend).
+   *  Orthogonal to `recurring_fee_cents` — the fee is added on top.
+   *  Set to 0 / omit to disable. */
+  min_monthly_spend_cents: z5.number().int().nonnegative().optional(),
+  /**
+   * Unified grants array — the SINGLE credit surface (v0.56+). Each entry
+   * expresses one credit grant primitive: `recurring`, `one_time`,
+   * `promotional`, `trial`, `rollover`, `top_up`, `auto_recharge`.
+   *
+   * Recurring + one-time credit are declared here as canonical
+   * `{kind:"recurring"}` / `{kind:"one_time"}` entries (at most one of
+   * each — enforced by `refineSingleCanonicalGrant`). The legacy
+   * `recurring_credit_grant_cents` / `one_time_credit_grant_cents` scalar
+   * knobs were removed; call `getEffectiveGrants(plan)` to read the
+   * consolidated list.
+   */
+  grants: z5.array(grantSchema).max(40).default([])
+};
+var billingKnobsOptionalShape = {
+  meters: z5.array(meterSchema).optional(),
+  recurring_fee_cents: z5.number().int().nonnegative().optional(),
+  /** Variant override for the billing cadence. Absent → inherit the
+   *  parent plan's `billing_interval`. */
+  billing_interval: billingIntervalSchema.optional(),
+  trial_days: z5.number().int().nonnegative().optional(),
+  max_monthly_spend_cents: z5.number().int().nonnegative().optional(),
+  min_monthly_spend_cents: z5.number().int().nonnegative().optional(),
+  /** Variant override for the grants array — the single credit surface.
+   *  When present, fully replaces the parent plan's grants (no shallow
+   *  merge — grants are collectively meaningful). */
+  grants: z5.array(grantSchema).max(40).optional()
+};
+var planVariantObjectSchema = z5.object({
+  /**
+   * Stable variant id — used as the second half of the CompiledPlan
+   * lineage key, so changing it counts as create-new + archive-old.
+   * Lower-case kebab-case to match URL-share-link readability.
+   */
+  id: z5.string().min(1).max(64).regex(/^[a-z0-9_-]+$/, "Variant id must be lowercase alphanumeric with hyphens/underscores"),
+  /** Human-readable label for dashboards / observability. */
+  label: z5.string().max(200).optional(),
+  /**
+   * Rollout percentage (0-100). 0 = paused (variant exists but no new
+   * assignments); 100 = full takeover (effectively a forced graduation
+   * for new subscribers, but legacy subs stay on parent until period end).
+   */
+  rolloutPercent: z5.number().int().min(0).max(100),
+  /**
+   * Seed for the deterministic hash function. Rotating the seed
+   * invalidates existing variant assignments — useful for re-running an
+   * experiment with a fresh cohort.
+   */
+  assignmentSeed: z5.string().min(1).max(100).default("default"),
+  /**
+   * What happens to billing when this variant gets rolled back AND the
+   * subscriber has already been billed for the experimental price:
+   *   - NONE (default): next period bills at parent price; no refund
+   *   - PRORATE: Stripe `proration_behavior=create_prorations` → mid-period credit
+   *   - CREDIT: full credit for the variant-priced charge as customer balance
+   * Out-of-scope: auto-refund. Builders use `billing.refund` if needed.
+   */
+  prorationOnRollback: proRationOnRollbackSchema,
+  // Optional 5-knob overrides — missing fields inherit from the parent
+  // plan. The pre-0.53 `pricing: planPricingSchema.optional()` field is
+  // gone; variants now override the knobs directly.
+  ...billingKnobsOptionalShape,
+  limits: z5.array(planLimitRuleSchema).max(20).optional(),
+  featureGates: z5.record(z5.string(), z5.boolean()).optional(),
+  /** See `planSpecSchema.capability_limits`. Variant overrides are
+   *  merged shallowly onto the parent plan's map — missing keys
+   *  inherit from the parent. */
+  capability_limits: z5.record(z5.string().min(1).max(120), z5.union([z5.number().int().nonnegative(), z5.boolean()])).optional(),
+  overageBehavior: z5.enum(["block", "allow_and_bill"]).optional()
+});
+var planVariantSchema = planVariantObjectSchema.superRefine((variant, ctx) => {
+  refineSingleCanonicalGrant(variant.grants, ctx);
+});
+var planSpecObjectSchema = z5.object({
+  key: z5.string().min(1).max(64).regex(/^[a-z0-9_-]+$/, "Plan key must be lowercase alphanumeric with hyphens/underscores"),
+  name: z5.string().min(1).max(100),
+  description: z5.string().max(500).optional(),
+  details: z5.array(z5.string().max(200)).max(10).optional(),
+  // ---------------------------------------------------------------------
+  // 5-knob billing shape (v0.53.0)
+  // ---------------------------------------------------------------------
+  //
+  // Billing math:
+  //   bill = recurring_fee
+  //        + max(0, total_meter_cost − applied_credit_balance)
+  //        − discounts
+  //
+  // Stripe applies grants at invoice finalization. Trial enforcement
+  // runs through Stripe webhooks → `lifecycle_block` constraint at
+  // runtime; there's no `trial_expiry` constraint kind anymore.
+  ...billingKnobsShape,
+  free: z5.boolean().default(false),
+  // `plan.features` removed in feat/feature-plans-link — features
+  // declare their plans via `feature.plans[]` (canonical, feature-first
+  // direction). Builders writing the manifest now go to the feature
+  // they're adding routes to and list which plans grant access. The
+  // compiler walks `spec.features` and includes a feature's routes for
+  // a plan when the plan's key appears in `feature.plans[]`. See
+  // shared-types/src/plans/spec/product.ts (featureCatalogEntrySchema).
+  limits: z5.array(planLimitRuleSchema).max(20).default([]),
+  featureGates: z5.record(z5.string(), z5.boolean()).optional(),
+  /**
+   * Control-plane capability limits (Phase 1a, v0.56+).
+   *
+   * Caps on the count of *control-plane objects* a subscriber can create
+   * on a given plan (webhooks, API keys, environments, custom domains,
+   * workflows, team-member seats, …) plus boolean feature toggles
+   * (enterprise_sso, audit_log, …).
+   *
+   * Map of `capabilityKey → maxCount | boolean`.
+   *
+   * Numeric limits are *inclusive* — a limit of 5 means up to 5
+   * instances are allowed. Boolean flags express feature enablement
+   * (true = enabled; false / missing = disabled).
+   *
+   * These are NOT edge enforcement concerns; the gateway only carries
+   * the projection for client UIs. Enforcement happens at the route
+   * handler via `assertCapacity()` in core.
+   *
+   * The platform doesn't enumerate valid keys — every product /
+   * route handler defines its own set. Conventionally lowercase with
+   * underscores.
+   *
+   * Example:
+   *   capability_limits:
+   *     webhooks: 5
+   *     api_keys: 10
+   *     environments: 1
+   *     enterprise_sso: true
+   */
+  capability_limits: z5.record(z5.string().min(1).max(120), z5.union([z5.number().int().nonnegative(), z5.boolean()])).default({}),
+  overageBehavior: z5.enum(["block", "allow_and_bill"]).default("block"),
+  selfServeEnabled: z5.boolean().default(true),
+  /**
+   * Phase A0 — multi-stable plan support.
+   *
+   * `legacy: true` marks a plan version that should be kept alive
+   * indefinitely for the existing subscriber cohort, alongside a new
+   * ACTIVE plan in the same lineage. Compiles into `CompiledPlan` with
+   * status `LEGACY_STABLE`. The plan is hidden from the public Pricing
+   * page; new subscribers cannot join. Removing a `legacy: true` plan
+   * from YAML while subs are pinned to it is a compile error (would
+   * orphan the cohort).
+   */
+  legacy: z5.boolean().optional().default(false),
+  /**
+   * Phase A0 — A/B testing variants of this plan. Each variant compiles
+   * into a sibling `CompiledPlan` with status `EXPERIMENTAL` and
+   * `experimentParentId` pointing at this plan's CompiledPlan.
+   *
+   * Constraints (enforced at compile time):
+   *   - Cannot coexist with `legacy: true` on the same plan
+   *   - Variant `id` must be unique within the variants array
+   */
+  variants: z5.array(planVariantSchema).max(4).optional(),
+  archive: z5.object({
+    at: z5.string().datetime().optional(),
+    transitionTo: z5.string().optional(),
+    strategy: z5.enum(["auto", "explicit", "block"]).default("auto")
+  }).optional()
+});
+var planSpecSchema = planSpecObjectSchema.superRefine((plan, ctx) => {
+  refineSingleCanonicalGrant(plan.grants, ctx);
+});
+
+// ../contracts/dist/plans/spec/webhooks.js
+import { z as z7 } from "zod";
+
+// ../contracts/dist/webhooks/events.js
+import { z as z6 } from "zod";
+var WEBHOOK_EVENT_NAMES = [
+  "subscription.created",
+  "subscription.updated",
+  "subscription.canceled",
+  "payment.succeeded",
+  "payment.failed",
+  "rate_limit.exceeded",
+  "entitlement.changed",
+  "usage.threshold_reached"
+];
+var webhookEventNameSchema = z6.enum(WEBHOOK_EVENT_NAMES);
+
+// ../contracts/dist/plans/spec/webhooks.js
+var WEBHOOK_SECRET_PLACEHOLDER_PATTERN = /^\$\{[A-Z][A-Z0-9_]{0,127}\}$/;
+var webhookSecretSchema = z7.string().min(3).max(200).refine((value) => WEBHOOK_SECRET_PLACEHOLDER_PATTERN.test(value), {
+  message: "secret must use ${VAR} interpolation syntax (e.g. ${WEBHOOK_SECRET}); raw secrets in YAML are rejected. Define the env var in the per-product secret store and reference it here."
+});
+var webhookRetryPolicySchema = z7.object({
+  maxAttempts: z7.number().int().min(1).max(20).default(5),
+  backoff: z7.enum(["exponential", "fixed"]).default("exponential")
+});
+var webhookEndpointSchema = z7.object({
+  /**
+   * Stable endpoint id — used as the third key of the
+   * `(productId, environmentId, id)` uniqueness tuple. Idempotent upsert
+   * keys on this id; renaming an id is delete + recreate.
+   */
+  id: z7.string().min(1).max(64).regex(/^[a-z0-9_-]+$/, "Webhook endpoint id must be lowercase alphanumeric with hyphens/underscores"),
+  /** Public HTTPS URL the dispatcher POSTs to. */
+  url: z7.string().url("webhooks.endpoints[].url must be a valid URL"),
+  /**
+   * Signing secret. MUST be a `${VAR}` placeholder; raw secrets in YAML
+   * are rejected by invariant 8. The seal pass resolves this against the
+   * per-product secret store at compile time and stamps the resolved
+   * value onto the WebhookEndpoint row.
+   */
+  secret: webhookSecretSchema,
+  /**
+   * Subset of the central event catalog this endpoint subscribes to.
+   * Each value is validated against `webhookEventNameSchema` —
+   * unknown events fail invariant 9.
+   */
+  events: z7.array(webhookEventNameSchema).min(1, "webhooks.endpoints[].events must subscribe to \u2265 1 event"),
+  enabled: z7.boolean().default(true),
+  retryPolicy: webhookRetryPolicySchema.default({
+    maxAttempts: 5,
+    backoff: "exponential"
+  })
+});
+var webhooksBlockSchema = z7.object({
+  endpoints: z7.array(webhookEndpointSchema).max(50).default([])
+});
+
+// ../contracts/dist/plans/spec/environments.js
+import { z as z8 } from "zod";
+var planOverrideSchema = z8.object({
+  meters: z8.array(meterSchema).optional(),
+  recurring_fee_cents: z8.number().int().nonnegative().optional(),
+  /** Per-env override for the billing cadence. Absent → inherit the
+   *  base plan's `billing_interval`. */
+  billing_interval: billingIntervalSchema.optional(),
+  /** Credit override — the unified grants array is the single credit
+   *  surface. When present it fully replaces the parent plan's grants
+   *  for this environment (the legacy recurring/one-time scalar knobs
+   *  were removed). */
+  grants: z8.array(grantSchema).max(40).optional(),
+  trial_days: z8.number().int().nonnegative().optional(),
+  max_monthly_spend_cents: z8.number().int().nonnegative().optional(),
+  limits: z8.array(planLimitRuleSchema).max(20).optional(),
+  featureGates: z8.record(z8.string(), z8.boolean()).optional(),
+  overageBehavior: z8.enum(["block", "allow_and_bill"]).optional(),
+  selfServeEnabled: z8.boolean().optional(),
+  legacy: z8.boolean().optional()
+}).strict();
+var webhookEndpointOverrideSchema = z8.object({
+  url: z8.string().url().optional(),
+  secret: webhookSecretSchema.optional(),
+  events: z8.array(webhookEventNameSchema).optional(),
+  enabled: z8.boolean().optional(),
+  retryPolicy: webhookRetryPolicySchema.partial().optional()
+}).strict();
+var environmentOverrideBlockSchema = z8.object({
+  plans: z8.record(z8.string(), planOverrideSchema).optional(),
+  webhooks: z8.object({
+    endpoints: z8.record(z8.string(), webhookEndpointOverrideSchema).optional()
+  }).strict().optional()
+}).strict();
+var environmentsBlockSchema = z8.record(z8.string().min(1).max(64), environmentOverrideBlockSchema);
+
+// ../contracts/dist/plans/spec/product.js
+import { z as z13 } from "zod";
+
+// ../contracts/dist/plans/spec/frontend-layer.js
+import { z as z9 } from "zod";
+var FRONTEND_MANIFEST_SCHEMA_VERSION = 1;
+var KNOWN_FRONTEND_COMPONENT_IDS = [
+  "plans_table",
+  "usage_card",
+  "api_keys_panel",
+  "billing_summary",
+  "credit_balance",
+  "feature_panel",
+  "product_docs",
+  "audit_log",
+  "team_panel",
+  "markdown"
+];
+var RESERVED_TEMPLATE_PATHS = [
+  "/",
+  "/pricing",
+  "/dashboard",
+  "/dashboard/*",
+  "/settings",
+  "/settings/*",
+  "/team",
+  "/audit-log",
+  "/docs",
+  "/docs/*",
+  "/terms",
+  "/privacy",
+  "/persona",
+  "/persona-sign-in"
+];
+var frontendPathSchema = z9.string().min(1).max(200).regex(/^\/[a-zA-Z0-9_./-]*$/, "path must start with / and contain only [a-zA-Z0-9_./-]");
+var frontendCapabilityRefSchema = z9.string().min(1).max(120).regex(/^[a-z0-9_-]+$/);
+var frontendNavItemSchema = z9.object({
+  label: z9.string().min(1).max(80),
+  path: frontendPathSchema,
+  capability: frontendCapabilityRefSchema.optional()
+});
+var frontendComponentIdSchema = z9.enum(KNOWN_FRONTEND_COMPONENT_IDS);
+var frontendComponentSchema = z9.object({
+  component: frontendComponentIdSchema,
+  props: z9.record(z9.string().min(1).max(80), z9.unknown()).optional(),
+  capability: frontendCapabilityRefSchema.optional(),
+  gateMode: z9.enum(["hide", "disable", "upsell"]).default("hide")
+});
+var frontendPageSchema = z9.object({
+  path: frontendPathSchema,
+  title: z9.string().min(1).max(120),
+  requiresAuth: z9.boolean(),
+  capability: frontendCapabilityRefSchema.optional(),
+  components: z9.array(frontendComponentSchema).max(12).default([])
+});
+var frontendManifestSchema = z9.object({
+  version: z9.literal(FRONTEND_MANIFEST_SCHEMA_VERSION),
+  nav: z9.array(frontendNavItemSchema).max(12).default([]),
+  pages: z9.array(frontendPageSchema).max(24).default([])
+}).superRefine((manifest, ctx) => {
+  const seenPages = /* @__PURE__ */ new Set();
+  manifest.pages.forEach((page, index) => {
+    if (seenPages.has(page.path)) {
+      ctx.addIssue({
+        code: "custom",
+        message: `duplicate frontend page path "${page.path}"`,
+        path: ["pages", index, "path"]
+      });
+    }
+    seenPages.add(page.path);
+    if (isReservedTemplatePath(page.path)) {
+      ctx.addIssue({
+        code: "custom",
+        message: `frontend page path "${page.path}" is reserved by the template`,
+        path: ["pages", index, "path"]
+      });
+    }
+  });
+});
+function isReservedTemplatePath(path) {
+  return RESERVED_TEMPLATE_PATHS.some((reserved) => {
+    if (reserved.endsWith("/*")) {
+      const prefix = reserved.slice(0, -2);
+      return path === prefix || path.startsWith(`${prefix}/`);
+    }
+    return path === reserved;
+  });
+}
+
+// ../contracts/dist/plans/spec/migrations-layer.js
+import { z as z10 } from "zod";
+var planKeySchema = z10.string().min(1).max(64).regex(/^[a-z0-9_-]+$/, "Plan key must be lowercase alphanumeric with hyphens/underscores");
+var versionRefSchema = z10.string().min(1).max(100);
+var planVersionRefSchema = z10.object({
+  plan: planKeySchema,
+  version: versionRefSchema.optional()
+});
+var migrationTargetSchema = z10.object({
+  plan: planKeySchema,
+  version: z10.literal("head").default("head")
+});
+var pinnedPlanVersionSchema = z10.object({
+  plan: planKeySchema,
+  version: versionRefSchema
+});
+var migrationEffectiveSchema = z10.enum([
+  "grandfather",
+  "next_renewal",
+  "by_date",
+  "immediate",
+  "opt_in"
+]);
+var migrationProrationSchema = z10.enum(["none", "prorate", "credit"]);
+var migrationExistingCustomersSchema = z10.object({
+  effective: migrationEffectiveSchema,
+  date: z10.string().datetime().optional(),
+  proration: migrationProrationSchema.optional()
+}).superRefine((policy, ctx) => {
+  if (policy.effective === "by_date" && policy.date === void 0) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["date"],
+      message: "existingCustomers.date is required when effective is by_date"
+    });
+  }
+});
+var migrationPinSchema = z10.object({
+  subscriber: z10.string().min(1).max(200),
+  pinTo: pinnedPlanVersionSchema,
+  until: z10.string().datetime().optional(),
+  notes: z10.string().max(1e3).optional()
+});
+var migrationDeclSchema = z10.object({
+  id: z10.string().min(1).max(120).regex(/^[a-z0-9][a-z0-9_.-]*$/, "Migration id must be lowercase alphanumeric with dots, hyphens, or underscores"),
+  from: planVersionRefSchema,
+  to: migrationTargetSchema,
+  newCustomers: z10.literal("immediate").default("immediate"),
+  existingCustomers: migrationExistingCustomersSchema,
+  pins: z10.array(migrationPinSchema).max(50).default([])
+});
+var migrationDeclsSchema = z10.array(migrationDeclSchema).superRefine((migrations, ctx) => {
+  const seen = /* @__PURE__ */ new Set();
+  migrations.forEach((migration, index) => {
+    if (seen.has(migration.id)) {
+      ctx.addIssue({
+        code: "custom",
+        path: [index, "id"],
+        message: `duplicate migration id "${migration.id}"`
+      });
+    }
+    seen.add(migration.id);
+  });
+});
+
+// ../contracts/dist/plans/spec/counted-resources.js
+import { z as z11 } from "zod";
+var countedResourceScopeSchema = z11.enum(["subscription", "subject"]);
+var countedResourceCountSourceSchema = z11.enum([
+  "reported",
+  "action_inferred"
+]);
+var countedResourceNameSchema = z11.string().min(1).max(100).regex(/^[a-z0-9_.:-]+$/);
+var countedResourceSchema = z11.object({
+  name: countedResourceNameSchema,
+  display: z11.string().min(1).max(120).optional(),
+  scope: countedResourceScopeSchema.default("subscription"),
+  subjectType: z11.string().min(1).max(64).regex(/^[a-zA-Z0-9_.:-]+$/).optional(),
+  countSource: countedResourceCountSourceSchema.default("reported")
+}).superRefine((resource, ctx) => {
+  if (resource.scope === "subject" && !resource.subjectType) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["subjectType"],
+      message: "subjectType is required when resource scope is subject"
+    });
+  }
+  if (resource.scope === "subscription" && resource.subjectType) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["subjectType"],
+      message: "subjectType is only valid for subject-scoped counted resources"
+    });
+  }
+});
+var countedResourcesSchema = z11.array(countedResourceSchema).max(100).default([]);
+
+// ../contracts/dist/plans/addons.js
+import { z as z12 } from "zod";
+var addOnSchema = z12.object({
+  /** Stable identifier — appears in `SubscriptionAddOn.addOnKey` and in
+   *  Stripe metadata. Lowercase alphanumeric with hyphens/underscores
+   *  to match the plan-key grammar. */
+  key: z12.string().min(1).max(64).regex(/^[a-z0-9_-]+$/, "AddOn key must be lowercase alphanumeric with hyphens/underscores"),
+  /** Display name (Pricing page chip, settings list, etc.). */
+  name: z12.string().min(1).max(100),
+  /** Short description for tooltips / chooser. */
+  description: z12.string().max(500).optional(),
+  /** Recurring fee added to the subscription invoice while the AddOn is
+   *  active. 0 = no recurring fee (e.g. for boolean feature toggles or
+   *  one-time-grant-only packs). */
+  recurring_fee_cents: z12.number().int().nonnegative().default(0),
+  /** Billing cadence for this add-on's recurring fee (`month` default /
+   *  `year`). Drives the add-on's Stripe price `recurring.interval`. */
+  billing_interval: billingIntervalSchema.default("month"),
+  /** Additional metered dimensions/rates enabled by this AddOn. Merged
+   *  into the effective entitlement's meter list (by dimension).
+   *  Conflict resolution at compile time: AddOn meter wins over base
+   *  plan meter for the same dimension (PR 2a-2 implements this). */
+  meters: z12.array(meterSchema).default([]),
+  /** Grants issued when the AddOn is activated and/or on each period
+   *  rollover (kind-dependent). Same vocabulary as plan grants. */
+  grants: z12.array(grantSchema).max(40).default([]),
+  /** Capability bumps. Numeric limits combine with the base via MAX
+   *  (so an "extra seats" addon raises the ceiling without lowering
+   *  it). Boolean flags combine with OR (any true wins). */
+  capability_limits: z12.record(z12.string().min(1).max(120), z12.union([z12.number().int().nonnegative(), z12.boolean()])).default({}),
+  /** Additive feature gates. Keys true here are appended to the
+   *  effective entitlement's gate set. */
+  featureGates: z12.record(z12.string(), z12.boolean()).optional(),
+  /** Whether the AddOn is visible in the subscriber-facing catalog.
+   *  When false, only admin-issued (not self-serve). Defaults true. */
+  selfServeEnabled: z12.boolean().default(true)
+});
+var addOnsBlockSchema = z12.record(z12.string().min(1).max(64), addOnSchema).default({});
+var subscriptionAddOnStatusSchema = z12.enum([
+  "active",
+  "canceled",
+  "paused",
+  "pending_activation"
+]);
+var subscriptionAddOnSchema = z12.object({
+  /** References `product.add_ons.<addOnKey>`. */
+  addOnKey: z12.string().min(1).max(64),
+  /** Status drives entitlement composition: only `active` AddOns
+   *  contribute to the effective entitlement. */
+  status: subscriptionAddOnStatusSchema.default("active"),
+  /** When the AddOn became active (ISO-8601). Drives one-time grant
+   *  issuance and recurring-fee start. */
+  activatedAt: z12.string().datetime().optional(),
+  /** When the AddOn was canceled (ISO-8601). Null while active. */
+  canceledAt: z12.string().datetime().nullable().optional(),
+  /** Stripe subscription-item id for the recurring-fee line, when
+   *  the AddOn declares a non-zero `recurring_fee_cents`. */
+  stripeSubscriptionItemId: z12.string().optional()
+});
+
+// ../contracts/dist/plans/spec/refinements.js
+function rejectUsagePricing(spec, ctx) {
+  if (spec.usagePricing === void 0)
+    return;
+  ctx.addIssue({
+    code: "custom",
+    path: ["usagePricing"],
+    message: "usagePricing is not supported. Define usage.meters.<key>.rating instead."
+  });
+}
+function validateFreePlans(plans, ctx) {
+  const freePlans = plans.filter((plan) => plan.free);
+  if (freePlans.length > 1) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["plans"],
+      message: "Only one free plan is allowed per product"
+    });
+  }
+  plans.forEach((plan, index) => {
+    if (!plan.free)
+      return;
+    validateFreePlanPrice(plan, index, ctx);
+    validateFreePlanHardLimit(plan, index, ctx);
+  });
+}
+function validateFreePlanPrice(plan, index, ctx) {
+  const monthly = planMonthlyPrice(plan);
+  if ((monthly ?? 0) === 0)
+    return;
+  ctx.addIssue({
+    code: "custom",
+    path: ["plans", index, "recurring_fee_cents"],
+    message: "Free plans must have zero price"
+  });
+}
+function validateFreePlanHardLimit(plan, index, ctx) {
+  const hasHardLimit = plan.limits.some((limit) => !limit.enforcement || limit.enforcement === "enforce");
+  if (hasHardLimit)
+    return;
+  ctx.addIssue({
+    code: "custom",
+    path: ["plans", index, "limits"],
+    message: "Free plans must include at least one hard enforced limit"
+  });
+}
+function validatePaidPlanPrices(plans, ctx) {
+  const priceKeys = /* @__PURE__ */ new Map();
+  plans.forEach((plan, index) => {
+    if (plan.free)
+      return;
+    const monthly = planMonthlyPrice(plan);
+    if (monthly === void 0 || monthly <= 0)
+      return;
+    const key = planPriceKey(plan, monthly);
+    const existing = priceKeys.get(key);
+    if (existing) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["plans", index, "recurring_fee_cents"],
+        message: `Paid plan price duplicates plan "${existing}" (${key})`
+      });
+      return;
+    }
+    priceKeys.set(key, plan.key);
+  });
+}
+function validateMeterReferences(spec, ctx) {
+  const runtimeMeterKeys = new Set((spec.metering?.meters ?? []).map((m) => m.key).filter((k) => typeof k === "string" && k.length > 0));
+  const usageMeterKeys = new Set(Object.keys(spec.usage?.meters ?? {}));
+  spec.plans.forEach((plan, index) => {
+    const meters = plan.meters;
+    if (!meters)
+      return;
+    meters.forEach((meter, meterIdx) => {
+      const dim = meter.dimension;
+      if (typeof dim !== "string" || dim.length === 0)
+        return;
+      if (runtimeMeterKeys.has(dim))
+        return;
+      if (usageMeterKeys.has(dim))
+        return;
+      ctx.addIssue({
+        code: "custom",
+        path: ["plans", index, "meters", meterIdx, "dimension"],
+        message: `Plan "${plan.key}" prices meter "${dim}" but no metering.meters[] entry and no usage.meters[] entry declares it.`
+      });
+    });
+  });
+}
+function validateFeatureReferences(spec, ctx) {
+  if (!spec.features)
+    return;
+  const planKeys = new Set(spec.plans.map((p) => p.key));
+  for (const [featureKey, feature] of Object.entries(spec.features)) {
+    if (!feature.plans)
+      continue;
+    feature.plans.forEach((planKey, idx) => {
+      if (planKeys.has(planKey))
+        return;
+      ctx.addIssue({
+        code: "custom",
+        path: ["features", featureKey, "plans", idx],
+        message: `Feature "${featureKey}" references unknown plan "${planKey}"`
+      });
+    });
+    const seen = /* @__PURE__ */ new Set();
+    feature.plans.forEach((planKey, idx) => {
+      if (seen.has(planKey)) {
+        ctx.addIssue({
+          code: "custom",
+          path: ["features", featureKey, "plans", idx],
+          message: `Feature "${featureKey}" lists plan "${planKey}" more than once`
+        });
+      }
+      seen.add(planKey);
+    });
+  }
+}
+function validateRouteMeters(spec, ctx) {
+  if (!spec.features)
+    return;
+  const meterKeys = new Set((spec.metering?.meters ?? []).map((m) => m.key).filter((k) => typeof k === "string" && k.length > 0));
+  let anyRouteDeclaresMeters = false;
+  for (const [featureKey, feature] of Object.entries(spec.features)) {
+    const routes = feature.routes ?? [];
+    routes.forEach((route, routeIdx) => {
+      if (!route.meters || route.meters.length === 0)
+        return;
+      anyRouteDeclaresMeters = true;
+      route.meters.forEach((meter, meterIdx) => {
+        if (meterKeys.has(meter))
+          return;
+        ctx.addIssue({
+          code: "custom",
+          path: [
+            "features",
+            featureKey,
+            "routes",
+            routeIdx,
+            "meters",
+            meterIdx
+          ],
+          message: `Route references unknown meter "${meter}". Declare it in metering.meters[].`
+        });
+      });
+    });
+  }
+  if (anyRouteDeclaresMeters && meterKeys.size === 0) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["metering", "meters"],
+      message: "One or more routes declare `meters` but `metering.meters[]` is empty. Declare meters at the product level first."
+    });
+  }
+}
+function buildReachableMetersByPlan(spec, runtimeMeters) {
+  const out = /* @__PURE__ */ new Map();
+  for (const plan of spec.plans) {
+    out.set(plan.key, /* @__PURE__ */ new Set());
+  }
+  if (!spec.features) {
+    for (const set of out.values()) {
+      for (const m of runtimeMeters)
+        set.add(m);
+    }
+    return out;
+  }
+  for (const feature of Object.values(spec.features)) {
+    addFeatureMetersToReachable(feature, runtimeMeters, out);
+  }
+  return out;
+}
+function addFeatureMetersToReachable(feature, runtimeMeters, reachableByPlan) {
+  const grantedPlanKeys = feature.plans ?? [];
+  const routes = feature.routes ?? [];
+  for (const planKey of grantedPlanKeys) {
+    const reachable = reachableByPlan.get(planKey);
+    if (!reachable)
+      continue;
+    for (const route of routes) {
+      if (route.unmetered === true)
+        continue;
+      if (route.meters && route.meters.length > 0) {
+        for (const meter of route.meters)
+          reachable.add(meter);
+        continue;
+      }
+      for (const m of runtimeMeters)
+        reachable.add(m);
+    }
+  }
+}
+function extractLimitMeterKey(limit) {
+  if (!limit || typeof limit !== "object")
+    return null;
+  const candidate = limit;
+  if (typeof candidate.dimension === "string")
+    return candidate.dimension;
+  return null;
+}
+var SPECIAL_REACHABLE_DIMENSIONS = /* @__PURE__ */ new Set(["credits"]);
+function validateLimitMeterReachability(spec, ctx) {
+  if (!spec.plans || spec.plans.length === 0)
+    return;
+  const runtimeMeters = new Set((spec.metering?.meters ?? []).map((m) => m.key).filter((k) => typeof k === "string" && k.length > 0));
+  const usageMeters = new Set(Object.keys(spec.usage?.meters ?? {}));
+  const reachableByPlan = buildReachableMetersByPlan(spec, runtimeMeters);
+  spec.plans.forEach((plan, planIdx) => {
+    const limits = plan.limits ?? [];
+    const reachable = reachableByPlan.get(plan.key) ?? /* @__PURE__ */ new Set();
+    limits.forEach((limit, limitIdx) => {
+      const ack = limit && typeof limit === "object" ? limit.acknowledgeUnreachable === true : false;
+      if (ack)
+        return;
+      const meterKey = extractLimitMeterKey(limit);
+      if (!meterKey)
+        return;
+      if (reachable.has(meterKey))
+        return;
+      if (usageMeters.has(meterKey))
+        return;
+      if (SPECIAL_REACHABLE_DIMENSIONS.has(meterKey))
+        return;
+      ctx.addIssue({
+        code: "custom",
+        path: ["plans", planIdx, "limits", limitIdx, "meter"],
+        message: `Plan "${plan.key}" limits meter "${meterKey}" but no route in any granted feature emits this meter, and the meter is not declared under usage.meters either. Either grant a feature whose routes meter "${meterKey}" to this plan, declare the meter under metering.meters[] or usage.meters, or set acknowledgeUnreachable: true if the limit is intentional (e.g. soft budget).`
+      });
+    });
+  });
+}
+function planMonthlyPrice(plan) {
+  return plan.recurring_fee_cents;
+}
+function planPriceKey(plan, monthly) {
+  void plan;
+  return `USD:month:${monthly}`;
+}
+
+// ../contracts/dist/plans/spec/product.js
+var productIdentitySchema = z13.object({
+  subdomain: z13.string().min(1).max(63).regex(/^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/, "Subdomain must be lowercase alphanumeric with optional hyphens")
+});
+var meterEnforcementTypeSchema = z13.enum([
+  "exact_pre_request",
+  "estimated_then_settled",
+  "postpaid",
+  "strict_concurrency"
+]);
+var meterDefinitionSchema = z13.object({
+  key: z13.string().min(1).max(64).regex(/^[a-z0-9_]+$/, "Meter key must be lowercase alphanumeric with underscores"),
+  display: z13.string().min(1).max(100),
+  // v0.42.0 — `type: "built-in" | "custom"` removed. The runtime never
+  // read it (gateway estimators key on meter NAME, Stripe meter
+  // creation keys on meter KEY); it was schema documentation. Wizard
+  // pre-fills sensible meters per template (api_calls → `requests`;
+  // ai_usage → `dollars`); Custom template lets builders define keys
+  // freely. Old specs with `type: ...` parse cleanly because Zod
+  // strips unknown fields by default.
+  unit: z13.string().max(20).optional(),
+  /**
+   * Runtime enforcement semantics for this meter. This is compiled into
+   * signed gateway artifacts so the edge chooses reservation, settlement,
+   * postpaid, or strict permit behavior from declarative config rather than from
+   * mutable gateway-side defaults.
+   */
+  enforcementType: meterEnforcementTypeSchema.default("estimated_then_settled"),
+  // ---------------------------------------------------------------------
+  // 0.29.0 — meter aggregation contract (FAR-394 / Phase 1a).
+  //
+  // Mirrors Lago's BillableMetric so a meter defined here can be
+  // pushed to Lago without a translation layer. `aggregation` and
+  // `window` carry safe defaults so existing CompiledPlan rows in
+  // core's DB (which carry historical specs) continue to parse.
+  // The property fields are optional at the schema level; core's
+  // validate-pass (Phase 1b) enforces the conditional requirements
+  // (`valueProperty` required for SUM/MAX, `uniqueProperty`
+  // required for UNIQUE_COUNT) where it has the cross-field context.
+  // ---------------------------------------------------------------------
+  /**
+   * How to aggregate measured values into a usage figure for the
+   * current `window`. Defaults to `COUNT` (one event = one unit) so
+   * existing meters that didn't declare aggregation continue to work.
+   */
+  aggregation: z13.enum(["SUM", "COUNT", "MAX", "UNIQUE_COUNT", "LATEST"]).default("COUNT"),
+  /**
+   * Aggregation window. `billing_period` (the default) makes the
+   * meter accumulate across the subscription's billing period.
+   * Sub-period windows (`minute`/`hour`/`day`/`month`) are for
+   * rate-limit-shaped meters where the period boundary is a fixed
+   * wall-clock interval, not the subscription anniversary.
+   */
+  window: z13.enum(["minute", "hour", "day", "month", "billing_period"]).default("billing_period"),
+  /**
+   * Property on the event payload to read for `SUM` and `MAX`
+   * aggregations. Optional at the schema level; core's `validate.ts`
+   * (Phase 1b) enforces "required when aggregation is SUM or MAX".
+   */
+  valueProperty: z13.string().optional(),
+  /**
+   * Property on the event payload to dedupe on for `UNIQUE_COUNT`
+   * aggregation. Optional at the schema level; core's validate-pass
+   * enforces "required when aggregation is UNIQUE_COUNT".
+   */
+  uniqueProperty: z13.string().optional(),
+  /**
+   * Optional grouping dimensions. When set, the aggregation is per
+   * unique combination of these properties' values, not a single
+   * scalar. Used for per-region or per-model breakdowns.
+   */
+  groupBy: z13.array(z13.string()).optional(),
+  /**
+   * Lago-side event code for ingress correlation. Matches Lago's
+   * BillableMetric `code` so events sent to Lago land on the right
+   * meter without a per-meter translation table.
+   */
+  eventCode: z13.string().optional()
+});
+var usageMeasureSchema = z13.string().min(1).max(64).regex(/^[a-z0-9_]+$/, "Usage measure must be lowercase alphanumeric with underscores");
+var usageRatingPricePolicySchema = z13.enum([
+  "pass_through",
+  "markup",
+  "fixed_margin",
+  "customer_rate"
+]);
+var fixedRatingSchema = z13.object({
+  source: z13.literal("fixed"),
+  rates: z13.record(z13.string().min(1), z13.record(usageMeasureSchema, z13.number().int().nonnegative()))
+});
+var providerCatalogRatingSchema = z13.object({
+  source: z13.literal("provider_catalog"),
+  catalog: z13.string().min(1).max(100),
+  pricePolicy: usageRatingPricePolicySchema.default("pass_through"),
+  markupPercent: z13.number().nonnegative().max(1e4).optional(),
+  marginMicros: z13.number().int().nonnegative().optional()
+});
+var upstreamReportedRatingSchema = z13.object({
+  source: z13.literal("upstream_reported"),
+  amountField: z13.string().min(1).max(500),
+  currencyField: z13.string().min(1).max(500).optional()
+});
+var externalRateApiRatingSchema = z13.object({
+  source: z13.literal("external_rate_api"),
+  resolver: z13.string().min(1).max(100),
+  configRef: z13.string().min(1).max(200).optional()
+});
+var customRatingSchema = z13.object({
+  source: z13.literal("custom"),
+  resolver: z13.string().min(1).max(100),
+  configRef: z13.string().min(1).max(200).optional()
+});
+var usageRatingSchema = z13.discriminatedUnion("source", [
+  fixedRatingSchema,
+  providerCatalogRatingSchema,
+  upstreamReportedRatingSchema,
+  externalRateApiRatingSchema,
+  customRatingSchema
+]);
+var usageMeterSchema = z13.object({
+  selector: z13.string().min(1).max(100).optional(),
+  measures: z13.array(usageMeasureSchema).min(1).max(20),
+  rating: usageRatingSchema.optional()
+});
+var usageBlockSchema = z13.object({
+  meters: z13.record(z13.string().min(1).max(64).regex(/^[a-z0-9_]+$/), usageMeterSchema)
+});
+var featureRouteSchema = z13.object({
+  method: z13.enum(["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS", "*"]).default("*"),
+  // Path is the route under the product's baseUrl. OpenAPI parameter
+  // syntax is supported and translated by the compiler:
+  //   /users/:id   → /users/*
+  //   /users/{id}  → /users/*
+  // Path-globs `*` (one segment) and `**` (any subpath) are passed
+  // through. The compiler rejects ambiguous compound segments like
+  // `/foo/:a-:b` — parameter names must occupy whole segments.
+  path: z13.string().min(1).max(500).regex(/^\/[a-zA-Z0-9_/:.{}*-]*$/, "path must start with / and contain only [a-zA-Z0-9_/:.{}*-]"),
+  // Optional per-route meter binding (Option B, v0.41.0). When set,
+  // the gateway only emits usage events for these meters on requests
+  // matching this route — `requests` and token meters get scoped
+  // independently per route. Resolution rules:
+  //   - omitted   → route inherits "all configured product meters"
+  //                 (back-compat with manifests written before v0.41)
+  //   - non-empty → only these meters increment
+  //   - []        → REJECTED at parse (`ROUTE_METERS_EMPTY_ARRAY`).
+  //                 Use `unmetered: true` for the explicit opt-out.
+  //   - null      → treated as omitted (PATCH-clear UX)
+  //
+  // Each entry must resolve to a key in `metering.meters[].key`;
+  // otherwise the cross-validation refinement
+  // `validateRouteMeters` rejects with `UNKNOWN_METER_IN_ROUTE`.
+  meters: z13.array(z13.string().min(1).max(64)).min(1, "Use `unmetered: true` instead of an empty array (typo guard against silently-unmetered routes)").max(20).nullable().optional(),
+  // Explicit unmetered route. Mutually exclusive with `meters` (the
+  // `superRefine` below catches any builder that sets both).
+  // Compiles to `entitlement.fr[i].meters: []` on the wire side so
+  // the gateway short-circuits both DO consume and event publish.
+  unmetered: z13.boolean().optional()
+}).superRefine((route, ctx) => {
+  if (route.unmetered === true && route.meters && route.meters.length > 0) {
+    ctx.addIssue({
+      code: "custom",
+      message: "`unmetered: true` is mutually exclusive with `meters` \u2014 drop one",
+      path: ["unmetered"]
+    });
+  }
+});
+var featureCatalogEntrySchema = z13.object({
+  // Optional human-friendly summary; surfaced in dashboards / settings UI.
+  description: z13.string().max(500).optional(),
+  routes: z13.array(featureRouteSchema).min(1).max(50),
+  // Plans that grant this feature. Feature-first canonical mapping —
+  // builders declare "which plans get this feature" on the feature
+  // itself rather than enumerating features per plan. Required and
+  // non-empty: a feature with no plans grants nothing and is a likely
+  // typo. Cross-reference validation (every key resolves to an
+  // existing plan) lives in `validateFeatureReferences` below.
+  plans: z13.array(z13.string().min(1)).min(1).max(20)
+});
+var featureCatalogSchema = z13.record(z13.string().min(1).max(100).regex(/^[a-z0-9_.:-]+$/), featureCatalogEntrySchema);
+var productSpecSchema = z13.object({
+  product: z13.object({
+    name: z13.string().min(1).max(100),
+    displayName: z13.string().max(200).optional(),
+    description: z13.string().max(2e3).optional(),
+    baseUrl: z13.string().url("baseUrl must be a valid URL"),
+    sandboxBaseUrl: z13.string().url("sandboxBaseUrl must be a valid URL").optional(),
+    visibility: z13.enum(["public", "private"]).default("public"),
+    // Branding
+    logoUrl: z13.string().url().optional(),
+    primaryColor: z13.string().regex(/^#[0-9a-fA-F]{6}$/).optional(),
+    // Environment
+    envBranchPrefix: z13.string().max(50).nullable().optional()
+  }),
+  gateway: z13.object({
+    authHeader: z13.string().min(1).max(100).default("x-api-key"),
+    upstreamAuth: z13.object({
+      type: z13.enum(["none", "static_bearer"]),
+      token: z13.string().optional()
+    }).default({ type: "none" })
+  }),
+  metering: z13.object({
+    meters: z13.array(meterDefinitionSchema).max(10).default([]),
+    billOn4xx: z13.boolean().default(false)
+  }).default({ meters: [], billOn4xx: false }),
+  usage: usageBlockSchema.optional(),
+  usagePricing: z13.never({
+    error: "usagePricing is not supported. Define usage.meters.<key>.rating instead."
+  }).optional(),
+  features: featureCatalogSchema.optional(),
+  resources: countedResourcesSchema,
+  /**
+   * Track B4 — Declarative frontend surface. Product code can declare
+   * template-owned nav/pages composed from known portal components. The
+   * template renders these for non-reserved paths; contractual dashboard
+   * sections remain template-owned.
+   */
+  frontend: frontendManifestSchema.optional(),
+  migrations: migrationDeclsSchema.optional(),
+  // v0.53.0 — `billing.strategy` removed. Plans now declare their own
+  // billing shape via the unified 5-knob spec (`meters`,
+  // `recurring_fee_cents`, `recurring_credit_grant_cents`,
+  // `one_time_credit_grant_cents`, `trial_days`,
+  // `max_monthly_spend_cents`). The product-level `billing` block
+  // retains the transition-policy fields (`gracePeriodDays`,
+  // `subscriberChangePolicy`); the strategy enum is gone.
+  billing: z13.object({
+    gracePeriodDays: z13.number().int().nonnegative().default(3),
+    // When true (default), a plan limit INCREASE re-projects onto active
+    // subscribers immediately; a DECREASE always defers to period end.
+    // Read by migrateActiveSubscribersForRuntimeOnlyChange.
+    applyLimitUpgradesInstantly: z13.boolean().optional(),
+    subscriberChangePolicy: subscriberChangePolicySchema.default({
+      default: "preserve_current_period",
+      proration: "none",
+      when: {
+        price_increase: "preserve_current_period",
+        price_decrease: "switch_immediately",
+        feature_added: "switch_immediately",
+        feature_removed: "preserve_current_period",
+        limit_increased: "switch_immediately",
+        limit_reduced: "preserve_current_period",
+        credit_increased: "switch_immediately",
+        credit_reduced: "preserve_current_period",
+        rating_changed: "preserve_current_period"
+      },
+      allowImmediatePriceIncrease: false,
+      allowImmediateEntitlementReduction: false
+    })
+  }).default({
+    gracePeriodDays: 3,
+    subscriberChangePolicy: {
+      default: "preserve_current_period",
+      proration: "none",
+      when: {
+        price_increase: "preserve_current_period",
+        price_decrease: "switch_immediately",
+        feature_added: "switch_immediately",
+        feature_removed: "preserve_current_period",
+        limit_increased: "switch_immediately",
+        limit_reduced: "preserve_current_period",
+        credit_increased: "switch_immediately",
+        credit_reduced: "preserve_current_period",
+        rating_changed: "preserve_current_period"
+      },
+      allowImmediatePriceIncrease: false,
+      allowImmediateEntitlementReduction: false
+    }
+  }),
+  plans: z13.array(planSpecSchema).max(4).default([]),
+  /**
+   * Add-on catalog (v0.56+). Composable economic + entitlement
+   * overlays that subscribers can pile on top of their base plan.
+   * Map keyed by the AddOn key.
+   *
+   * Compositor (core PR 2a-2) merges (base_plan, [active addons])
+   * → effective entitlement at compile time. Capability limits
+   * combine via MAX (additive); meters merge by dimension;
+   * grants append.
+   *
+   * Example:
+   *   add_ons:
+   *     extra_tokens_50k:
+   *       name: Extra 50k tokens
+   *       recurring_fee_cents: 2000
+   *       grants:
+   *         - kind: recurring
+   *           amount_cents: 2000
+   *     enterprise_sso:
+   *       name: Enterprise SSO
+   *       featureGates:
+   *         sso: true
+   */
+  add_ons: addOnsBlockSchema,
+  /**
+   * Phase 3b — Lifecycle policy. Currently carries breaking-change
+   * governance: the deprecation window and successor-route
+   * requirements that the publish gate enforces when YAML diff
+   * removes a route or otherwise breaks compatibility.
+   *
+   * Absent or empty → no calendar enforcement (today's behavior).
+   * When set, core's `publish-validators` walks the diff and
+   * refuses changes that violate the policy (e.g. a route removal
+   * before the deprecation window has elapsed, or without a
+   * declared successor).
+   *
+   * Example:
+   *   lifecycle:
+   *     breaking_changes:
+   *       require_deprecation_window_days: 90
+   *       require_successor_route: true
+   */
+  lifecycle: z13.object({
+    breaking_changes: z13.object({
+      /** Minimum days a route must have been marked for removal
+       *  (in main-branch YAML) before the publish gate will let
+       *  it actually be removed. Set to 0 to disable. */
+      require_deprecation_window_days: z13.number().int().nonnegative().default(0),
+      /** When true, a route removal must declare a successor
+       *  route via the lifecycle metadata (mechanics in core
+       *  3b-2) before the publish gate accepts it. */
+      require_successor_route: z13.boolean().default(false)
+    }).default({
+      require_deprecation_window_days: 0,
+      require_successor_route: false
+    })
+  }).default({
+    breaking_changes: {
+      require_deprecation_window_days: 0,
+      require_successor_route: false
+    }
+  }),
+  /**
+   * Phase B0 — Platform-as-Backend mode. Optional top-level webhook
+   * subscription block. Compiles into `WebhookEndpoint` rows via the
+   * `emit-webhooks` pass (idempotent upsert, soft-delete on absence).
+   *
+   * Once a product has compiled with a `webhooks` block, API mutations
+   * on those endpoints fail with `409 MANAGED_BY_CODE` — see
+   * `core/src/routes/management-webhooks.ts`. Tie-breaker: product.config.ts
+   * wins over API state if an endpoint id appears in both.
+   */
+  webhooks: webhooksBlockSchema.optional(),
+  /**
+   * Phase B0 — Per-environment overrides. Deep-merges onto the base
+   * spec at compile time, scoped by environment id (resolved from the
+   * pushing branch via `branch-environment-resolver.ts`).
+   *
+   * Out-of-scope: overriding `customerAuthStrategy` is not allowed —
+   * that field stays provisioner-controlled.
+   */
+  environments: environmentsBlockSchema.optional(),
+  /**
+   * Ephemeral-environment behaviour. Production never reads from
+   * here; the fields are only meaningful for env-branch compiles
+   * (env/* branches, validation bot, agent-CI flows). See
+   * `feature/env-flash-model` plan + `docs/yaml-edits.md`.
+   *
+   * `defaultPlan` (OPTIONAL): when set, the bootstrap-key endpoint
+   * (`POST /portal/products/.../test/bootstrap-key`) and the
+   * internal persona-issue endpoint (`POST /internal/personas/
+   * issue`) fall back to this planKey if the caller omits one.
+   * Lets agents in env-CI bootstrap a persona with zero plan-pick
+   * decision. If unset, callers MUST pass `planKey` explicitly
+   * (preserves today's behaviour). Compiler validation pins the
+   * value to a real `plans[].key`.
+   */
+  ephemeral: z13.object({
+    defaultPlan: z13.string().min(1).optional()
+  }).optional()
+}).superRefine((spec, ctx) => {
+  rejectUsagePricing(spec, ctx);
+  validateFreePlans(spec.plans, ctx);
+  validatePaidPlanPrices(spec.plans, ctx);
+  validateMeterReferences(spec, ctx);
+  validateFeatureReferences(spec, ctx);
+  validateRouteMeters(spec, ctx);
+  validateLimitMeterReachability(spec, ctx);
+});
+var productPhaseSchema = z13.object({
+  product: productSpecSchema.shape.product
+});
+var gatewayPhaseSchema = z13.object({
+  gateway: productSpecSchema.shape.gateway
+});
+var meteringPhaseSchema = z13.object({
+  metering: productSpecSchema.shape.metering
+});
+var plansPhaseSchema = z13.object({
+  plans: productSpecSchema.shape.plans
+});
+
+// ../contracts/dist/plans/spec/policy-types.js
+import { z as z14 } from "zod";
+var rateLimitWindowSchema = z14.string().min(2).max(20).regex(/^\d+(ms|s|m|h)$/, "rate_limit window must look like `60s`, `5m`, `1h`");
+var rateLimitConfigSchema = z14.object({
+  strategy: z14.enum(["token_bucket", "sliding_window", "fixed_window"]).default("token_bucket"),
+  /**
+   * Which request dimensions identify the bucket. v0.3.0 supports a
+   * fixed set; extending requires a coordinated gateway/policy-engine
+   * change. The `subscription` dimension is the steady-state default;
+   * `ip` is for unauthenticated probes; `credential` is finer-grained
+   * than subscription (per-key throttling).
+   */
+  dimensions: z14.array(z14.enum(["subscription", "credential", "ip", "route"])).min(1).max(4).default(["subscription"]),
+  limits: z14.array(z14.object({
+    window: rateLimitWindowSchema,
+    max: z14.number().int().positive().max(1e7)
+  })).min(1).max(10),
+  /**
+   * Bounded fail-open behaviour for DO outages. See architecture RFC
+   * "Fail-open guardrails" section. When the policy executor observes
+   * `max_consecutive_failures` DO-call failures within
+   * `max_window_seconds`, it transitions to `degraded_mode` until
+   * `recovery_threshold` consecutive successes restore normal
+   * evaluation.
+   */
+  fail_open: z14.object({
+    max_consecutive_failures: z14.number().int().positive().default(100),
+    max_window_seconds: z14.number().int().positive().default(60),
+    recovery_threshold: z14.number().int().positive().default(50),
+    degraded_mode: z14.enum([
+      "safe_mode_block",
+      "safe_mode_throttle",
+      "runtime_killswitch_trigger"
+    ]).default("safe_mode_throttle")
+  }).default({
+    max_consecutive_failures: 100,
+    max_window_seconds: 60,
+    recovery_threshold: 50,
+    degraded_mode: "safe_mode_throttle"
+  })
+});
+var authConfigSchema = z14.object({
+  header_name: z14.string().min(1).max(100).default("x-api-key"),
+  /**
+   * How the gateway constructs the upstream Authorization header:
+   *   - `none`          → no upstream auth header added
+   *   - `static_bearer` → forward a configured static token
+   *   - `subscriber_jwt` → mint a per-subscriber JWT (out of scope v0.3.0)
+   */
+  upstream_token_source: z14.discriminatedUnion("type", [
+    z14.object({ type: z14.literal("none") }),
+    z14.object({
+      type: z14.literal("static_bearer"),
+      token_secret_ref: z14.string().min(1).max(200).describe("Reference into the secret store (e.g. CF Secret name); not the raw token")
+    })
+  ]).default({ type: "none" }),
+  /**
+   * When `true`, treat the inbound credential's scopes (if any) as
+   * additional gating beyond the entitlement check. v0.3.0 ships with
+   * `strict` as the default.
+   */
+  scope_mode: z14.enum(["strict", "advisory", "off"]).default("strict")
+});
+var concurrencyConfigSchema = z14.object({
+  max_in_flight: z14.number().int().positive().max(1e4),
+  /**
+   * Which dimensions key the lease bucket. Matches the existing
+   * ConcurrencyLease DO `idFromName` pattern (subscription | capability
+   * tuple).
+   */
+  dimensions: z14.array(z14.enum(["subscription", "credential", "capability"])).min(1).max(3).default(["subscription"]),
+  /**
+   * Optional capability scope. When set, the lease bucket is keyed
+   * partly by this capability name — separate buckets per capability.
+   */
+  capability: z14.string().min(1).max(120).optional(),
+  /**
+   * Lease TTL — releases automatically after this many seconds even if
+   * the request never returns (defensive default 30s, mirrors existing
+   * ConcurrencyLease behaviour).
+   */
+  lease_ttl_seconds: z14.number().int().positive().max(600).default(30),
+  fail_open: z14.object({
+    max_consecutive_failures: z14.number().int().positive().default(50),
+    max_window_seconds: z14.number().int().positive().default(60),
+    recovery_threshold: z14.number().int().positive().default(20),
+    degraded_mode: z14.enum([
+      "safe_mode_block",
+      "safe_mode_throttle",
+      "runtime_killswitch_trigger"
+    ]).default("safe_mode_throttle")
+  }).default({
+    max_consecutive_failures: 50,
+    max_window_seconds: 60,
+    recovery_threshold: 20,
+    degraded_mode: "safe_mode_throttle"
+  })
+});
+var retryConfigSchema = z14.object({
+  max_attempts: z14.number().int().min(1).max(5).default(2),
+  /**
+   * HTTP status codes that trigger a retry. 5xx is the default; opt
+   * into 429 retries only when the upstream understands `Retry-After`.
+   */
+  retry_on_status: z14.array(z14.number().int().min(400).max(599)).min(1).max(20).default([502, 503, 504]),
+  /**
+   * Backoff curve. Total wall-clock attempt time is bounded so the
+   * gateway worker cannot block past `total_budget_ms`.
+   */
+  backoff: z14.object({
+    initial_ms: z14.number().int().positive().max(5e3).default(100),
+    multiplier: z14.number().positive().max(10).default(2),
+    jitter: z14.enum(["none", "full", "equal"]).default("equal"),
+    total_budget_ms: z14.number().int().positive().max(3e4).default(5e3)
+  }).default({
+    initial_ms: 100,
+    multiplier: 2,
+    jitter: "equal",
+    total_budget_ms: 5e3
+  })
+});
+var transformConfigSchema = z14.object({
+  /**
+   * When the transform applies. `request` runs before upstream forward;
+   * `response` runs after. Most transforms are one or the other; both
+   * is rare.
+   */
+  applies_to: z14.enum(["request", "response", "both"]).default("request"),
+  /**
+   * List of key rewrites. Source path uses dot notation (`a.b.c`);
+   * `target` may include the same syntax to move keys around. Drops
+   * are expressed as `target: null`.
+   */
+  rewrites: z14.array(z14.object({
+    source: z14.string().min(1).max(200),
+    target: z14.string().min(1).max(200).nullable()
+  })).min(1).max(20)
+});
+var policyBodySchema = z14.discriminatedUnion("type", [
+  z14.object({ type: z14.literal("rate_limit"), config: rateLimitConfigSchema }),
+  z14.object({ type: z14.literal("auth"), config: authConfigSchema }),
+  z14.object({ type: z14.literal("concurrency"), config: concurrencyConfigSchema }),
+  z14.object({ type: z14.literal("retry"), config: retryConfigSchema }),
+  z14.object({ type: z14.literal("transform"), config: transformConfigSchema })
+]);
+
+// ../contracts/dist/plans/spec/policies-layer.js
+import { z as z15 } from "zod";
+var cacheProfileSchema = z15.enum(["long", "short", "blocking"]).default("long");
+var policyCompatibilitySchema = z15.object({
+  route_types: z15.array(z15.enum(["http"])).max(5).optional(),
+  meters: z15.array(z15.string().min(1).max(64)).max(20).optional(),
+  auth_modes: z15.array(z15.enum(["api_key", "oauth2", "anonymous"])).max(5).optional()
+});
+var policyFileSchema = z15.intersection(z15.object({
+  /**
+   * Policy name. Referenced by routes via `policies: [<name>]`. Must
+   * be unique across the product; the compiler enforces this in the
+   * cross-file validation pass.
+   */
+  name: z15.string().min(1).max(64).regex(/^[a-z0-9_-]+$/, "Policy name must be lowercase alphanumeric with hyphens/underscores"),
+  description: z15.string().max(500).optional(),
+  compatible_with: policyCompatibilitySchema.default({}),
+  /**
+   * Mutation class — runtime vs contractual. Policies are operational
+   * by nature so the default is `runtime`. Marking a policy as
+   * `contractual` signals that changes to it require human approval
+   * (invariant #16).
+   */
+  mutation_class: z15.enum(["runtime", "contractual"]).default("runtime"),
+  cacheProfile: cacheProfileSchema
+}), policyBodySchema);
+
+// ../contracts/dist/plans/spec/routes-layer.js
+import { z as z17 } from "zod";
+
+// ../contracts/dist/framework/actions/index.js
+import { z as z16 } from "zod";
+var actionKindSchema = z16.enum(["query", "mutation"]);
+var actionAuditPolicySchema = z16.enum(["none", "metadata", "full"]);
+var actionSubjectBindingSchema = z16.object({
+  type: z16.string().min(1).max(64).regex(/^[a-zA-Z0-9_.:-]+$/),
+  from: z16.enum(["header", "path_param"]),
+  name: z16.string().min(1).max(120)
+});
+var actionResourceEffectSchema = z16.object({
+  resource: z16.string().min(1).max(100).regex(/^[a-z0-9_.:-]+$/),
+  effect: z16.enum(["create", "delete"])
+});
+var actionSpecSchema = z16.object({
+  id: z16.string().min(1).max(160).regex(/^[a-z0-9_.:-]+$/),
+  title: z16.string().min(1).max(160).optional(),
+  kind: actionKindSchema,
+  actorType: z16.string().min(1).max(64).regex(/^[a-zA-Z0-9_.:-]+$/).optional(),
+  subject: actionSubjectBindingSchema.optional(),
+  inputSchemaRef: z16.string().min(1).max(240).optional(),
+  audit: actionAuditPolicySchema.default("metadata"),
+  resource: actionResourceEffectSchema.optional()
+});
+
+// ../contracts/dist/plans/spec/routes-layer.js
+var routeMatchSchema = z17.object({
+  method: z17.enum(["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS", "*"]).default("*"),
+  path: z17.string().min(1).max(500).regex(/^\/[a-zA-Z0-9_/:.{}*-]*$/, "path must start with / and contain only [a-zA-Z0-9_/:.{}*-]")
+});
+var routeDefinitionSchema = z17.object({
+  match: routeMatchSchema,
+  /**
+   * Per-route meter binding. Mirrors the legacy `featureRouteSchema`
+   * semantics:
+   *   - omitted   → route inherits "all configured product meters"
+   *   - non-empty → only these meters increment
+   *   - []        → REJECTED at parse (typo guard)
+   *   - null      → treated as omitted (PATCH-clear UX)
+   */
+  meters: z17.array(z17.string().min(1).max(64)).min(1, "Use `unmetered: true` instead of an empty array (typo guard against silently-unmetered routes)").max(20).nullable().optional(),
+  unmetered: z17.boolean().optional(),
+  /** Optional explicit action id. When absent, the compiler derives an
+   *  implicit action from feature + method + path. */
+  action: z17.string().min(1).max(160).regex(/^[a-z0-9_.:-]+$/).optional()
+}).superRefine((route, ctx) => {
+  if (route.unmetered === true && route.meters && route.meters.length > 0) {
+    ctx.addIssue({
+      code: "custom",
+      message: "`unmetered: true` is mutually exclusive with `meters` \u2014 drop one",
+      path: ["unmetered"]
+    });
+  }
+});
+var routeUpstreamSchema = z17.object({
+  override_origin: z17.string().url("override_origin must be a valid URL").nullable().default(null)
+});
+var routeRuntimeSchema = z17.object({
+  rollout_key: z17.string().min(1).max(120).regex(/^[a-z0-9_-]+$/, "rollout_key must be lowercase alphanumeric with hyphens/underscores").optional(),
+  /**
+   * Optional runtime flags this feature depends on. The runtime
+   * evaluator AND's the feature's enablement across all referenced
+   * flags. If any flag is disabled, the route returns the configured
+   * fallback (404 by default — see /runtime failure matrix).
+   */
+  required_flags: z17.array(z17.string().min(1).max(120).regex(/^[a-z0-9_-]+$/)).max(10).optional()
+});
+var routesFileSchema = z17.object({
+  /**
+   * Feature key — the entitlement unit. Surfaced in dashboards,
+   * subscriptions, and the gateway's matched-route trace.
+   */
+  feature: z17.string().min(1).max(100).regex(/^[a-z0-9_.:-]+$/, "feature key must be lowercase alphanumeric with [_.:-]"),
+  description: z17.string().max(500).optional(),
+  /**
+   * Route additions are contractual by default — they expose new API
+   * surface to subscribers. Internal/non-customer-visible routes can
+   * mark themselves `runtime` to allow autonomous agent flips
+   * (invariant #16; see RFC approval matrix).
+   */
+  mutation_class: z17.enum(["runtime", "contractual"]).default("contractual"),
+  cacheProfile: cacheProfileSchema,
+  routes: z17.array(routeDefinitionSchema).min(1).max(50),
+  upstream: routeUpstreamSchema.default({ override_origin: null }),
+  /**
+   * Ordered list of policy names to apply. Executed sequentially by
+   * the gateway policy engine; first-deny wins. Referenced policies
+   * MUST declare compatible `compatible_with` envelopes for this
+   * feature's route/meter shape — the compiler enforces.
+   */
+  policies: z17.array(z17.string().min(1).max(64).regex(/^[a-z0-9_-]+$/)).max(20).default([]),
+  runtime: routeRuntimeSchema.default({}),
+  /**
+   * Capability groups this feature joins. A plan that includes any
+   * referenced capability grants this feature. Capabilities are
+   * resolved at compile time into the plan's expanded feature set.
+   */
+  capabilities: z17.array(z17.string().min(1).max(120).regex(/^[a-z0-9_-]+$/)).max(20).default([]),
+  /**
+   * Plans that grant this feature directly (in addition to capability
+   * membership). Mirrors the legacy `featureCatalogEntrySchema.plans`
+   * field for the common case where the feature isn't part of any
+   * shared capability group.
+   *
+   * v0.3.0 keeps direct-plan binding for migration ergonomics; v0.4
+   * may deprecate this in favour of capability-only composition.
+   */
+  plans: z17.array(z17.string().min(1).max(64)).max(20).default([]),
+  /** Explicit actions declared by this feature. Routes reference them by
+   *  `route.action`; routes without a binding receive implicit actions. */
+  actions: z17.array(actionSpecSchema).max(100).optional()
+});
+
+// ../contracts/dist/plans/spec/runtime-layer.js
+import { z as z18 } from "zod";
+var keyNameSchema = z18.string().min(1).max(120).regex(/^[a-z0-9_-]+$/, "runtime key must be lowercase alphanumeric with hyphens/underscores");
+var dependsOnSchema = z18.object({
+  runtime_flags: z18.array(keyNameSchema).max(10).optional(),
+  capabilities: z18.array(z18.string().min(1).max(120).regex(/^[a-z0-9_-]+$/)).max(10).optional()
+}).default({});
+var audienceSchema = z18.object({
+  plans: z18.array(z18.string().min(1).max(64)).max(20).optional(),
+  environments: z18.array(z18.string().min(1).max(64)).max(10).optional(),
+  capabilities: z18.array(z18.string().min(1).max(120).regex(/^[a-z0-9_-]+$/)).max(10).optional()
+}).default({});
+var rolloutDefaultsSchema = z18.object({
+  missing_behavior: z18.enum(["treat_as_zero_percent", "treat_as_full_rollout", "fail_closed"]).default("treat_as_zero_percent"),
+  stale_behavior: z18.enum(["use_last_known", "fail_closed_on_signature"]).default("use_last_known")
+});
+var rolloutEntrySchema = z18.object({
+  description: z18.string().max(500).optional(),
+  audience: audienceSchema,
+  /**
+   * Rollout percentage (0-100). 0 = no subscribers in treatment;
+   * 100 = full rollout. Cohort stability invariant #20: increasing
+   * the percent admits more subscribers (existing stay); decreasing
+   * drops subscribers whose deterministic bucket is above the new
+   * boundary (logged as an audit event).
+   */
+  percent: z18.number().int().min(0).max(100),
+  /**
+   * Seed for the deterministic SHA-256 hash that computes bucket
+   * assignment. Rotating the seed is a destructive rebucketing
+   * operation; the workflow runner refuses without approval metadata
+   * (invariant #16).
+   */
+  assignment_seed: z18.string().min(1).max(120).default("default"),
+  depends_on: dependsOnSchema,
+  defaults: rolloutDefaultsSchema.default({
+    missing_behavior: "treat_as_zero_percent",
+    stale_behavior: "use_last_known"
+  })
+});
+var runtimeRolloutFileSchema = z18.object({
+  cacheProfile: cacheProfileSchema.default("blocking"),
+  rollouts: z18.record(keyNameSchema, rolloutEntrySchema).default({})
+});
+var flagDefaultsSchema = z18.object({
+  missing_behavior: z18.enum(["disabled", "enabled", "fail_closed"]).default("disabled"),
+  stale_behavior: z18.enum(["use_last_known", "fail_closed_on_signature"]).default("use_last_known")
+});
+var flagEntrySchema = z18.object({
+  description: z18.string().max(500).optional(),
+  enabled: z18.boolean(),
+  audience: audienceSchema,
+  depends_on: dependsOnSchema,
+  defaults: flagDefaultsSchema.default({
+    missing_behavior: "disabled",
+    stale_behavior: "use_last_known"
+  }),
+  /**
+   * When set, this flag acts as a killswitch — its `enabled: true`
+   * disables traffic for the referenced subjects. Useful for
+   * incident response (`policy_premium-rate-limit_emergency_off`).
+   */
+  killswitch_target: z18.object({
+    kind: z18.enum(["policy", "route", "rollout"]),
+    name: z18.string().min(1).max(120).regex(/^[a-z0-9_-]+$/)
+  }).optional()
+});
+var runtimeFlagsFileSchema = z18.object({
+  cacheProfile: cacheProfileSchema.default("blocking"),
+  flags: z18.record(keyNameSchema, flagEntrySchema).default({})
+});
+var migrationDefaultsSchema = z18.object({
+  missing_behavior: z18.enum(["disabled", "pending_review"]).default("disabled"),
+  stale_behavior: z18.enum(["use_last_known", "fail_closed_on_signature"]).default("use_last_known")
+});
+var migrationTriggerSchema = z18.object({
+  description: z18.string().max(500).optional(),
+  /**
+   * The (fromPlanKey, toPlanKey) migration this trigger configures.
+   * Compiler validates both keys resolve.
+   */
+  from_plan_key: z18.string().min(1).max(64),
+  to_plan_key: z18.string().min(1).max(64),
+  policy: z18.enum([
+    "GRANDFATHER",
+    "MIGRATE_AT_RENEWAL",
+    "MIGRATE_IMMEDIATELY",
+    "MIGRATE_BY_DATE",
+    "OPT_IN"
+  ]).default("MIGRATE_AT_RENEWAL"),
+  proration_policy: z18.enum(["NONE", "PRORATE", "CREDIT"]).default("NONE"),
+  /**
+   * Wall-clock cutover for `MIGRATE_BY_DATE` policy. Ignored for other
+   * policies. Must be in the future at compile time.
+   */
+  cutover_at: z18.string().datetime().optional(),
+  /**
+   * Freeze window per invariant #8 — while this migration is RUNNING,
+   * contractual mutations to the product are rejected at the webhook
+   * layer with 423 LOCKED. Set to `false` to allow concurrent
+   * contract edits (only for migrations that don't touch entitlement
+   * shape — e.g. pure price corrections).
+   */
+  freeze_contract_mutations: z18.boolean().default(true),
+  depends_on: dependsOnSchema,
+  defaults: migrationDefaultsSchema.default({
+    missing_behavior: "disabled",
+    stale_behavior: "use_last_known"
+  })
+});
+var runtimeMigrationsFileSchema = z18.object({
+  cacheProfile: cacheProfileSchema.default("blocking"),
+  migrations: z18.record(keyNameSchema, migrationTriggerSchema).default({})
+});
+
+// ../contracts/dist/plans/spec/capabilities-layer.js
+import { z as z19 } from "zod";
+var capabilityFileSchema = z19.object({
+  capability: z19.string().min(1).max(120).regex(/^[a-z0-9_-]+$/, "capability name must be lowercase alphanumeric with hyphens/underscores"),
+  description: z19.string().max(500).optional(),
+  /**
+   * Capability composition is contractual by default — including a new
+   * feature changes the customer's effective entitlement. Mark
+   * `runtime` only for capabilities that compose runtime-only knobs
+   * (e.g. an internal "monitoring" capability that gates dashboard
+   * pages without affecting billable behaviour).
+   */
+  mutation_class: z19.enum(["runtime", "contractual"]).default("contractual"),
+  includes_features: z19.array(z19.string().min(1).max(100).regex(/^[a-z0-9_.:-]+$/)).max(20).default([]),
+  includes_policies: z19.array(z19.string().min(1).max(64).regex(/^[a-z0-9_-]+$/)).max(20).default([]),
+  includes_capabilities: z19.array(z19.string().min(1).max(120).regex(/^[a-z0-9_-]+$/)).max(20).default([])
+});
+
+// ../contracts/dist/plans/spec/product-v2.js
+import { z as z20 } from "zod";
+var PRODUCT_V2_SCHEMA_VERSION = 1;
+var billingKnobsShape2 = {
+  meters: z20.array(meterSchema).default([]),
+  recurring_fee_cents: z20.number().int().nonnegative().default(0),
+  /** Billing cadence (`month` default / `year`). Drives the Stripe price
+   *  `recurring.interval` and the entitlement billing-period window. */
+  billing_interval: billingIntervalSchema.default("month"),
+  trial_days: z20.number().int().nonnegative().default(0),
+  max_monthly_spend_cents: z20.number().int().nonnegative().optional(),
+  min_monthly_spend_cents: z20.number().int().nonnegative().optional(),
+  // Unified grants array — the SINGLE credit surface. Recurring +
+  // one-time credit are canonical entries here (the legacy scalar knobs
+  // were removed).
+  grants: z20.array(grantSchema).max(40).default([])
+};
+var planSpecV2Schema = z20.object({
+  key: z20.string().min(1).max(64).regex(/^[a-z0-9_-]+$/, "Plan key must be lowercase alphanumeric with hyphens/underscores"),
+  name: z20.string().min(1).max(100),
+  description: z20.string().max(500).optional(),
+  details: z20.array(z20.string().max(200)).max(10).optional(),
+  ...billingKnobsShape2,
+  free: z20.boolean().default(false),
+  /**
+   * Capability composition references. The compiler's
+   * `resolve-capabilities` pass walks the graph and expands this into
+   * concrete (features, policies) sets stored on the CompiledPlan.
+   *
+   * Replaces the legacy `featureGates` block (which is now expressed
+   * via capability composition) and the per-plan inverse feature
+   * mapping (`featureCatalogEntry.plans[]`).
+   *
+   * A plan may reference zero capabilities — useful for free / starter
+   * plans that grant access only via direct route bindings.
+   */
+  capabilities: z20.array(z20.string().min(1).max(120).regex(/^[a-z0-9_-]+$/)).max(20).default([]),
+  limits: z20.array(planLimitRuleSchema).max(20).default([]),
+  /**
+   * Control-plane capability caps (count limits + boolean toggles).
+   * Same semantics as the legacy `capability_limits` field.
+   */
+  capability_limits: z20.record(z20.string().min(1).max(120), z20.union([z20.number().int().nonnegative(), z20.boolean()])).default({}),
+  overageBehavior: z20.enum(["block", "allow_and_bill"]).default("block"),
+  selfServeEnabled: z20.boolean().default(true),
+  /**
+   * Marks a plan as the pinned-cohort head (status LEGACY_STABLE). Only
+   * existing subscribers stay on legacy plans; new subscribers cannot
+   * join. Removing a legacy plan while subscribers are pinned is a
+   * compile error.
+   */
+  legacy: z20.boolean().optional().default(false),
+  archive: z20.object({
+    at: z20.string().datetime().optional(),
+    transitionTo: z20.string().optional(),
+    strategy: z20.enum(["auto", "explicit", "block"]).default("auto")
+  }).optional()
+}).superRefine((plan, ctx) => {
+  refineSingleCanonicalGrant(plan.grants, ctx);
+});
+var DEFAULT_SUBSCRIBER_CHANGE_POLICY = {
+  default: "preserve_current_period",
+  proration: "none",
+  when: {
+    price_increase: "preserve_current_period",
+    price_decrease: "switch_immediately",
+    feature_added: "switch_immediately",
+    feature_removed: "preserve_current_period",
+    limit_increased: "switch_immediately",
+    limit_reduced: "preserve_current_period",
+    credit_increased: "switch_immediately",
+    credit_reduced: "preserve_current_period",
+    rating_changed: "preserve_current_period"
+  },
+  allowImmediatePriceIncrease: false,
+  allowImmediateEntitlementReduction: false
+};
+var productSpecV2Schema = z20.object({
+  /**
+   * Schema-version stamp. Forward migrations target a higher value;
+   * readers refuse unsupported versions per invariant #2.
+   */
+  artifactSchemaVersion: z20.literal(PRODUCT_V2_SCHEMA_VERSION).default(PRODUCT_V2_SCHEMA_VERSION),
+  product: z20.object({
+    name: z20.string().min(1).max(100),
+    displayName: z20.string().max(200).optional(),
+    description: z20.string().max(2e3).optional(),
+    baseUrl: z20.string().url("baseUrl must be a valid URL"),
+    sandboxBaseUrl: z20.string().url("sandboxBaseUrl must be a valid URL").optional(),
+    visibility: z20.enum(["public", "private"]).default("public"),
+    logoUrl: z20.string().url().optional(),
+    primaryColor: z20.string().regex(/^#[0-9a-fA-F]{6}$/).optional(),
+    envBranchPrefix: z20.string().max(50).nullable().optional()
+  }),
+  /**
+   * Meter catalog. Referenced by /routes/*.yaml via `meters: [...]`.
+   * Same shape as the legacy meterDefinitionSchema (re-exported from
+   * product.ts to keep one source of truth during the transition).
+   *
+   * Lifted to a top-level array so the compiler can hash + invalidate
+   * meter changes independently from plan changes (incremental
+   * compilation per invariant #1 + Merkle DAG).
+   */
+  meters: z20.array(meterDefinitionSchema).max(10).default([]),
+  /**
+   * Bill on 4xx responses (independent of meter setup). Stays on the
+   * product spec because it's a contractual choice that affects
+   * billing predictability.
+   */
+  billOn4xx: z20.boolean().default(false),
+  frontend: frontendManifestSchema.optional(),
+  migrations: migrationDeclsSchema.optional(),
+  resources: countedResourcesSchema,
+  billing: z20.object({
+    gracePeriodDays: z20.number().int().nonnegative().default(3),
+    // When true (default), a plan limit INCREASE re-projects onto active
+    // subscribers immediately; a DECREASE always defers to period end.
+    // Read by migrateActiveSubscribersForRuntimeOnlyChange.
+    applyLimitUpgradesInstantly: z20.boolean().optional(),
+    subscriberChangePolicy: subscriberChangePolicySchema.default(DEFAULT_SUBSCRIBER_CHANGE_POLICY)
+  }).default({
+    gracePeriodDays: 3,
+    subscriberChangePolicy: DEFAULT_SUBSCRIBER_CHANGE_POLICY
+  }),
+  plans: z20.array(planSpecV2Schema).max(4).default([]),
+  add_ons: addOnsBlockSchema,
+  lifecycle: z20.object({
+    breaking_changes: z20.object({
+      require_deprecation_window_days: z20.number().int().nonnegative().default(0),
+      require_successor_route: z20.boolean().default(false)
+    }).default({
+      require_deprecation_window_days: 0,
+      require_successor_route: false
+    })
+  }).default({
+    breaking_changes: {
+      require_deprecation_window_days: 0,
+      require_successor_route: false
+    }
+  }),
+  webhooks: webhooksBlockSchema.optional(),
+  environments: environmentsBlockSchema.optional(),
+  ephemeral: z20.object({
+    defaultPlan: z20.string().min(1).optional()
+  }).optional()
+});
+
+// ../contracts/dist/plans/spec/manifest-ir.js
+import { createHash } from "node:crypto";
+import { z as z21 } from "zod";
+var MANIFEST_IR_VERSION = 1;
+var manifestIrSchema = z21.object({
+  irVersion: z21.literal(MANIFEST_IR_VERSION),
+  /** Version of @farthershore/product that emitted this envelope. */
+  sdkVersion: z21.string().min(1).max(64),
+  /** Legacy unified ProductSpec — the live `CompileProductOptions.sourceSpec`. */
+  product: productSpecSchema,
+  /** One entry per feature, sorted by `feature` (mirrors /routes/<feature>.yaml). */
+  routes: z21.array(routesFileSchema).max(200).default([]),
+  /** Sorted by `name` (mirrors /policies/<name>.yaml). */
+  policies: z21.array(policyFileSchema).max(200).default([]),
+  /** Sorted by `capability` (mirrors /capabilities/<name>.yaml). */
+  capabilities: z21.array(capabilityFileSchema).max(200).default([]),
+  /** Reserved. Always null at irVersion 1 — runtime stays YAML/dashboard. */
+  runtime: z21.object({
+    rollout: z21.null().default(null),
+    flags: z21.null().default(null),
+    migrations: z21.null().default(null)
+  }).default({ rollout: null, flags: null, migrations: null })
+});
+function canonicalManifestJson(value) {
+  return stableJson(JSON.parse(JSON.stringify(value)));
+}
+function hashManifestIr(ir) {
+  return createHash("sha256").update(canonicalManifestJson(ir)).digest("hex");
+}
+function stableJson(value) {
+  if (Array.isArray(value))
+    return `[${value.map(stableJson).join(",")}]`;
+  if (value && typeof value === "object") {
+    return `{${Object.entries(value).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([key, val]) => `${JSON.stringify(key)}:${stableJson(val)}`).join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+
+// ../contracts/dist/plans/presets.js
+var FREE = {
+  kind: "free",
+  label: "Free",
+  description: "No recurring fee and no metered usage. Pure freemium tier.",
+  pricing: {
+    meters: [],
+    recurring_fee_cents: 0,
+    billing_interval: "month",
+    grants: [],
+    trial_days: 0
+  }
+};
+var STARTER = {
+  kind: "starter",
+  label: "Starter \u2014 $20/mo + $20 included",
+  description: "$20/month subscription with $20 of usage credit each period. Stripe-style minimum-spend; overage billed at $0.001/request by default.",
+  pricing: {
+    meters: [
+      { dimension: "requests", kind: "linear", price_per_unit_micros: 1e3 }
+    ],
+    recurring_fee_cents: 2e3,
+    billing_interval: "month",
+    grants: [{ kind: "recurring", amount_cents: 2e3 }],
+    trial_days: 0
+  }
+};
+var PRO = {
+  kind: "pro",
+  label: "Pro \u2014 $100/mo + $200 included",
+  description: "$100/month subscription with $200 of usage credit each period and a 14-day trial. Overage billed at $0.0005/request by default.",
+  pricing: {
+    meters: [
+      { dimension: "requests", kind: "linear", price_per_unit_micros: 500 }
+    ],
+    recurring_fee_cents: 1e4,
+    billing_interval: "month",
+    grants: [{ kind: "recurring", amount_cents: 2e4 }],
+    trial_days: 14
+  }
+};
+var PREPAID = {
+  kind: "prepaid",
+  label: "Prepaid \u2014 $50 sign-up credit, then PAYG",
+  description: "$50 one-time credit at signup. Once depleted the subscriber pays-as-they-go at $0.001/request by default.",
+  pricing: {
+    meters: [
+      { dimension: "requests", kind: "linear", price_per_unit_micros: 1e3 }
+    ],
+    recurring_fee_cents: 0,
+    billing_interval: "month",
+    grants: [{ kind: "one_time", amount_cents: 5e3 }],
+    trial_days: 0
+  }
+};
+var METERED = {
+  kind: "metered",
+  label: "Metered (pay-as-you-go)",
+  description: "No subscription fee. Pure usage billing at $0.001/request by default.",
+  pricing: {
+    meters: [
+      { dimension: "requests", kind: "linear", price_per_unit_micros: 1e3 }
+    ],
+    recurring_fee_cents: 0,
+    billing_interval: "month",
+    grants: [],
+    trial_days: 0
+  }
+};
+var PLAN_PRESETS = Object.freeze({
+  free: FREE,
+  starter: STARTER,
+  pro: PRO,
+  prepaid: PREPAID,
+  metered: METERED
+});
+
+// ../contracts/dist/plans/subscription-pricing-override.js
+import { z as z22 } from "zod";
+var subscriptionPricingOverrideSchema = z22.object({
+  /** Override the plan's recurring fee for this subscriber. */
+  recurring_fee_cents: z22.number().int().nonnegative().optional(),
+  /**
+   * Override the plan's credit grants. `grants[]` is the single credit
+   * surface — when present, it fully replaces the plan's grants for this
+   * subscriber (recurring + one-time credit are canonical entries here;
+   * the legacy recurring/one-time scalar knobs were removed).
+   */
+  grants: z22.array(grantSchema).max(40).optional(),
+  /** Override the minimum-spend floor. */
+  min_monthly_spend_cents: z22.number().int().nonnegative().optional(),
+  /** Override the maximum-spend ceiling. */
+  max_monthly_spend_cents: z22.number().int().nonnegative().optional(),
+  /** Replace the entire meter list for this subscriber. When set, the
+   *  full plan meter array is replaced (not merged) — call it explicit
+   *  rather than implicit so a deal can also REMOVE billable meters,
+   *  not just adjust rates. */
+  meters: z22.array(meterSchema).optional(),
+  /** Free-text notes about the deal. Surfaced in admin UI for audit. */
+  notes: z22.string().max(2e3).optional()
+});
+
+// src/validate.ts
+function validateManifestIr(candidate) {
+  const parsed = manifestIrSchema.safeParse(candidate);
+  if (!parsed.success) {
+    return {
+      ok: false,
+      issues: parsed.error.issues.map((issue) => ({
+        code: issue.code.toUpperCase(),
+        path: issue.path.map(String).join("."),
+        message: issue.message
+      }))
+    };
+  }
+  const ir = JSON.parse(
+    JSON.stringify(candidate)
+  );
+  return { ok: true, ir, irHash: hashIr(ir) };
+}
+function hashIr(ir) {
+  return hashManifestIr(ir);
+}
+
+// src/version.ts
+var SDK_VERSION = true ? "0.0.0" : "0.0.0-dev";
+
+// src/business.ts
+var BUSINESS_BRAND = Symbol.for("farthershore.product.business");
+function isCapabilityGrant(value) {
+  return typeof value === "object" && value !== null && value.kind === "capability_grant";
+}
+function keyOf(ref) {
+  return typeof ref === "string" ? ref : ref.key;
+}
+function parseRouteMatch(match) {
+  const trimmed = match.trim();
+  const space = trimmed.indexOf(" ");
+  if (space === -1) {
+    if (!trimmed.startsWith("/")) {
+      throw new ManifestBuilderError(
+        `route "${match}": expected "METHOD /path" or "/path"`
+      );
+    }
+    return { method: "*", path: trimmed };
+  }
+  const method = trimmed.slice(0, space).toUpperCase();
+  const path = trimmed.slice(space + 1).trim();
+  const methods = [
+    "GET",
+    "POST",
+    "PUT",
+    "PATCH",
+    "DELETE",
+    "HEAD",
+    "OPTIONS",
+    "*"
+  ];
+  if (!methods.includes(method)) {
+    throw new ManifestBuilderError(
+      `route "${match}": unknown HTTP method "${method}"`
+    );
+  }
+  if (!path.startsWith("/")) {
+    throw new ManifestBuilderError(
+      `route "${match}": path must start with "/"`
+    );
+  }
+  return { method, path };
+}
+var Business = class {
+  [BUSINESS_BRAND] = true;
+  name;
+  options;
+  meters = /* @__PURE__ */ new Map();
+  resources = /* @__PURE__ */ new Map();
+  plans = /* @__PURE__ */ new Map();
+  features = /* @__PURE__ */ new Map();
+  policies = /* @__PURE__ */ new Map();
+  capabilities = /* @__PURE__ */ new Map();
+  migrations = [];
+  frontendManifest;
+  productPatch = {};
+  /** Sugar for binding API routes to features. */
+  api;
+  frontend;
+  lifecycle;
+  /** Escape hatches — raw platform-schema JSON, validated at toIR(). */
+  raw;
+  constructor(name, options) {
+    if (!name || typeof name !== "string") {
+      throw new ManifestBuilderError("fs.business(name, \u2026): name is required");
+    }
+    if (!options?.baseUrl) {
+      throw new ManifestBuilderError(
+        `fs.business("${name}", \u2026): options.baseUrl is required (the upstream origin the gateway proxies to)`
+      );
+    }
+    this.name = name;
+    this.options = options;
+    this.api = {
+      route: (match, options2) => {
+        const featureKey = keyOf(options2.feature);
+        const file = this.features.get(featureKey);
+        if (!file) {
+          throw new ManifestBuilderError(
+            `api.route("${match}"): feature "${featureKey}" is not declared \u2014 call business.feature("${featureKey}", \u2026) first`
+          );
+        }
+        file.routes.push(this.buildRoute(match, options2));
+        return this;
+      }
+    };
+    this.frontend = {
+      nav: (items) => {
+        const manifest = this.ensureFrontendManifest();
+        manifest.nav = items.map((item) => ({
+          label: item.label,
+          path: item.path,
+          ...item.capability !== void 0 ? { capability: keyOf(item.capability) } : {}
+        }));
+        return this;
+      },
+      page: (path, options2) => {
+        const manifest = this.ensureFrontendManifest();
+        if (manifest.pages?.some((page) => page.path === path)) {
+          throw new ManifestBuilderError(
+            `duplicate frontend page "${path}" \u2014 each frontend page path must be declared once`
+          );
+        }
+        manifest.pages ??= [];
+        manifest.pages.push({
+          path,
+          title: options2.title,
+          requiresAuth: options2.requiresAuth,
+          ...options2.capability !== void 0 ? { capability: keyOf(options2.capability) } : {},
+          ...options2.components?.length ? {
+            components: options2.components.map((component) => ({
+              component: component.component,
+              ...component.props !== void 0 ? { props: component.props } : {},
+              ...component.capability !== void 0 ? { capability: keyOf(component.capability) } : {},
+              ...component.gateMode !== void 0 ? { gateMode: component.gateMode } : {}
+            }))
+          } : {}
+        });
+        return this;
+      },
+      manifest: (manifest) => {
+        this.frontendManifest = manifest;
+        return this;
+      }
+    };
+    this.lifecycle = {
+      migration: (id, options2) => {
+        this.assertUniqueMigrationId(id);
+        this.migrations.push({
+          id,
+          from: this.normalizeMigrationPlanRef(options2.from),
+          to: this.normalizeMigrationTargetRef(options2.to),
+          newCustomers: options2.newCustomers ?? "immediate",
+          existingCustomers: options2.existingCustomers,
+          ...options2.pins?.length ? {
+            pins: options2.pins.map((pin) => ({
+              subscriber: pin.subscriber,
+              pinTo: {
+                plan: keyOf(pin.pinTo.plan),
+                version: pin.pinTo.version
+              },
+              ...pin.until !== void 0 ? { until: pin.until } : {},
+              ...pin.notes !== void 0 ? { notes: pin.notes } : {}
+            }))
+          } : {}
+        });
+        return this;
+      },
+      migrations: (migrations) => {
+        this.assertUniqueMigrationIds(migrations);
+        this.migrations = migrations;
+        return this;
+      }
+    };
+    this.raw = {
+      productPatch: (patch) => {
+        this.productPatch = deepMerge(this.productPatch, patch);
+        return this;
+      },
+      plan: (spec) => {
+        this.assertNewKey(this.plans, spec.key, "plan");
+        this.plans.set(spec.key, spec);
+        return this;
+      },
+      routesFile: (file) => {
+        this.assertNewKey(this.features, file.feature, "feature");
+        this.features.set(file.feature, file);
+        return this;
+      },
+      policyFile: (file) => {
+        this.assertNewKey(this.policies, file.name, "policy");
+        this.policies.set(file.name, file);
+        return this;
+      },
+      capabilityFile: (file) => {
+        this.assertNewKey(this.capabilities, file.capability, "capability");
+        this.capabilities.set(file.capability, file);
+        return this;
+      },
+      frontend: (manifest) => {
+        this.frontendManifest = manifest;
+        return this;
+      }
+    };
+  }
+  meter(key, options) {
+    this.assertNewKey(this.meters, key, "meter");
+    this.meters.set(key, { key, ...options });
+    return { kind: "meter", key };
+  }
+  resource(name, options = {}) {
+    this.assertNewKey(this.resources, name, "resource");
+    this.resources.set(name, { name, ...options });
+    return { kind: "resource", key: name };
+  }
+  capability(key, options = {}) {
+    this.assertNewKey(this.capabilities, key, "capability");
+    const file = {
+      capability: key,
+      ...options.description !== void 0 || options.title !== void 0 ? { description: options.description ?? options.title } : {},
+      ...options.mutationClass !== void 0 ? { mutation_class: options.mutationClass } : {},
+      ...options.includesFeatures?.length ? { includes_features: options.includesFeatures.map(keyOf) } : {},
+      ...options.includesPolicies?.length ? { includes_policies: options.includesPolicies.map(keyOf) } : {},
+      ...options.includesCapabilities?.length ? { includes_capabilities: options.includesCapabilities.map(keyOf) } : {}
+    };
+    this.capabilities.set(key, file);
+    return {
+      kind: "capability",
+      key,
+      enable: (enableOptions) => ({
+        kind: "capability_grant",
+        capability: key,
+        ...enableOptions?.limits ? { limits: enableOptions.limits } : {}
+      })
+    };
+  }
+  feature(key, options = {}) {
+    this.assertNewKey(this.features, key, "feature");
+    const file = {
+      feature: key,
+      routes: [],
+      ...options.description !== void 0 ? { description: options.description } : {},
+      ...options.mutationClass !== void 0 ? { mutation_class: options.mutationClass } : {},
+      ...options.cacheProfile !== void 0 ? { cacheProfile: options.cacheProfile } : {},
+      ...options.upstreamOrigin !== void 0 ? { upstream: { override_origin: options.upstreamOrigin } } : {},
+      ...options.policies?.length ? { policies: options.policies.map(keyOf) } : {},
+      ...options.capabilities?.length ? { capabilities: options.capabilities.map(keyOf) } : {},
+      ...options.plans?.length ? { plans: options.plans.map(keyOf) } : {},
+      ...options.actions?.length ? {
+        actions: options.actions.map(({ id, ...action }) => ({
+          id,
+          ...action
+        }))
+      } : {},
+      ...options.rolloutKey !== void 0 || options.requiredFlags?.length ? {
+        runtime: {
+          ...options.rolloutKey !== void 0 ? { rollout_key: options.rolloutKey } : {},
+          ...options.requiredFlags?.length ? { required_flags: options.requiredFlags } : {}
+        }
+      } : {}
+    };
+    for (const route of options.routes ?? []) {
+      file.routes.push(this.buildRoute(route.match, route));
+    }
+    this.features.set(key, file);
+    const ref = {
+      kind: "feature",
+      key,
+      action: (id, actionOptions) => {
+        file.actions ??= [];
+        if (file.actions.some((action) => action.id === id)) {
+          throw new ManifestBuilderError(
+            `duplicate action "${id}" \u2014 each action id must be declared once`
+          );
+        }
+        file.actions.push({ id, ...actionOptions });
+        return { kind: "action", key: id };
+      },
+      route: (match, routeOptions) => {
+        file.routes.push(this.buildRoute(match, routeOptions ?? {}));
+        return ref;
+      }
+    };
+    return ref;
+  }
+  policy(name, options) {
+    this.assertNewKey(this.policies, name, "policy");
+    this.policies.set(name, {
+      name,
+      type: options.type,
+      config: options.config,
+      ...options.description !== void 0 ? { description: options.description } : {},
+      ...options.mutationClass !== void 0 ? { mutation_class: options.mutationClass } : {},
+      ...options.cacheProfile !== void 0 ? { cacheProfile: options.cacheProfile } : {},
+      ...options.compatibleWith ? {
+        compatible_with: {
+          ...options.compatibleWith.routeTypes ? { route_types: options.compatibleWith.routeTypes } : {},
+          ...options.compatibleWith.meters ? { meters: options.compatibleWith.meters.map(keyOf) } : {},
+          ...options.compatibleWith.authModes ? { auth_modes: options.compatibleWith.authModes } : {}
+        }
+      } : {}
+    });
+    return { kind: "policy", key: name };
+  }
+  plan(key, options) {
+    this.assertNewKey(this.plans, key, "plan");
+    const capabilityKeys = (options.capabilities ?? []).map(keyOf);
+    const capabilityLimits = {
+      ...options.capabilityLimits ?? {}
+    };
+    const creditGrants = [];
+    for (const grant of options.grants ?? []) {
+      if (isCapabilityGrant(grant)) {
+        if (!capabilityKeys.includes(grant.capability)) {
+          capabilityKeys.push(grant.capability);
+        }
+        Object.assign(capabilityLimits, grant.limits ?? {});
+      } else {
+        creditGrants.push(grant);
+      }
+    }
+    const spec = {
+      key,
+      name: options.name,
+      ...options.description !== void 0 ? { description: options.description } : {},
+      ...options.details ? { details: options.details } : {},
+      ...options.price ? {
+        recurring_fee_cents: options.price.recurring_fee_cents,
+        billing_interval: options.price.billing_interval,
+        ...options.price.free ? { free: true } : {}
+      } : {},
+      ...options.meters ? { meters: options.meters } : {},
+      ...creditGrants.length ? { grants: creditGrants } : {},
+      ...options.trialDays !== void 0 ? { trial_days: options.trialDays } : {},
+      ...options.maxMonthlySpendCents !== void 0 ? { max_monthly_spend_cents: options.maxMonthlySpendCents } : {},
+      ...options.minMonthlySpendCents !== void 0 ? { min_monthly_spend_cents: options.minMonthlySpendCents } : {},
+      ...options.limits ? { limits: options.limits } : {},
+      ...options.featureGates ? { featureGates: options.featureGates } : {},
+      ...Object.keys(capabilityLimits).length ? { capability_limits: capabilityLimits } : {},
+      ...options.overageBehavior !== void 0 ? { overageBehavior: options.overageBehavior } : {},
+      ...options.selfServeEnabled !== void 0 ? { selfServeEnabled: options.selfServeEnabled } : {},
+      ...options.legacy !== void 0 ? { legacy: options.legacy } : {},
+      ...options.archive ? { archive: options.archive } : {},
+      ...options.raw ?? {}
+    };
+    const rawCaps = Array.isArray(
+      spec.capabilities
+    ) ? spec.capabilities.map(
+      String
+    ) : [];
+    const mergedCaps = [.../* @__PURE__ */ new Set([...capabilityKeys, ...rawCaps])];
+    if (mergedCaps.length) {
+      spec.capabilities = mergedCaps;
+    }
+    this.plans.set(key, spec);
+    return { kind: "plan", key };
+  }
+  /** Assemble + validate the Manifest IR. Throws ManifestValidationError
+   *  with structured issues when the declared state is invalid. */
+  toIR() {
+    const candidate = {
+      irVersion: 1,
+      sdkVersion: SDK_VERSION,
+      product: this.buildProductSpec(),
+      routes: sortBy([...this.features.values()], (file) => file.feature),
+      policies: sortBy([...this.policies.values()], (file) => file.name),
+      capabilities: sortBy(
+        [...this.capabilities.values()],
+        (file) => file.capability
+      ),
+      runtime: { rollout: null, flags: null, migrations: null }
+    };
+    const result = validateManifestIr(candidate);
+    if (!result.ok) throw new ManifestValidationError(result.issues);
+    return { ir: result.ir, irHash: result.irHash };
+  }
+  buildProductSpec() {
+    const options = this.options;
+    const base = {
+      product: {
+        name: this.name,
+        baseUrl: options.baseUrl,
+        ...options.displayName !== void 0 ? { displayName: options.displayName } : {},
+        ...options.description !== void 0 ? { description: options.description } : {},
+        ...options.sandboxBaseUrl !== void 0 ? { sandboxBaseUrl: options.sandboxBaseUrl } : {},
+        ...options.visibility !== void 0 ? { visibility: options.visibility } : {},
+        ...options.logoUrl !== void 0 ? { logoUrl: options.logoUrl } : {},
+        ...options.primaryColor !== void 0 ? { primaryColor: options.primaryColor } : {},
+        ...options.envBranchPrefix !== void 0 ? { envBranchPrefix: options.envBranchPrefix } : {}
+      },
+      gateway: {
+        ...options.authHeader !== void 0 ? { authHeader: options.authHeader } : {},
+        ...options.upstreamAuth !== void 0 ? { upstreamAuth: options.upstreamAuth } : {}
+      },
+      metering: {
+        meters: sortBy([...this.meters.values()], (meter) => meter.key),
+        ...options.billOn4xx !== void 0 ? { billOn4xx: options.billOn4xx } : {}
+      },
+      ...options.billing !== void 0 ? { billing: options.billing } : {},
+      ...this.frontendManifest !== void 0 ? { frontend: this.frontendManifest } : {},
+      ...this.migrations.length ? { migrations: this.migrations } : {},
+      ...this.resources.size ? {
+        resources: sortBy(
+          [...this.resources.values()],
+          (resource) => resource.name
+        )
+      } : {},
+      plans: sortBy([...this.plans.values()], (plan) => plan.key)
+    };
+    return deepMerge(
+      base,
+      this.productPatch
+    );
+  }
+  buildRoute(match, options) {
+    const parsed = parseRouteMatch(match);
+    return {
+      match: parsed,
+      ...options.meters?.length ? { meters: options.meters.map(keyOf) } : {},
+      ...options.unmetered !== void 0 ? { unmetered: options.unmetered } : {},
+      ...options.action !== void 0 ? { action: keyOf(options.action) } : {}
+    };
+  }
+  ensureFrontendManifest() {
+    this.frontendManifest ??= { version: 1, nav: [], pages: [] };
+    return this.frontendManifest;
+  }
+  normalizeMigrationPlanRef(ref) {
+    return {
+      plan: keyOf(ref.plan),
+      ...ref.version !== void 0 ? { version: ref.version } : {}
+    };
+  }
+  normalizeMigrationTargetRef(ref) {
+    return {
+      plan: keyOf(ref.plan),
+      version: ref.version ?? "head"
+    };
+  }
+  assertUniqueMigrationId(id) {
+    if (this.migrations.some((migration) => migration.id === id)) {
+      throw new ManifestBuilderError(
+        `duplicate migration "${id}" \u2014 each migration id must be declared once`
+      );
+    }
+  }
+  assertUniqueMigrationIds(migrations) {
+    const seen = /* @__PURE__ */ new Set();
+    for (const migration of migrations) {
+      if (seen.has(migration.id)) {
+        throw new ManifestBuilderError(
+          `duplicate migration "${migration.id}" \u2014 each migration id must be declared once`
+        );
+      }
+      seen.add(migration.id);
+    }
+  }
+  assertNewKey(map, key, label) {
+    if (map.has(key)) {
+      throw new ManifestBuilderError(
+        `duplicate ${label} "${key}" \u2014 each ${label} key must be declared once`
+      );
+    }
+  }
+};
+function isBusiness(value) {
+  return typeof value === "object" && value !== null && value[BUSINESS_BRAND] === true;
+}
+function sortBy(items, key) {
+  return [...items].sort((a, b) => {
+    const ka = key(a);
+    const kb = key(b);
+    return ka < kb ? -1 : ka > kb ? 1 : 0;
+  });
+}
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function deepMerge(base, patch) {
+  const out = { ...base };
+  for (const [key, value] of Object.entries(patch)) {
+    const existing = out[key];
+    if (isPlainObject(existing) && isPlainObject(value)) {
+      out[key] = deepMerge(existing, value);
+    } else {
+      out[key] = value;
+    }
+  }
+  return out;
+}
+
+// src/bin.ts
+function parseArgs(argv) {
+  const args = {
+    entry: "product.config.ts",
+    out: "manifest-ir.json",
+    diagnosticsOut: "manifest-diagnostics.json"
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const flag = argv[i];
+    const value = argv[i + 1];
+    if (flag === "--entry" && value) {
+      args.entry = value;
+      i++;
+    } else if (flag === "--out" && value) {
+      args.out = value;
+      i++;
+    } else if (flag === "--diagnostics-out" && value) {
+      args.diagnosticsOut = value;
+      i++;
+    } else if (flag === "--help" || flag === "-h") {
+      process.stdout.write(
+        "Usage: farthershore-manifest-build [--entry product.config.ts] [--out manifest-ir.json] [--diagnostics-out manifest-diagnostics.json]\n"
+      );
+      process.exit(0);
+    }
+  }
+  return args;
+}
+function validationIssues(error) {
+  if (error instanceof ManifestValidationError) return error.issues;
+  if (typeof error === "object" && error !== null && error.name === "ManifestValidationError" && Array.isArray(error.issues)) {
+    return error.issues;
+  }
+  return null;
+}
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const entryPath = resolve(process.cwd(), args.entry);
+  let mod;
+  try {
+    mod = await tsImport(
+      pathToFileURL(entryPath).href,
+      import.meta.url
+    );
+  } catch (error) {
+    process.stderr.write(
+      `farthershore-manifest-build: failed to load ${args.entry}: ${error instanceof Error ? error.message : String(error)}
+`
+    );
+    process.exit(1);
+  }
+  const direct = mod.default;
+  const interop = direct?.default;
+  const candidate = isBusiness(direct) ? direct : interop;
+  if (!isBusiness(candidate)) {
+    process.stderr.write(
+      `farthershore-manifest-build: ${args.entry} must \`export default\` the Business returned by fs.business(\u2026)
+`
+    );
+    process.exit(1);
+  }
+  try {
+    const { ir, irHash } = candidate.toIR();
+    await writeFile(
+      resolve(process.cwd(), args.out),
+      `${JSON.stringify({ ir, irHash }, null, 2)}
+`,
+      "utf8"
+    );
+    process.stdout.write(
+      `manifest ok \u2014 ${ir.product.plans?.length ?? 0} plan(s), ${ir.routes.length} feature(s), irHash ${irHash.slice(0, 12)}\u2026 (sdk ${SDK_VERSION})
+`
+    );
+  } catch (error) {
+    const issues = validationIssues(error);
+    if (issues) {
+      await writeFile(
+        resolve(process.cwd(), args.diagnosticsOut),
+        `${JSON.stringify({ version: 1, source: "sdk", issues }, null, 2)}
+`,
+        "utf8"
+      );
+      process.stderr.write(`${errorMessage(error)}
+`);
+      process.exit(2);
+    }
+    process.stderr.write(
+      `farthershore-manifest-build: ${errorMessage(error)}
+`
+    );
+    process.exit(1);
+  }
+}
+await main();