@farthershore/product 0.2.0 → 0.3.0

package/README.md

@@ -2,9 +2,11 @@
 
 Product-as-Code SDK for Farther Shore. Builder repos use this package from
 `product/product.config.ts` to declare product contracts in TypeScript. Builders
-author and export a `Business`; the Farther Shore GitHub bot compiles that
-program to backend-owned IR, validates it, and publishes through Core when repo
-changes land.
+author and export a `Business`; Farther Shore compiles that program to
+backend-owned IR, validates it, and applies it through Core. Every product is
+created with a GitHub repo that contains the editable `frontend/` starter and
+the Product SDK entrypoint; connecting GitHub is a product-creation
+precondition.
 
 ## Install
 
@@ -31,10 +33,11 @@ frontend/
   ...
 ```
 
-`product/` is authored Product SDK code. `frontend/` is the generated editable
-frontend app and is built by the frontend pipeline only. Runtime state and
-compiled IR are not checked into the builder repo; Farther Shore stores them in
-Core.
+`product/` is authored Product SDK code and may be split into any imported files
+the builder wants. `frontend/` is the generated editable starter app and is built
+by the frontend pipeline only. Runtime state, accepted specs, compilation
+records, deployment runs, and compiled IR are not checked into the builder repo;
+Farther Shore stores them in Core.
 
 ## Example
 
@@ -61,7 +64,16 @@ Modules are plain synchronous functions:
 import { fs, type ProductModule } from "@farthershore/product";
 
 export const configureMeters: ProductModule = (product) => {
-  product.meter("requests", { display: "Requests" });
+  product.requests();
+
+  const tokens = product.meter("tokens_used", {
+    unit: "token",
+    estimate: 500,
+  });
+
+  product.feature("runs").route("POST /v1/runs", {
+    reports: tokens,
+  });
 };
 
 export const configurePlans: ProductModule = (product) => {
@@ -80,10 +92,57 @@ export const configurePlans: ProductModule = (product) => {
 };
 ```
 
-## Bot build
+## Metering
+
+`product.requests()` declares the platform-managed request meter and applies
+`requests = 1` to every metered route. Builders do not need backend code for
+plain request counting.
+
+```ts
+const product = fs.product("croncloud", {
+  baseUrl: "https://api.croncloud.com",
+});
+
+product.requests();
+
+const tokens = product.meter("tokens_used", {
+  unit: "token",
+  estimate: 500,
+});
+
+product.feature("runs").route("POST /v1/runs", {
+  reports: tokens,
+});
+```
+
+Route metering is explicit:
 
-Normal product repos do not call platform release or IR APIs. The GitHub bot
-owns that workflow:
+- omitted route metering inherits product defaults such as `requests = 1`
+- `reports` declares dynamic meters the upstream may report with
+  `@farthershore/metering`
+- `costs` declares gateway-known fixed usage values for a route
+- `estimates` overrides reusable meter estimates for admission checks
+- `unmetered: true` clears all inherited and explicit route metering
+- `inheritDefaultMeters: false` disables inherited defaults only
+
+```ts
+const credits = product.meter("api_credits", { unit: "credit" });
+
+product.defaultMeters(credits.fixed(1));
+
+product.feature("exports").route("POST /v1/bulk-export", {
+  costs: credits.fixed(10),
+});
+
+product.feature("health").route("GET /healthz", {
+  unmetered: true,
+});
+```
+
+## Lifecycle apply paths
+
+Generated product repos use GitHub as the required automation and frontend
+workspace:
 
 1. Loads `product/product.config.ts`.
 2. Requires the default export to be the `Business` returned by
@@ -93,9 +152,15 @@ owns that workflow:
 4. Validates the result against the deployed platform contract.
 5. Publishes the accepted release through Core so edge artifacts propagate.
 
-The bundled `farthershore-manifest-build` binary is bot/build-runner plumbing.
-Run it locally only when debugging the automation itself; it is not part of the
-normal builder workflow.
+The same IR can also be applied to an already repo-backed product through
+trusted Core APIs, for example `farthershore build --apply <product>`. That path
+is useful for local validation/apply loops, but it is not a replacement for the
+product repo. The repo remains the required frontend customization workspace
+because `frontend/` is where the starter UI and all custom React code live.
+
+The bundled `farthershore-manifest-build` binary is shared by the bot,
+build-runner, and CLI. It emits the deterministic Manifest IR envelope that Core
+accepts; Core, not the user repo, remains the lifecycle authority.
 
 ## Public API
 
@@ -104,11 +169,14 @@ normal builder workflow.
 - `business.use(...modules)` — compose Product SDK modules from any files under
   `product/`.
 - `business.meter(...)` — declare billable or enforceable dimensions.
+- `business.requests()` — declare and inherit the platform-managed successful
+  request meter.
+- `business.defaultMeters(...)` — apply reusable fixed costs to metered routes.
 - `business.resource(...)` — declare counted resources for resource-count
   constraints.
 - `business.capability(...)` — declare capability bundles and plan grants.
 - `business.feature(...)` / `business.api.route(...)` — declare gateway routes,
-  meters, and action metadata.
+  static costs, dynamic reports, estimates, and action metadata.
 - `business.policy(...)` — declare policy files in code.
 - `business.plan(...)` — declare plan pricing, limits, grants, and lifecycle
   behavior.

package/dist/bin.js

@@ -1051,10 +1051,11 @@ function validateRouteMeters(spec, ctx) {
   for (const [featureKey, feature] of Object.entries(spec.features)) {
     const routes = feature.routes ?? [];
     routes.forEach((route, routeIdx) => {
-      if (!route.meters || route.meters.length === 0)
+      const routeMeters = routeMeterKeys(route);
+      if (routeMeters.length === 0)
         return;
       anyRouteDeclaresMeters = true;
-      route.meters.forEach((meter, meterIdx) => {
+      routeMeters.forEach((meter, meterIdx) => {
         if (meterKeys.has(meter))
           return;
         ctx.addIssue({
@@ -1064,7 +1065,7 @@ function validateRouteMeters(spec, ctx) {
             featureKey,
             "routes",
             routeIdx,
-            "meters",
+            "metering",
             meterIdx
           ],
           message: `Route references unknown meter "${meter}". Declare it in metering.meters[].`
@@ -1076,7 +1077,7 @@ function validateRouteMeters(spec, ctx) {
     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."
+      message: "One or more routes declare metering keys but `metering.meters[]` is empty. Declare meters at the product level first."
     });
   }
 }
@@ -1093,11 +1094,11 @@ function buildReachableMetersByPlan(spec, runtimeMeters) {
     return out;
   }
   for (const feature of Object.values(spec.features)) {
-    addFeatureMetersToReachable(feature, runtimeMeters, out);
+    addFeatureMetersToReachable(feature, out);
   }
   return out;
 }
-function addFeatureMetersToReachable(feature, runtimeMeters, reachableByPlan) {
+function addFeatureMetersToReachable(feature, reachableByPlan) {
   const grantedPlanKeys = feature.plans ?? [];
   const routes = feature.routes ?? [];
   for (const planKey of grantedPlanKeys) {
@@ -1107,16 +1108,25 @@ function addFeatureMetersToReachable(feature, runtimeMeters, reachableByPlan) {
     for (const route of routes) {
       if (route.unmetered === true)
         continue;
-      if (route.meters && route.meters.length > 0) {
-        for (const meter of route.meters)
+      const modernRouteMeters = routeMeterKeys(route);
+      if (modernRouteMeters.length > 0) {
+        for (const meter of modernRouteMeters)
           reachable.add(meter);
         continue;
       }
-      for (const m of runtimeMeters)
-        reachable.add(m);
     }
   }
 }
+function routeMeterKeys(route) {
+  const keys = /* @__PURE__ */ new Set();
+  for (const key of Object.keys(route.metering?.defaults ?? {}))
+    keys.add(key);
+  for (const key of route.metering?.reports ?? [])
+    keys.add(key);
+  for (const key of Object.keys(route.metering?.estimates ?? {}))
+    keys.add(key);
+  return [...keys];
+}
 function extractLimitMeterKey(limit) {
   if (!limit || typeof limit !== "object")
     return null;
@@ -1185,6 +1195,10 @@ var meterDefinitionSchema = z13.object({
   // freely. Old specs with `type: ...` parse cleanly because Zod
   // strips unknown fields by default.
   unit: z13.string().max(20).optional(),
+  /** Reusable pre-request estimate for routes that dynamically report this meter. */
+  estimate: z13.number().finite().nonnegative().optional(),
+  /** Fixed per-request default applied by Product SDK helpers. */
+  routeDefault: z13.number().finite().nonnegative().optional(),
   /**
    * Runtime enforcement semantics for this meter. This is compiled into
    * signed gateway artifacts so the edge chooses reservation, settlement,
@@ -1291,6 +1305,15 @@ var usageMeterSchema = z13.object({
 var usageBlockSchema = z13.object({
   meters: z13.record(z13.string().min(1).max(64).regex(/^[a-z0-9_]+$/), usageMeterSchema)
 });
+var routeMeteringSchema = z13.object({
+  defaults: z13.record(z13.string().min(1).max(64), z13.number().finite().nonnegative()).optional(),
+  reports: z13.array(z13.string().min(1).max(64)).max(20).optional(),
+  estimates: z13.record(z13.string().min(1).max(64), z13.number().finite().nonnegative()).optional(),
+  onStatusCodes: z13.union([
+    z13.string().min(1).max(100),
+    z13.array(z13.number().int().min(100).max(599)).min(1).max(100)
+  ]).optional()
+});
 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
@@ -1301,35 +1324,12 @@ var featureRouteSchema = z13.object({
   // 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"]
-    });
-  }
-});
+  // Explicit no-usage route. Dynamic/static route metering is declared
+  // exclusively under `metering`.
+  unmetered: z13.boolean().optional(),
+  metering: routeMeteringSchema.optional(),
+  inheritDefaultMeters: z13.boolean().optional()
+}).strict();
 var featureCatalogEntrySchema = z13.object({
   // Optional human-friendly summary; surfaced in dashboards / settings UI.
   description: z13.string().max(500).optional(),
@@ -1465,7 +1465,7 @@ var productSpecSchema = 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.
+    // Read by advanceActiveSubscribersToLatestCompiledPlans.
     applyLimitUpgradesInstantly: z13.boolean().optional(),
     subscriberChangePolicy: subscriberChangePolicySchema.default({
       default: "preserve_current_period",
@@ -1834,28 +1834,21 @@ var routeMatchSchema = z17.object({
 });
 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(),
+  metering: z17.object({
+    defaults: z17.record(z17.string().min(1).max(64), z17.number().finite().nonnegative()).optional(),
+    reports: z17.array(z17.string().min(1).max(64)).max(20).optional(),
+    estimates: z17.record(z17.string().min(1).max(64), z17.number().finite().nonnegative()).optional(),
+    onStatusCodes: z17.union([
+      z17.string().min(1).max(100),
+      z17.array(z17.number().int().min(100).max(599)).min(1).max(100)
+    ]).optional()
+  }).optional(),
   unmetered: z17.boolean().optional(),
+  inheritDefaultMeters: 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"]
-    });
-  }
-});
+}).strict();
 var routeUpstreamSchema = z17.object({
   override_origin: z17.string().url("override_origin must be a valid URL").nullable().default(null)
 });
@@ -2143,7 +2136,7 @@ var productSpecV2Schema = z20.object({
     envBranchPrefix: z20.string().max(50).nullable().optional()
   }),
   /**
-   * Meter catalog. Referenced by /routes/*.yaml via `meters: [...]`.
+   * Meter catalog. Referenced by route `metering` metadata.
    * Same shape as the legacy meterDefinitionSchema (re-exported from
    * product.ts to keep one source of truth during the transition).
    *
@@ -2167,7 +2160,7 @@ var productSpecV2Schema = 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.
+    // Read by advanceActiveSubscribersToLatestCompiledPlans.
     applyLimitUpgradesInstantly: z20.boolean().optional(),
     subscriberChangePolicy: subscriberChangePolicySchema.default(DEFAULT_SUBSCRIBER_CHANGE_POLICY)
   }).default({
@@ -2360,7 +2353,7 @@ function hashIr(ir) {
 }
 
 // src/version.ts
-var SDK_VERSION = true ? "0.2.0" : "0.0.0-dev";
+var SDK_VERSION = true ? "0.3.0" : "0.0.0-dev";
 
 // src/business.ts
 var BUSINESS_BRAND = Symbol.for("farthershore.product.business");
@@ -2370,6 +2363,9 @@ function isCapabilityGrant(value) {
 function keyOf(ref) {
   return typeof ref === "string" ? ref : ref.key;
 }
+function displayFromKey(key) {
+  return key.split("_").filter(Boolean).map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join(" ");
+}
 function parseRouteMatch(match) {
   const trimmed = match.trim();
   const space = trimmed.indexOf(" ");
@@ -2410,6 +2406,7 @@ var Business = class {
   name;
   options;
   graph = new ManifestResourceGraph();
+  defaultMeterCosts = [];
   frontendManifest;
   productPatch = {};
   /** Sugar for binding API routes to features. */
@@ -2566,8 +2563,37 @@ var Business = class {
   }
   meter(key, options) {
     this.assertNewKey("meter", key, "meter");
-    this.graph.register("meter", key, { key, ...options });
-    return { kind: "meter", key };
+    const { routeDefault, ...meterOptions } = options;
+    this.graph.register("meter", key, {
+      key,
+      display: meterOptions.display ?? displayFromKey(key),
+      ...meterOptions
+    });
+    const ref = this.makeMeterRef(key);
+    if (routeDefault !== void 0) {
+      this.defaultMeterCosts.push(
+        this.normalizeMeterCost(ref.fixed(routeDefault))
+      );
+    }
+    return ref;
+  }
+  requests(options = {}) {
+    return this.meter("requests", {
+      display: options.display ?? "Requests",
+      unit: options.unit ?? "request",
+      aggregation: options.aggregation ?? "COUNT",
+      enforcementType: options.enforcementType ?? "estimated_then_settled",
+      window: options.window,
+      estimate: options.estimate ?? 1,
+      routeDefault: 1
+    });
+  }
+  defaultMeters(costs) {
+    const entries = Array.isArray(costs) ? costs : [costs];
+    for (const cost of entries) {
+      this.defaultMeterCosts.push(this.normalizeMeterCost(cost));
+    }
+    return this;
   }
   resource(name, options = {}) {
     this.assertNewKey("counted_resource", name, "resource");
@@ -2740,6 +2766,7 @@ var Business = class {
    *  with structured issues when the declared state is invalid. */
   toIR() {
     this.assertGraphDependenciesSatisfied();
+    this.assertRouteMeteringValid();
     const candidate = {
       irVersion: 1,
       sdkVersion: SDK_VERSION,
@@ -2781,10 +2808,7 @@ var Business = class {
         ...options.upstreamAuth !== void 0 ? { upstreamAuth: options.upstreamAuth } : {}
       },
       metering: {
-        meters: this.graph.sortedValues(
-          "meter",
-          (meter) => meter.key
-        ),
+        meters: this.buildMeterDefinitions(),
         ...options.billOn4xx !== void 0 ? { billOn4xx: options.billOn4xx } : {}
       },
       ...options.billing !== void 0 ? { billing: options.billing } : {},
@@ -2815,15 +2839,109 @@ var Business = class {
       this.productPatch
     );
   }
+  buildMeterDefinitions() {
+    const routeValueMeters = this.routeValueMeterKeys();
+    return this.graph.sortedValues("meter", (meter) => meter.key).map((meter) => {
+      if (meter.aggregation !== void 0) return meter;
+      if (!routeValueMeters.has(meter.key)) return meter;
+      return { ...meter, aggregation: "SUM" };
+    });
+  }
+  routeValueMeterKeys() {
+    const keys = /* @__PURE__ */ new Set();
+    for (const file of this.graph.values("feature")) {
+      for (const route of file.routes) {
+        for (const meter of Object.keys(route.metering?.defaults ?? {})) {
+          keys.add(meter);
+        }
+        for (const meter of route.metering?.reports ?? []) {
+          keys.add(meter);
+        }
+      }
+    }
+    return keys;
+  }
   buildRoute(match, options) {
     const parsed = parseRouteMatch(match);
+    const metering = this.buildRouteMetering(options);
     return {
       match: parsed,
-      ...options.meters?.length ? { meters: options.meters.map(keyOf) } : {},
+      ...metering ? { metering } : {},
       ...options.unmetered !== void 0 ? { unmetered: options.unmetered } : {},
+      ...options.inheritDefaultMeters !== void 0 ? { inheritDefaultMeters: options.inheritDefaultMeters } : {},
       ...options.action !== void 0 ? { action: keyOf(options.action) } : {}
     };
   }
+  makeMeterRef(key) {
+    return {
+      kind: "meter",
+      key,
+      fixed: (value) => ({ kind: "meter_cost", meter: key, value }),
+      estimate: (value) => ({ kind: "meter_cost", meter: key, value })
+    };
+  }
+  buildRouteMetering(options) {
+    if (options.unmetered === true) return void 0;
+    const defaults = {};
+    if (options.inheritDefaultMeters !== false) {
+      for (const cost of this.defaultMeterCosts) {
+        defaults[cost.meter] = (defaults[cost.meter] ?? 0) + cost.value;
+      }
+    }
+    for (const cost of this.normalizeMeterCosts(options.costs)) {
+      defaults[cost.meter] = (defaults[cost.meter] ?? 0) + cost.value;
+    }
+    const reports = [
+      ...new Set(this.normalizeMeterRefs(options.reports ?? []))
+    ];
+    const estimates = {};
+    for (const meter of reports) {
+      const definition = this.graph.get(
+        "meter",
+        meter
+      )?.value;
+      if (typeof definition?.estimate === "number") {
+        estimates[meter] = definition.estimate;
+      }
+    }
+    for (const [meter, value] of Object.entries(options.estimates ?? {})) {
+      estimates[meter] = value;
+    }
+    const out = {};
+    if (Object.keys(defaults).length) out.defaults = defaults;
+    if (reports.length) out.reports = reports;
+    if (Object.keys(estimates).length) out.estimates = estimates;
+    if (options.onStatusCodes !== void 0)
+      out.onStatusCodes = options.onStatusCodes;
+    return Object.keys(out).length ? out : void 0;
+  }
+  normalizeMeterCost(cost) {
+    if (!cost || cost.kind !== "meter_cost") {
+      throw new ManifestBuilderError(
+        "meter cost must be created by meter.fixed(value)"
+      );
+    }
+    if (!this.graph.has("meter", cost.meter)) {
+      throw new ManifestBuilderError(
+        `meter cost references unknown meter "${cost.meter}"`
+      );
+    }
+    if (!Number.isFinite(cost.value) || cost.value < 0) {
+      throw new ManifestBuilderError(
+        `meter "${cost.meter}" fixed value must be a non-negative finite number`
+      );
+    }
+    return cost;
+  }
+  normalizeMeterCosts(costs) {
+    if (!costs) return [];
+    const entries = Array.isArray(costs) ? costs : [costs];
+    return entries.map((cost) => this.normalizeMeterCost(cost));
+  }
+  normalizeMeterRefs(refs) {
+    const entries = Array.isArray(refs) ? refs : [refs];
+    return entries.map(keyOf);
+  }
   ensureFrontendManifest() {
     this.frontendManifest ??= { version: 1, nav: [], pages: [] };
     this.syncFrontendGraphNode(this.frontendManifest);
@@ -2922,7 +3040,9 @@ var Business = class {
     return this.dependenciesFor("meter", file.compatible_with?.meters);
   }
   featureDependsOn(file) {
-    const meterKeys = file.routes.flatMap((route) => route.meters ?? []);
+    const meterKeys = file.routes.flatMap(
+      (route) => this.routeMeterDependencyKeys(route)
+    );
     return [
       ...this.dependenciesFor("policy", file.policies),
       ...this.dependenciesFor("capability", file.capabilities),
@@ -2930,6 +3050,48 @@ var Business = class {
       ...this.dependenciesFor("meter", meterKeys)
     ];
   }
+  routeMeterDependencyKeys(route) {
+    const keys = /* @__PURE__ */ new Set();
+    for (const meter of Object.keys(route.metering?.defaults ?? {})) {
+      keys.add(meter);
+    }
+    for (const meter of route.metering?.reports ?? []) keys.add(meter);
+    for (const meter of Object.keys(route.metering?.estimates ?? {})) {
+      keys.add(meter);
+    }
+    return [...keys];
+  }
+  assertRouteMeteringValid() {
+    for (const file of this.graph.values("feature")) {
+      file.routes.forEach((route, routeIndex) => {
+        if (route.unmetered === true) return;
+        const defaults = new Set(Object.keys(route.metering?.defaults ?? {}));
+        for (const meter of route.metering?.reports ?? []) {
+          if (defaults.has(meter)) {
+            throw new ManifestBuilderError(
+              `feature "${file.feature}" route ${routeIndex}: meter "${meter}" cannot be both a fixed route cost and a dynamic report`
+            );
+          }
+        }
+        for (const meter of route.metering?.reports ?? []) {
+          const definition = this.graph.get(
+            "meter",
+            meter
+          )?.value;
+          const enforcement = definition?.enforcementType ?? "estimated_then_settled";
+          const hasEstimate = route.metering?.estimates && Object.prototype.hasOwnProperty.call(
+            route.metering.estimates,
+            meter
+          );
+          if ((enforcement === "exact_pre_request" || enforcement === "estimated_then_settled") && !hasEstimate) {
+            throw new ManifestBuilderError(
+              `feature "${file.feature}" route ${routeIndex}: reported meter "${meter}" needs an estimate for gateway admission`
+            );
+          }
+        }
+      });
+    }
+  }
   actionDependsOn(featureKey, action) {
     return [
       resourceDependency("feature", featureKey),

package/dist/codegen.js

@@ -143,7 +143,14 @@ function generateManifestSource(ir) {
         options.requiredFlags = file.runtime.required_flags;
       options.routes = file.routes.map((route) => ({
         match: `${route.match.method ?? "*"} ${route.match.path}`,
-        ...route.meters && route.meters.length ? { meters: route.meters } : {},
+        ...route.metering?.reports?.length ? { reports: route.metering.reports } : {},
+        ...route.metering?.defaults && Object.keys(route.metering.defaults).length ? {
+          costs: Object.entries(route.metering.defaults).map(
+            ([meter, value]) => ({ kind: "meter_cost", meter, value })
+          )
+        } : {},
+        ...route.metering?.estimates && Object.keys(route.metering.estimates).length ? { estimates: route.metering.estimates } : {},
+        ...route.metering?.onStatusCodes !== void 0 ? { onStatusCodes: route.metering.onStatusCodes } : {},
         ...route.unmetered !== void 0 ? { unmetered: route.unmetered } : {},
         ...route.action !== void 0 ? { action: route.action } : {}
       }));

package/dist/index.js

@@ -1043,10 +1043,11 @@ function validateRouteMeters(spec, ctx) {
   for (const [featureKey, feature] of Object.entries(spec.features)) {
     const routes = feature.routes ?? [];
     routes.forEach((route, routeIdx) => {
-      if (!route.meters || route.meters.length === 0)
+      const routeMeters = routeMeterKeys(route);
+      if (routeMeters.length === 0)
         return;
       anyRouteDeclaresMeters = true;
-      route.meters.forEach((meter, meterIdx) => {
+      routeMeters.forEach((meter, meterIdx) => {
         if (meterKeys.has(meter))
           return;
         ctx.addIssue({
@@ -1056,7 +1057,7 @@ function validateRouteMeters(spec, ctx) {
             featureKey,
             "routes",
             routeIdx,
-            "meters",
+            "metering",
             meterIdx
           ],
           message: `Route references unknown meter "${meter}". Declare it in metering.meters[].`
@@ -1068,7 +1069,7 @@ function validateRouteMeters(spec, ctx) {
     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."
+      message: "One or more routes declare metering keys but `metering.meters[]` is empty. Declare meters at the product level first."
     });
   }
 }
@@ -1085,11 +1086,11 @@ function buildReachableMetersByPlan(spec, runtimeMeters) {
     return out;
   }
   for (const feature of Object.values(spec.features)) {
-    addFeatureMetersToReachable(feature, runtimeMeters, out);
+    addFeatureMetersToReachable(feature, out);
   }
   return out;
 }
-function addFeatureMetersToReachable(feature, runtimeMeters, reachableByPlan) {
+function addFeatureMetersToReachable(feature, reachableByPlan) {
   const grantedPlanKeys = feature.plans ?? [];
   const routes = feature.routes ?? [];
   for (const planKey of grantedPlanKeys) {
@@ -1099,16 +1100,25 @@ function addFeatureMetersToReachable(feature, runtimeMeters, reachableByPlan) {
     for (const route of routes) {
       if (route.unmetered === true)
         continue;
-      if (route.meters && route.meters.length > 0) {
-        for (const meter of route.meters)
+      const modernRouteMeters = routeMeterKeys(route);
+      if (modernRouteMeters.length > 0) {
+        for (const meter of modernRouteMeters)
           reachable.add(meter);
         continue;
       }
-      for (const m of runtimeMeters)
-        reachable.add(m);
     }
   }
 }
+function routeMeterKeys(route) {
+  const keys = /* @__PURE__ */ new Set();
+  for (const key of Object.keys(route.metering?.defaults ?? {}))
+    keys.add(key);
+  for (const key of route.metering?.reports ?? [])
+    keys.add(key);
+  for (const key of Object.keys(route.metering?.estimates ?? {}))
+    keys.add(key);
+  return [...keys];
+}
 function extractLimitMeterKey(limit) {
   if (!limit || typeof limit !== "object")
     return null;
@@ -1177,6 +1187,10 @@ var meterDefinitionSchema = z13.object({
   // freely. Old specs with `type: ...` parse cleanly because Zod
   // strips unknown fields by default.
   unit: z13.string().max(20).optional(),
+  /** Reusable pre-request estimate for routes that dynamically report this meter. */
+  estimate: z13.number().finite().nonnegative().optional(),
+  /** Fixed per-request default applied by Product SDK helpers. */
+  routeDefault: z13.number().finite().nonnegative().optional(),
   /**
    * Runtime enforcement semantics for this meter. This is compiled into
    * signed gateway artifacts so the edge chooses reservation, settlement,
@@ -1283,6 +1297,15 @@ var usageMeterSchema = z13.object({
 var usageBlockSchema = z13.object({
   meters: z13.record(z13.string().min(1).max(64).regex(/^[a-z0-9_]+$/), usageMeterSchema)
 });
+var routeMeteringSchema = z13.object({
+  defaults: z13.record(z13.string().min(1).max(64), z13.number().finite().nonnegative()).optional(),
+  reports: z13.array(z13.string().min(1).max(64)).max(20).optional(),
+  estimates: z13.record(z13.string().min(1).max(64), z13.number().finite().nonnegative()).optional(),
+  onStatusCodes: z13.union([
+    z13.string().min(1).max(100),
+    z13.array(z13.number().int().min(100).max(599)).min(1).max(100)
+  ]).optional()
+});
 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
@@ -1293,35 +1316,12 @@ var featureRouteSchema = z13.object({
   // 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"]
-    });
-  }
-});
+  // Explicit no-usage route. Dynamic/static route metering is declared
+  // exclusively under `metering`.
+  unmetered: z13.boolean().optional(),
+  metering: routeMeteringSchema.optional(),
+  inheritDefaultMeters: z13.boolean().optional()
+}).strict();
 var featureCatalogEntrySchema = z13.object({
   // Optional human-friendly summary; surfaced in dashboards / settings UI.
   description: z13.string().max(500).optional(),
@@ -1457,7 +1457,7 @@ var productSpecSchema = 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.
+    // Read by advanceActiveSubscribersToLatestCompiledPlans.
     applyLimitUpgradesInstantly: z13.boolean().optional(),
     subscriberChangePolicy: subscriberChangePolicySchema.default({
       default: "preserve_current_period",
@@ -1826,28 +1826,21 @@ var routeMatchSchema = z17.object({
 });
 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(),
+  metering: z17.object({
+    defaults: z17.record(z17.string().min(1).max(64), z17.number().finite().nonnegative()).optional(),
+    reports: z17.array(z17.string().min(1).max(64)).max(20).optional(),
+    estimates: z17.record(z17.string().min(1).max(64), z17.number().finite().nonnegative()).optional(),
+    onStatusCodes: z17.union([
+      z17.string().min(1).max(100),
+      z17.array(z17.number().int().min(100).max(599)).min(1).max(100)
+    ]).optional()
+  }).optional(),
   unmetered: z17.boolean().optional(),
+  inheritDefaultMeters: 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"]
-    });
-  }
-});
+}).strict();
 var routeUpstreamSchema = z17.object({
   override_origin: z17.string().url("override_origin must be a valid URL").nullable().default(null)
 });
@@ -2135,7 +2128,7 @@ var productSpecV2Schema = z20.object({
     envBranchPrefix: z20.string().max(50).nullable().optional()
   }),
   /**
-   * Meter catalog. Referenced by /routes/*.yaml via `meters: [...]`.
+   * Meter catalog. Referenced by route `metering` metadata.
    * Same shape as the legacy meterDefinitionSchema (re-exported from
    * product.ts to keep one source of truth during the transition).
    *
@@ -2159,7 +2152,7 @@ var productSpecV2Schema = 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.
+    // Read by advanceActiveSubscribersToLatestCompiledPlans.
     applyLimitUpgradesInstantly: z20.boolean().optional(),
     subscriberChangePolicy: subscriberChangePolicySchema.default(DEFAULT_SUBSCRIBER_CHANGE_POLICY)
   }).default({
@@ -2355,7 +2348,7 @@ function canonicalIrJson(ir) {
 }
 
 // src/version.ts
-var SDK_VERSION = true ? "0.2.0" : "0.0.0-dev";
+var SDK_VERSION = true ? "0.3.0" : "0.0.0-dev";
 
 // src/business.ts
 var BUSINESS_BRAND = Symbol.for("farthershore.product.business");
@@ -2365,6 +2358,9 @@ function isCapabilityGrant(value) {
 function keyOf(ref) {
   return typeof ref === "string" ? ref : ref.key;
 }
+function displayFromKey(key) {
+  return key.split("_").filter(Boolean).map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join(" ");
+}
 function parseRouteMatch(match) {
   const trimmed = match.trim();
   const space = trimmed.indexOf(" ");
@@ -2405,6 +2401,7 @@ var Business = class {
   name;
   options;
   graph = new ManifestResourceGraph();
+  defaultMeterCosts = [];
   frontendManifest;
   productPatch = {};
   /** Sugar for binding API routes to features. */
@@ -2561,8 +2558,37 @@ var Business = class {
   }
   meter(key, options) {
     this.assertNewKey("meter", key, "meter");
-    this.graph.register("meter", key, { key, ...options });
-    return { kind: "meter", key };
+    const { routeDefault, ...meterOptions } = options;
+    this.graph.register("meter", key, {
+      key,
+      display: meterOptions.display ?? displayFromKey(key),
+      ...meterOptions
+    });
+    const ref = this.makeMeterRef(key);
+    if (routeDefault !== void 0) {
+      this.defaultMeterCosts.push(
+        this.normalizeMeterCost(ref.fixed(routeDefault))
+      );
+    }
+    return ref;
+  }
+  requests(options = {}) {
+    return this.meter("requests", {
+      display: options.display ?? "Requests",
+      unit: options.unit ?? "request",
+      aggregation: options.aggregation ?? "COUNT",
+      enforcementType: options.enforcementType ?? "estimated_then_settled",
+      window: options.window,
+      estimate: options.estimate ?? 1,
+      routeDefault: 1
+    });
+  }
+  defaultMeters(costs) {
+    const entries = Array.isArray(costs) ? costs : [costs];
+    for (const cost of entries) {
+      this.defaultMeterCosts.push(this.normalizeMeterCost(cost));
+    }
+    return this;
   }
   resource(name, options = {}) {
     this.assertNewKey("counted_resource", name, "resource");
@@ -2735,6 +2761,7 @@ var Business = class {
    *  with structured issues when the declared state is invalid. */
   toIR() {
     this.assertGraphDependenciesSatisfied();
+    this.assertRouteMeteringValid();
     const candidate = {
       irVersion: 1,
       sdkVersion: SDK_VERSION,
@@ -2776,10 +2803,7 @@ var Business = class {
         ...options.upstreamAuth !== void 0 ? { upstreamAuth: options.upstreamAuth } : {}
       },
       metering: {
-        meters: this.graph.sortedValues(
-          "meter",
-          (meter) => meter.key
-        ),
+        meters: this.buildMeterDefinitions(),
         ...options.billOn4xx !== void 0 ? { billOn4xx: options.billOn4xx } : {}
       },
       ...options.billing !== void 0 ? { billing: options.billing } : {},
@@ -2810,15 +2834,109 @@ var Business = class {
       this.productPatch
     );
   }
+  buildMeterDefinitions() {
+    const routeValueMeters = this.routeValueMeterKeys();
+    return this.graph.sortedValues("meter", (meter) => meter.key).map((meter) => {
+      if (meter.aggregation !== void 0) return meter;
+      if (!routeValueMeters.has(meter.key)) return meter;
+      return { ...meter, aggregation: "SUM" };
+    });
+  }
+  routeValueMeterKeys() {
+    const keys = /* @__PURE__ */ new Set();
+    for (const file of this.graph.values("feature")) {
+      for (const route of file.routes) {
+        for (const meter of Object.keys(route.metering?.defaults ?? {})) {
+          keys.add(meter);
+        }
+        for (const meter of route.metering?.reports ?? []) {
+          keys.add(meter);
+        }
+      }
+    }
+    return keys;
+  }
   buildRoute(match, options) {
     const parsed = parseRouteMatch(match);
+    const metering = this.buildRouteMetering(options);
     return {
       match: parsed,
-      ...options.meters?.length ? { meters: options.meters.map(keyOf) } : {},
+      ...metering ? { metering } : {},
       ...options.unmetered !== void 0 ? { unmetered: options.unmetered } : {},
+      ...options.inheritDefaultMeters !== void 0 ? { inheritDefaultMeters: options.inheritDefaultMeters } : {},
       ...options.action !== void 0 ? { action: keyOf(options.action) } : {}
     };
   }
+  makeMeterRef(key) {
+    return {
+      kind: "meter",
+      key,
+      fixed: (value) => ({ kind: "meter_cost", meter: key, value }),
+      estimate: (value) => ({ kind: "meter_cost", meter: key, value })
+    };
+  }
+  buildRouteMetering(options) {
+    if (options.unmetered === true) return void 0;
+    const defaults = {};
+    if (options.inheritDefaultMeters !== false) {
+      for (const cost of this.defaultMeterCosts) {
+        defaults[cost.meter] = (defaults[cost.meter] ?? 0) + cost.value;
+      }
+    }
+    for (const cost of this.normalizeMeterCosts(options.costs)) {
+      defaults[cost.meter] = (defaults[cost.meter] ?? 0) + cost.value;
+    }
+    const reports = [
+      ...new Set(this.normalizeMeterRefs(options.reports ?? []))
+    ];
+    const estimates = {};
+    for (const meter of reports) {
+      const definition = this.graph.get(
+        "meter",
+        meter
+      )?.value;
+      if (typeof definition?.estimate === "number") {
+        estimates[meter] = definition.estimate;
+      }
+    }
+    for (const [meter, value] of Object.entries(options.estimates ?? {})) {
+      estimates[meter] = value;
+    }
+    const out = {};
+    if (Object.keys(defaults).length) out.defaults = defaults;
+    if (reports.length) out.reports = reports;
+    if (Object.keys(estimates).length) out.estimates = estimates;
+    if (options.onStatusCodes !== void 0)
+      out.onStatusCodes = options.onStatusCodes;
+    return Object.keys(out).length ? out : void 0;
+  }
+  normalizeMeterCost(cost) {
+    if (!cost || cost.kind !== "meter_cost") {
+      throw new ManifestBuilderError(
+        "meter cost must be created by meter.fixed(value)"
+      );
+    }
+    if (!this.graph.has("meter", cost.meter)) {
+      throw new ManifestBuilderError(
+        `meter cost references unknown meter "${cost.meter}"`
+      );
+    }
+    if (!Number.isFinite(cost.value) || cost.value < 0) {
+      throw new ManifestBuilderError(
+        `meter "${cost.meter}" fixed value must be a non-negative finite number`
+      );
+    }
+    return cost;
+  }
+  normalizeMeterCosts(costs) {
+    if (!costs) return [];
+    const entries = Array.isArray(costs) ? costs : [costs];
+    return entries.map((cost) => this.normalizeMeterCost(cost));
+  }
+  normalizeMeterRefs(refs) {
+    const entries = Array.isArray(refs) ? refs : [refs];
+    return entries.map(keyOf);
+  }
   ensureFrontendManifest() {
     this.frontendManifest ??= { version: 1, nav: [], pages: [] };
     this.syncFrontendGraphNode(this.frontendManifest);
@@ -2917,7 +3035,9 @@ var Business = class {
     return this.dependenciesFor("meter", file.compatible_with?.meters);
   }
   featureDependsOn(file) {
-    const meterKeys = file.routes.flatMap((route) => route.meters ?? []);
+    const meterKeys = file.routes.flatMap(
+      (route) => this.routeMeterDependencyKeys(route)
+    );
     return [
       ...this.dependenciesFor("policy", file.policies),
       ...this.dependenciesFor("capability", file.capabilities),
@@ -2925,6 +3045,48 @@ var Business = class {
       ...this.dependenciesFor("meter", meterKeys)
     ];
   }
+  routeMeterDependencyKeys(route) {
+    const keys = /* @__PURE__ */ new Set();
+    for (const meter of Object.keys(route.metering?.defaults ?? {})) {
+      keys.add(meter);
+    }
+    for (const meter of route.metering?.reports ?? []) keys.add(meter);
+    for (const meter of Object.keys(route.metering?.estimates ?? {})) {
+      keys.add(meter);
+    }
+    return [...keys];
+  }
+  assertRouteMeteringValid() {
+    for (const file of this.graph.values("feature")) {
+      file.routes.forEach((route, routeIndex) => {
+        if (route.unmetered === true) return;
+        const defaults = new Set(Object.keys(route.metering?.defaults ?? {}));
+        for (const meter of route.metering?.reports ?? []) {
+          if (defaults.has(meter)) {
+            throw new ManifestBuilderError(
+              `feature "${file.feature}" route ${routeIndex}: meter "${meter}" cannot be both a fixed route cost and a dynamic report`
+            );
+          }
+        }
+        for (const meter of route.metering?.reports ?? []) {
+          const definition = this.graph.get(
+            "meter",
+            meter
+          )?.value;
+          const enforcement = definition?.enforcementType ?? "estimated_then_settled";
+          const hasEstimate = route.metering?.estimates && Object.prototype.hasOwnProperty.call(
+            route.metering.estimates,
+            meter
+          );
+          if ((enforcement === "exact_pre_request" || enforcement === "estimated_then_settled") && !hasEstimate) {
+            throw new ManifestBuilderError(
+              `feature "${file.feature}" route ${routeIndex}: reported meter "${meter}" needs an estimate for gateway admission`
+            );
+          }
+        }
+      });
+    }
+  }
   actionDependsOn(featureKey, action) {
     return [
       resourceDependency("feature", featureKey),

package/dist/types/business.d.ts

@@ -34,7 +34,14 @@ export type BusinessOptions = {
         applyLimitUpgradesInstantly?: boolean;
     };
 };
-export type MeterOptions = Omit<MeterDefinitionJson, "key">;
+export type MeterOptions = Omit<MeterDefinitionJson, "key" | "display"> & {
+    display?: string;
+    /** Reusable pre-request estimate for dynamic route reports. */
+    estimate?: number;
+    /** Fixed value applied to every metered route unless the route opts out. */
+    routeDefault?: number;
+};
+export type RequestMeterOptions = Partial<Omit<MeterOptions, "routeDefault">>;
 export type CapabilityOptions = {
     title?: string;
     description?: string;
@@ -43,9 +50,24 @@ export type CapabilityOptions = {
     includesPolicies?: Array<string | PolicyRef>;
     includesCapabilities?: Array<string | CapabilityRef>;
 };
+export type MeterCost = {
+    readonly kind: "meter_cost";
+    readonly meter: string;
+    readonly value: number;
+};
 export type RouteOptions = {
-    /** Meter keys this route increments. Omitted = all product meters. */
-    meters?: Array<string | MeterRef>;
+    /**
+     * Dynamic meter keys the upstream may report with @farthershore/metering.
+     */
+    reports?: string | MeterRef | Array<string | MeterRef>;
+    /** Fixed gateway-known route costs. */
+    costs?: MeterCost | Array<MeterCost>;
+    /** Route-specific pre-request estimates for dynamic reports. */
+    estimates?: Record<string, number>;
+    /** Override the default successful-response range. */
+    onStatusCodes?: string | number[];
+    /** Disable product.defaultMeters()/product.requests() for this route only. */
+    inheritDefaultMeters?: boolean;
     unmetered?: boolean;
     action?: string | ActionRef;
 };
@@ -103,7 +125,7 @@ export type FeatureOptions = {
     actions?: Array<{
         id: string;
     } & ActionOptions>;
-    /** Routes, e.g. `{ match: "POST /v1/jobs", meters: ["requests"] }`. */
+    /** Routes, e.g. `{ match: "POST /v1/jobs", reports: [tokens] }`. */
     routes?: Array<{
         match: string;
     } & RouteOptions>;
@@ -152,6 +174,10 @@ export type PlanOptions = {
 export type MeterRef = {
     readonly kind: "meter";
     readonly key: string;
+    /** Fixed gateway-known usage for route/product defaults. */
+    fixed(value: number): MeterCost;
+    /** Convenience value for APIs that want an explicit estimate helper. */
+    estimate(value: number): MeterCost;
 };
 export type ResourceRef = {
     readonly kind: "resource";
@@ -201,6 +227,7 @@ export declare class Business {
     readonly name: string;
     private readonly options;
     private readonly graph;
+    private readonly defaultMeterCosts;
     private frontendManifest?;
     private productPatch;
     /** Sugar for binding API routes to features. */
@@ -231,6 +258,8 @@ export declare class Business {
     };
     constructor(name: string, options: BusinessOptions);
     meter(key: string, options: MeterOptions): MeterRef;
+    requests(options?: RequestMeterOptions): MeterRef;
+    defaultMeters(costs: MeterCost | MeterCost[]): Business;
     resource(name: string, options?: ResourceOptions): ResourceRef;
     capability(key: string, options?: CapabilityOptions): CapabilityRef;
     feature(key: string, options?: FeatureOptions): FeatureRef;
@@ -243,7 +272,14 @@ export declare class Business {
      *  with structured issues when the declared state is invalid. */
     toIR(): ManifestBuildResult;
     private buildProductSpec;
+    private buildMeterDefinitions;
+    private routeValueMeterKeys;
     private buildRoute;
+    private makeMeterRef;
+    private buildRouteMetering;
+    private normalizeMeterCost;
+    private normalizeMeterCosts;
+    private normalizeMeterRefs;
     private ensureFrontendManifest;
     private normalizeMigrationPlanRef;
     private normalizeMigrationTargetRef;
@@ -258,6 +294,8 @@ export declare class Business {
     private capabilityDependsOn;
     private policyDependsOn;
     private featureDependsOn;
+    private routeMeterDependencyKeys;
+    private assertRouteMeteringValid;
     private actionDependsOn;
     private planDependsOn;
     private migrationDependsOn;

package/dist/types/index.d.ts

@@ -14,7 +14,7 @@ export { price } from "./price.js";
 export { validateManifestIr, hashIr, canonicalIrJson } from "./validate.js";
 export { ManifestValidationError, ManifestBuilderError } from "./errors.js";
 export { SDK_VERSION } from "./version.js";
-export type { BusinessOptions, MeterOptions, ResourceOptions, CapabilityOptions, ActionOptions, FrontendNavItemOptions, FrontendPageOptions, FrontendComponentOptions, MigrationOptions, FeatureOptions, RouteOptions, PolicyOptions, PlanOptions, MeterRef, ResourceRef, ActionRef, PolicyRef, PlanRef, FeatureRef, CapabilityRef, PlanCapabilityGrant, ProductModule, } from "./business.js";
+export type { BusinessOptions, MeterOptions, RequestMeterOptions, MeterCost, ResourceOptions, CapabilityOptions, ActionOptions, FrontendNavItemOptions, FrontendPageOptions, FrontendComponentOptions, MigrationOptions, FeatureOptions, RouteOptions, PolicyOptions, PlanOptions, MeterRef, ResourceRef, ActionRef, PolicyRef, PlanRef, FeatureRef, CapabilityRef, PlanCapabilityGrant, ProductModule, } from "./business.js";
 export type { ManifestResourceGraphSnapshot, ManifestResourceKind, ManifestResourceUrn, } from "./resource-graph.js";
 export type { PriceSpec } from "./price.js";
 export type { ManifestIssue } from "./errors.js";

package/dist/types/ir-types.d.ts

@@ -5,6 +5,8 @@ export type MeterDefinitionJson = {
     key: string;
     display: string;
     unit?: string;
+    estimate?: number;
+    routeDefault?: number;
     enforcementType?: "exact_pre_request" | "estimated_then_settled" | "postpaid" | "strict_concurrency";
     aggregation?: "SUM" | "COUNT" | "MAX" | "UNIQUE_COUNT" | "LATEST";
     window?: "minute" | "hour" | "day" | "month" | "billing_period";
@@ -71,8 +73,14 @@ export type RouteDefinitionJson = {
         method?: HttpMethod;
         path: string;
     };
-    meters?: string[] | null;
+    metering?: {
+        defaults?: Record<string, number>;
+        reports?: string[];
+        estimates?: Record<string, number>;
+        onStatusCodes?: string | number[];
+    };
     unmetered?: boolean;
+    inheritDefaultMeters?: boolean;
     action?: string;
 };
 export type ActionSpecJson = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farthershore/product",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Farther Shore product-as-code SDK — declare your business in TypeScript",
   "type": "module",
   "main": "./dist/index.js",