@farthershore/product 0.5.0 → 0.6.1

package/dist/types/backend.d.ts

@@ -0,0 +1,41 @@
+import type { BackendDefinitionJson, BackendRunnerJson, BackendTransportModeJson, MeterDefinitionJson, RouteLayerJson } from "./ir-types.js";
+import { type KeyRef } from "./refs.js";
+import type { MeterRef } from "./route-metering.js";
+export type BackendTransportOptions = {
+    mode?: BackendTransportModeJson;
+    runner?: BackendRunnerJson;
+};
+export type BackendOptions = {
+    /** Human-friendly label (defaults to the id). */
+    name?: string;
+    /** Stable slug (defaults to the id). */
+    slug?: string;
+    transport?: BackendTransportOptions;
+    /** Per-request gateway->backend signature verification. Defaults false until
+     *  the JWKS + signer keystone is proven (deploy-order hard sequence). */
+    verification?: {
+        required?: boolean;
+    };
+    /** Meter allow-list. Omitted = all product meters allowed. */
+    meters?: Array<KeyRef | MeterRef>;
+    /** Marks this as the default backend when a product declares more than one. */
+    default?: boolean;
+    originUrl?: string;
+    originHostname?: string;
+};
+export type BackendNode = {
+    id: string;
+} & BackendDefinitionJson;
+export declare function createBackendNode(id: string, options?: BackendOptions): BackendNode;
+/**
+ * Project registered backend nodes into a record keyed by id, sorted by id for
+ * stable, reviewable IR. The synthetic `id` field is stripped because the map
+ * key carries it.
+ */
+export declare function buildBackendBlock(backendNodes: readonly BackendNode[]): Record<string, BackendDefinitionJson>;
+/**
+ * BYO-Backend V1 — eager build-time validation of route->backend resolution,
+ * mirroring the compiler's `emit-backends` diagnostics so a builder gets a
+ * friendly error before the bytes ever reach the platform compiler.
+ */
+export declare function assertBackendBindingsValid(files: readonly RouteLayerJson[], backendNodes: readonly BackendNode[], meterDefinitions: readonly MeterDefinitionJson[]): void;

package/dist/types/codegen/index.d.ts

@@ -1,2 +1,10 @@
-import type { ManifestIrDocument } from "../ir-types.js";
+import type { ManifestIrDocument, PlanSpecJson } from "../ir-types.js";
+/**
+ * Emit a single `product.plan("key", { ... })` statement — the structured plan
+ * block for WS4 dashboard authoring. Reuses the same faithful `planOptions` +
+ * `lit` printer as full-file generation (price sugar, grants, capability_limits,
+ * the `raw` escape hatch), so the snippet a builder applies via a GitHub edit /
+ * PR is byte-identical to what full regeneration would emit for that plan.
+ */
+export declare function generatePlanStatement(plan: PlanSpecJson): string;
 export declare function generateManifestSource(ir: ManifestIrDocument): string;

package/dist/types/declarations.d.ts

@@ -0,0 +1,123 @@
+import type { ActionSpecJson, CacheProfile, CapabilityLayerJson, CountedResourceJson, CreditPolicyJson, GrantJson, MigrationDeclJson, MigrationPinJson, MutationClass, PlanLimitJson, PlanMeterJson, PlanSpecJson, PolicyLayerJson, ProductEntitlementJson, ProductSurfaceJson, ProductSurfaceTypeJson, ProductWorkflowJson, ProductWorkflowKindJson, ProductWorkflowTriggerJson, RouteDefinitionJson, RouteLayerJson } from "./ir-types.js";
+import type { PriceSpec } from "./price.js";
+import { type KeyRef, type PlanCapabilityGrant } from "./refs.js";
+import type { MeterRef, RouteMeteringOptions } from "./route-metering.js";
+type RouteDeclarationOptions = RouteMeteringOptions & {
+    action?: KeyRef;
+    backend?: KeyRef;
+};
+export type CapabilityDeclarationOptions = {
+    title?: string;
+    description?: string;
+    mutationClass?: MutationClass;
+    includesFeatures?: KeyRef[];
+    includesPolicies?: KeyRef[];
+    includesCapabilities?: KeyRef[];
+};
+export type FeatureDeclarationOptions = {
+    description?: string;
+    mutationClass?: MutationClass;
+    cacheProfile?: CacheProfile;
+    upstreamOrigin?: string | null;
+    policies?: KeyRef[];
+    plans?: KeyRef[];
+    rolloutKey?: string;
+    requiredFlags?: string[];
+    actions?: Array<{
+        id: string;
+    } & Omit<ActionSpecJson, "id">>;
+    routes?: Array<{
+        match: string;
+    } & RouteDeclarationOptions>;
+};
+export type PolicyDeclarationOptions = {
+    type: string;
+    config: Record<string, unknown>;
+    description?: string;
+    mutationClass?: MutationClass;
+    cacheProfile?: CacheProfile;
+    compatibleWith?: {
+        routeTypes?: string[];
+        meters?: Array<KeyRef | MeterRef>;
+        authModes?: string[];
+    };
+};
+export type SurfaceDeclarationOptions = {
+    key?: string;
+    display?: string;
+    description?: string;
+};
+export type WorkflowDeclarationOptions = {
+    title?: string;
+    description?: string;
+    kind?: ProductWorkflowKindJson;
+    trigger?: ProductWorkflowTriggerJson;
+    capabilities?: KeyRef[];
+    meters?: Array<KeyRef | MeterRef>;
+    estimates?: Record<string, number>;
+    metadata?: Record<string, unknown>;
+};
+export type EntitlementDeclarationOptions = {
+    description?: string;
+    capabilities?: KeyRef[];
+    featureGates?: Record<string, boolean>;
+    limits?: PlanLimitJson[];
+    meters?: Array<KeyRef | MeterRef>;
+};
+export type PlanDeclarationOptions = {
+    name: string;
+    description?: string;
+    details?: string[];
+    price?: PriceSpec;
+    meters?: PlanMeterJson[];
+    grants?: Array<GrantJson | PlanCapabilityGrant>;
+    /** Non-grant credit policies (rollover + auto-recharge). */
+    creditPolicy?: CreditPolicyJson;
+    trialDays?: number;
+    maxMonthlySpendCents?: number;
+    minMonthlySpendCents?: number;
+    limits?: PlanLimitJson[];
+    featureGates?: Record<string, boolean>;
+    capabilityLimits?: Record<string, number | boolean>;
+    capabilities?: KeyRef[];
+    overageBehavior?: "block" | "allow_and_bill";
+    selfServeEnabled?: boolean;
+    legacy?: boolean;
+    archive?: {
+        at?: string;
+        transitionTo?: string;
+        strategy?: "auto" | "explicit" | "block";
+    };
+    raw?: Record<string, unknown>;
+};
+export type MigrationPlanRefOptions = {
+    plan: KeyRef;
+    version?: string;
+};
+export type MigrationTargetRefOptions = {
+    plan: KeyRef;
+    version?: "head";
+};
+export type MigrationPinOptions = Omit<MigrationPinJson, "pinTo"> & {
+    pinTo: {
+        plan: KeyRef;
+        version: string;
+    };
+};
+export type MigrationDeclarationOptions = Omit<MigrationDeclJson, "id" | "from" | "to" | "newCustomers" | "pins"> & {
+    from: MigrationPlanRefOptions;
+    to: MigrationTargetRefOptions;
+    newCustomers?: "immediate";
+    pins?: MigrationPinOptions[];
+};
+export type ResourceDeclarationOptions = Omit<CountedResourceJson, "name">;
+export declare function buildCapabilityLayer(key: string, options?: CapabilityDeclarationOptions): CapabilityLayerJson;
+export declare function buildFeatureLayer(key: string, options: FeatureDeclarationOptions, buildRoute: (match: string, options: RouteDeclarationOptions) => RouteDefinitionJson): RouteLayerJson;
+export declare function buildPolicyLayer(name: string, options: PolicyDeclarationOptions): PolicyLayerJson;
+export declare function buildSurfaceSpec(type: ProductSurfaceTypeJson, options?: SurfaceDeclarationOptions): ProductSurfaceJson;
+export declare function buildWorkflowSpec(key: string, options?: WorkflowDeclarationOptions): ProductWorkflowJson;
+export declare function buildEntitlementSpec(key: string, options?: EntitlementDeclarationOptions): ProductEntitlementJson;
+export declare function buildPlanSpec(key: string, options: PlanDeclarationOptions): PlanSpecJson;
+export declare function buildMigrationDecl(id: string, options: MigrationDeclarationOptions): MigrationDeclJson;
+export declare function assertUniqueMigrationIds(migrations: readonly MigrationDeclJson[]): void;
+export {};

package/dist/types/dependencies.d.ts

@@ -0,0 +1,13 @@
+import type { ActionSpecJson, CapabilityLayerJson, FrontendManifestJson, MigrationDeclJson, PlanSpecJson, PolicyLayerJson, ProductEntitlementJson, ProductWorkflowJson, RouteLayerJson } from "./ir-types.js";
+import { type ManifestResourceKind, type ManifestResourceUrn, type MissingManifestResourceDependency } from "./resource-graph.js";
+export type ResourceExists = (kind: ManifestResourceKind, key: string) => boolean;
+export declare function capabilityDependsOn(file: CapabilityLayerJson): ManifestResourceUrn[];
+export declare function policyDependsOn(file: PolicyLayerJson): ManifestResourceUrn[];
+export declare function entitlementDependsOn(entitlement: ProductEntitlementJson, hasResource: ResourceExists): ManifestResourceUrn[];
+export declare function workflowDependsOn(workflow: ProductWorkflowJson): ManifestResourceUrn[];
+export declare function featureDependsOn(file: RouteLayerJson): ManifestResourceUrn[];
+export declare function actionDependsOn(featureKey: string, action: ActionSpecJson): ManifestResourceUrn[];
+export declare function planDependsOn(plan: PlanSpecJson, hasResource: ResourceExists): ManifestResourceUrn[];
+export declare function migrationDependsOn(migration: MigrationDeclJson): ManifestResourceUrn[];
+export declare function frontendDependsOn(manifest: FrontendManifestJson): ManifestResourceUrn[];
+export declare function assertResourceDependenciesSatisfied(missing: readonly MissingManifestResourceDependency[]): void;

package/dist/types/frontend.d.ts

@@ -0,0 +1,23 @@
+import type { FrontendComponentId, FrontendGateMode, FrontendManifestJson } from "./ir-types.js";
+import { type KeyRef } from "./refs.js";
+export type FrontendNavItemInput = {
+    label: string;
+    path: string;
+    capability?: KeyRef;
+};
+export type FrontendComponentInput = {
+    component: FrontendComponentId;
+    props?: Record<string, unknown>;
+    capability?: KeyRef;
+    gateMode?: FrontendGateMode;
+};
+export type FrontendPageInput = {
+    title: string;
+    requiresAuth: boolean;
+    capability?: KeyRef;
+    components?: FrontendComponentInput[];
+};
+export declare function createFrontendManifest(): FrontendManifestJson;
+export declare function setFrontendNav(manifest: FrontendManifestJson, items: FrontendNavItemInput[]): void;
+export declare function addFrontendPage(manifest: FrontendManifestJson, path: string, options: FrontendPageInput): void;
+export declare function frontendCapabilityKeys(manifest: FrontendManifestJson): string[];

package/dist/types/index.d.ts

@@ -12,9 +12,9 @@ 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 { ProductOptions, MeterOptions, RequestMeterOptions, MeterCost, ResourceOptions, CapabilityOptions, ActionOptions, FrontendNavItemOptions, FrontendPageOptions, FrontendComponentOptions, MigrationOptions, FeatureOptions, RouteOptions, PolicyOptions, PlanOptions, SurfaceOptions, EntitlementOptions, MeterRef, ResourceRef, ActionRef, PolicyRef, PlanRef, SurfaceRef, EntitlementRef, FeatureRef, CapabilityRef, PlanCapabilityGrant, ProductModule, } from "./product.js";
+export type { ProductOptions, MeterOptions, RequestMeterOptions, MeterCost, ResourceOptions, CapabilityOptions, ActionOptions, FrontendNavItemOptions, FrontendPageOptions, FrontendComponentOptions, MigrationOptions, FeatureOptions, RouteOptions, BackendOptions, BackendTransportOptions, PolicyOptions, PlanOptions, SurfaceOptions, EntitlementOptions, MeterRef, ResourceRef, ActionRef, BackendRef, PolicyRef, PlanRef, SurfaceRef, EntitlementRef, FeatureRef, CapabilityRef, PlanCapabilityGrant, ProductModule, } from "./product.js";
 export type { ManifestResourceGraphSnapshot, ManifestResourceKind, ManifestResourceUrn, } from "./resource-graph.js";
 export type { PriceSpec } from "./price.js";
 export type { ManifestIssue } from "./errors.js";
 export type { ValidationResult } from "./validate.js";
-export type { ManifestIrDocument, ManifestBuildResult, ProductSpecJson, PlanSpecJson, RoutesFileJson, PolicyFileJson, CapabilityFileJson, FrontendManifestJson, FrontendNavItemJson, FrontendPageJson, FrontendComponentJson, FrontendComponentId, FrontendGateMode, MeterDefinitionJson, PlanMeterJson, PlanLimitJson, GrantJson, HttpMethod, MutationClass, CacheProfile, } from "./ir-types.js";
+export type { ManifestIrDocument, ManifestBuildResult, ProductSpecJson, PlanSpecJson, RouteLayerJson, RouteDefinitionJson, BackendDefinitionJson, BackendTransportModeJson, BackendRunnerJson, PolicyLayerJson, CapabilityLayerJson, FrontendManifestJson, FrontendNavItemJson, FrontendPageJson, FrontendComponentJson, FrontendComponentId, FrontendGateMode, MeterDefinitionJson, PlanMeterJson, PlanLimitJson, GrantJson, HttpMethod, MutationClass, CacheProfile, } from "./ir-types.js";

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

@@ -22,9 +22,20 @@ export type PlanMeterJson = {
     [key: string]: unknown;
 };
 export type GrantJson = {
-    kind: "recurring" | "one_time" | "promotional" | "trial" | "rollover" | "top_up" | "auto_recharge";
+    kind: "credit" | "top_up";
     [key: string]: unknown;
 };
+/** Non-grant credit policies (rollover + auto-recharge) — mirrors the
+ *  platform creditPolicySchema. */
+export type CreditPolicyJson = {
+    rollover?: {
+        percent: number;
+    };
+    auto_recharge?: {
+        threshold_cents: number;
+        refill_cents: number;
+    };
+};
 export type PlanLimitWindowJson = {
     type: "named";
     name: "second" | "minute" | "hour" | "day" | "week" | "month";
@@ -57,6 +68,8 @@ export type PlanSpecJson = {
     max_monthly_spend_cents?: number;
     min_monthly_spend_cents?: number;
     grants?: GrantJson[];
+    creditPolicy?: CreditPolicyJson;
+    capabilities?: string[];
     free?: boolean;
     limits?: PlanLimitJson[];
     featureGates?: Record<string, boolean>;
@@ -82,6 +95,28 @@ export type RouteDefinitionJson = {
     unmetered?: boolean;
     inheritDefaultMeters?: boolean;
     action?: string;
+    /** BYO-Backend V1 — route→backend binding id. Omitted = the sole / default
+     *  backend (single-backend products stay zero-config). */
+    backend?: string;
+};
+export type BackendTransportModeJson = "public_origin" | "mtls" | "cloudflare_tunnel";
+export type BackendRunnerJson = "managed_cloudflared" | "sidecar";
+export type BackendDefinitionJson = {
+    name?: string;
+    slug?: string;
+    transport?: {
+        mode?: BackendTransportModeJson;
+        runner?: BackendRunnerJson;
+    };
+    verification?: {
+        required?: boolean;
+    };
+    /** Meter allow-list. Omitted = all product meters allowed. */
+    meters?: string[];
+    /** Marks the default backend when a product declares more than one. */
+    default?: boolean;
+    originUrl?: string;
+    originHostname?: string;
 };
 export type ActionSpecJson = {
     id: string;
@@ -100,7 +135,7 @@ export type ActionSpecJson = {
         effect: "create" | "delete";
     };
 };
-export type RoutesFileJson = {
+export type RouteLayerJson = {
     feature: string;
     description?: string;
     mutation_class?: MutationClass;
@@ -114,11 +149,13 @@ export type RoutesFileJson = {
         rollout_key?: string;
         required_flags?: string[];
     };
-    capabilities?: string[];
     plans?: string[];
     actions?: ActionSpecJson[];
+    /** BYO-Backend V1 — feature-level default backend binding for all routes in
+     *  this file (routes may override per-route). */
+    backend?: string;
 };
-export type PolicyFileJson = {
+export type PolicyLayerJson = {
     name: string;
     description?: string;
     type: string;
@@ -131,7 +168,7 @@ export type PolicyFileJson = {
     mutation_class?: MutationClass;
     cacheProfile?: CacheProfile;
 };
-export type CapabilityFileJson = {
+export type CapabilityLayerJson = {
     capability: string;
     description?: string;
     mutation_class?: MutationClass;
@@ -294,6 +331,10 @@ export type ProductSpecJson = {
         meters?: MeterDefinitionJson[];
         billOn4xx?: boolean;
     };
+    /** BYO-Backend V1 — first-class backend declarations keyed by backend id.
+     *  Emitted only when at least one backend is declared (so single-backend /
+     *  no-backend products keep their pre-BYOB irHash). */
+    backend?: Record<string, BackendDefinitionJson>;
     frontend?: FrontendManifestJson;
     migrations?: MigrationDeclJson[];
     resources?: CountedResourceJson[];
@@ -312,14 +353,9 @@ export type ManifestIrDocument = {
     irVersion: 1;
     sdkVersion: string;
     product: ProductSpecJson;
-    routes: RoutesFileJson[];
-    policies: PolicyFileJson[];
-    capabilities: CapabilityFileJson[];
-    runtime: {
-        rollout: null;
-        flags: null;
-        migrations: null;
-    };
+    routes: RouteLayerJson[];
+    policies: PolicyLayerJson[];
+    capabilities: CapabilityLayerJson[];
 };
 /** Platform compiler result: the validated envelope plus its canonical hash. */
 export type ManifestBuildResult = {

package/dist/types/product-assembly.d.ts

@@ -0,0 +1,22 @@
+import { type BackendNode } from "./backend.js";
+import type { CountedResourceJson, FrontendManifestJson, MeterDefinitionJson, MigrationDeclJson, PlanSpecJson, ProductEntitlementJson, ProductSpecJson, ProductSurfaceJson, ProductWorkflowJson, RouteLayerJson } from "./ir-types.js";
+import type { ProductOptions } from "./product.js";
+import type { MeterCost } from "./route-metering.js";
+export type ProductSpecAssemblyInput = {
+    name: string;
+    options: ProductOptions;
+    productPatch: Record<string, unknown>;
+    meters: readonly MeterDefinitionJson[];
+    defaultMeterCosts: readonly MeterCost[];
+    backends: readonly BackendNode[];
+    surfaces: readonly ProductSurfaceJson[];
+    entitlements: readonly ProductEntitlementJson[];
+    workflows: readonly ProductWorkflowJson[];
+    frontendManifest?: FrontendManifestJson;
+    migrations: readonly MigrationDeclJson[];
+    resources: readonly CountedResourceJson[];
+    plans: readonly PlanSpecJson[];
+    featureLayers: readonly RouteLayerJson[];
+};
+export declare function assembleProductSpec(input: ProductSpecAssemblyInput): ProductSpecJson;
+export declare function mergeProductPatch(base: Record<string, unknown>, patch: Record<string, unknown>): Record<string, unknown>;

package/dist/types/product.d.ts

@@ -1,6 +1,12 @@
-import type { CacheProfile, ActionSpecJson, CapabilityFileJson, FrontendComponentId, FrontendGateMode, FrontendManifestJson, GrantJson, MeterDefinitionJson, MigrationDeclJson, MigrationPinJson, MutationClass, CountedResourceJson, PlanLimitJson, PlanMeterJson, PlanSpecJson, PolicyFileJson, ProductPoliciesJson, ProductCustomerContextJson, ProductWorkflowKindJson, ProductWorkflowTriggerJson, ProductSurfaceTypeJson, RoutesFileJson } from "./ir-types.js";
+import type { CacheProfile, ActionSpecJson, CapabilityLayerJson, FrontendComponentId, FrontendGateMode, FrontendManifestJson, GrantJson, CreditPolicyJson, MeterDefinitionJson, MigrationDeclJson, MigrationPinJson, MutationClass, CountedResourceJson, PlanLimitJson, PlanMeterJson, PlanSpecJson, PolicyLayerJson, ProductPoliciesJson, ProductCustomerContextJson, ProductWorkflowKindJson, ProductWorkflowTriggerJson, ProductSurfaceTypeJson, RouteLayerJson } from "./ir-types.js";
 import type { PriceSpec } from "./price.js";
 import { type ManifestResourceGraphSnapshot } from "./resource-graph.js";
+import { type BackendOptions } from "./backend.js";
+import { type PlanCapabilityGrant } from "./refs.js";
+import { type MeterCost, type MeterRef, type RouteMeteringOptions } from "./route-metering.js";
+export type { MeterCost, MeterEstimate, MeterRef } from "./route-metering.js";
+export type { BackendOptions, BackendTransportOptions } from "./backend.js";
+export type { PlanCapabilityGrant } from "./refs.js";
 /** Brand symbol so the bin can recognize a Product across SDK copies
  *  (the repo's pinned SDK vs whatever loaded the entry). */
 export declare const PRODUCT_BRAND: unique symbol;
@@ -30,7 +36,6 @@ export type ProductOptions = {
         customerAuth?: ProductCustomerContextJson["portal_auth"];
     };
     billing?: {
-        gracePeriodDays?: number;
         applyLimitUpgradesInstantly?: boolean;
     };
 };
@@ -50,26 +55,12 @@ 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 = {
-    /**
-     * 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;
+export type RouteOptions = RouteMeteringOptions & {
     action?: string | ActionRef;
+    /** BYO-Backend V1 — bind this route to a declared backend. Omitted = the
+     *  product's sole / default backend (single-backend products stay
+     *  zero-config). */
+    backend?: string | BackendRef;
 };
 export type ActionOptions = Omit<ActionSpecJson, "id">;
 export type FrontendNavItemOptions = {
@@ -89,9 +80,16 @@ export type FrontendPageOptions = {
     capability?: string | CapabilityRef;
     components?: FrontendComponentOptions[];
 };
+/**
+ * A plan-version reference: `"head"` (newest ACTIVE version) or a
+ * positive-integer string ("1", "2", ...). The template-literal type rejects
+ * obvious mistakes like date strings (`"2026-06-01"`) at compile time; the
+ * contracts `versionRefSchema` is the runtime source of truth.
+ */
+export type VersionRef = "head" | `${number}`;
 export type MigrationPlanRefOptions = {
     plan: string | PlanRef;
-    version?: string;
+    version?: VersionRef;
 };
 export type MigrationTargetRefOptions = {
     plan: string | PlanRef;
@@ -100,7 +98,7 @@ export type MigrationTargetRefOptions = {
 export type MigrationPinOptions = Omit<MigrationPinJson, "pinTo"> & {
     pinTo: {
         plan: string | PlanRef;
-        version: string;
+        version: VersionRef;
     };
 };
 export type MigrationOptions = Omit<MigrationDeclJson, "id" | "from" | "to" | "newCustomers" | "pins"> & {
@@ -117,7 +115,6 @@ export type FeatureOptions = {
     /** Per-feature upstream origin override (default: product origin). */
     upstreamOrigin?: string | null;
     policies?: Array<string | PolicyRef>;
-    capabilities?: Array<string | CapabilityRef>;
     /** Plans that grant this feature directly. */
     plans?: Array<string | PlanRef>;
     rolloutKey?: string;
@@ -152,6 +149,8 @@ export type PlanOptions = {
     meters?: PlanMeterJson[];
     /** Credit grants and/or capability enablements from `cap.enable()`. */
     grants?: Array<GrantJson | PlanCapabilityGrant>;
+    /** Non-grant credit policies (rollover + auto-recharge). */
+    creditPolicy?: CreditPolicyJson;
     trialDays?: number;
     maxMonthlySpendCents?: number;
     minMonthlySpendCents?: number;
@@ -193,14 +192,6 @@ export type EntitlementOptions = {
     limits?: PlanLimitJson[];
     meters?: Array<string | MeterRef>;
 };
-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";
     readonly key: string;
@@ -229,6 +220,10 @@ export type ActionRef = {
     readonly kind: "action";
     readonly key: string;
 };
+export type BackendRef = {
+    readonly kind: "backend";
+    readonly key: string;
+};
 export type FeatureRef = {
     readonly kind: "feature";
     readonly key: string;
@@ -246,11 +241,6 @@ export type CapabilityRef = {
         limits?: Record<string, number | boolean>;
     }): PlanCapabilityGrant;
 };
-export type PlanCapabilityGrant = {
-    readonly kind: "capability_grant";
-    readonly capability: string;
-    readonly limits?: Record<string, number | boolean>;
-};
 /**
  * A synchronous Product SDK module. Use this to split a product across files:
  * `product.use(configureMeters, configureRoutes, configurePlans)`.
@@ -262,7 +252,6 @@ export declare class Product {
     private readonly options;
     private readonly graph;
     private readonly defaultMeterCosts;
-    private frontendManifest?;
     private productPatch;
     /** Sugar for binding API routes to features. */
     readonly api: {
@@ -279,22 +268,26 @@ export declare class Product {
         migration: (id: string, options: MigrationOptions) => Product;
         migrations: (migrations: MigrationDeclJson[]) => Product;
     };
-    readonly offering: {
-        plan: (key: string, options: PlanOptions) => PlanRef;
-    };
     /** Escape hatches — raw platform-schema JSON, validated by the compiler. */
     readonly raw: {
         /** Deep-merged onto the emitted product spec (usage, webhooks,
          *  environments, add_ons, lifecycle, billing overrides, …). */
         productPatch: (patch: Record<string, unknown>) => Product;
         plan: (spec: PlanSpecJson) => Product;
-        routesFile: (file: RoutesFileJson) => Product;
-        policyFile: (file: PolicyFileJson) => Product;
-        capabilityFile: (file: CapabilityFileJson) => Product;
-        frontend: (manifest: FrontendManifestJson) => Product;
+        routeLayer: (layer: RouteLayerJson) => Product;
+        policyLayer: (layer: PolicyLayerJson) => Product;
+        capabilityLayer: (layer: CapabilityLayerJson) => Product;
     };
     constructor(name: string, options: ProductOptions);
     meter(key: string, options: MeterOptions): MeterRef;
+    /**
+     * BYO-Backend V1 — declare a first-class backend (an always-running HTTP
+     * container Farther Shore wraps). Products may declare MULTIPLE backends;
+     * routes bind to one via `route(..., { backend })`. A product with exactly
+     * one backend (or exactly one marked `default: true`) makes it the implicit
+     * default, so single-backend products stay zero-config.
+     */
+    backend(id: string, options?: BackendOptions): BackendRef;
     requests(options?: RequestMeterOptions): MeterRef;
     defaultMeters(costs: MeterCost | MeterCost[]): Product;
     resource(name: string, options?: ResourceOptions): ResourceRef;
@@ -309,40 +302,17 @@ export declare class Product {
     /** Inspect the SDK-local declaration graph used to emit the Manifest IR. */
     resourceGraph(): ManifestResourceGraphSnapshot;
     private buildProductSpec;
-    private buildMeterDefinitions;
-    private routeValueMeterKeys;
     private buildRoute;
-    private makeMeterRef;
-    private buildRouteMetering;
-    private materializeFeatureFiles;
-    private materializeRoute;
+    private materializeFeatureLayers;
     private normalizeMeterCost;
-    private normalizeMeterCosts;
-    private normalizeMeterRefs;
     private ensureFrontendManifest;
-    private normalizeMigrationPlanRef;
-    private normalizeMigrationTargetRef;
-    private assertUniqueMigrationIds;
     private assertNewKey;
     private assertGraphDependenciesSatisfied;
-    private getFeatureFile;
-    private registerFeatureFile;
+    private getFeatureLayer;
+    private registerFeatureLayer;
     private syncFeatureGraphNode;
     private registerAction;
     private syncFrontendGraphNode;
-    private capabilityDependsOn;
-    private policyDependsOn;
-    private entitlementDependsOn;
-    private workflowDependsOn;
-    private featureDependsOn;
-    private routeMeterDependencyKeys;
-    private assertRouteMeteringValid;
-    private actionDependsOn;
-    private planDependsOn;
-    private migrationDependsOn;
-    private frontendDependsOn;
-    private dependenciesFor;
-    private existingDependenciesFor;
 }
 export declare function isProduct(value: unknown): value is Product;
 export declare function product(name: string, options: ProductOptions, configure?: ProductModule): Product;

package/dist/types/refs.d.ts

@@ -0,0 +1,11 @@
+export type KeyRef = string | {
+    key: string;
+};
+export type PlanCapabilityGrant = {
+    readonly kind: "capability_grant";
+    readonly capability: string;
+    readonly limits?: Record<string, number | boolean>;
+};
+export declare function isCapabilityGrant(value: unknown): value is PlanCapabilityGrant;
+export declare function keyOf(ref: KeyRef): string;
+export declare function displayFromKey(key: string): string;

package/dist/types/resource-graph.d.ts

@@ -1,4 +1,4 @@
-export type ManifestResourceKind = "product" | "meter" | "counted_resource" | "capability" | "surface" | "entitlement" | "workflow" | "policy" | "feature" | "action" | "plan" | "frontend" | "lifecycle_migration";
+export type ManifestResourceKind = "product" | "meter" | "counted_resource" | "capability" | "surface" | "entitlement" | "workflow" | "policy" | "feature" | "action" | "plan" | "backend" | "frontend" | "lifecycle_migration";
 export type ManifestResourceUrn = `urn:farthershore:product:${ManifestResourceKind}:${string}`;
 export type ManifestResourceRef = {
     readonly kind: ManifestResourceKind;

package/dist/types/route-metering.d.ts

@@ -0,0 +1,53 @@
+import type { MeterDefinitionJson, RouteDefinitionJson, RouteLayerJson } from "./ir-types.js";
+import { type KeyRef } from "./refs.js";
+export type MeterCost = {
+    readonly kind: "meter_cost";
+    readonly meter: string;
+    readonly value: number;
+};
+export type MeterEstimate = {
+    readonly kind: "meter_estimate";
+    readonly meter: string;
+    readonly value: number;
+};
+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): MeterEstimate;
+};
+export type RouteMeteringOptions = {
+    /**
+     * Dynamic meter keys the upstream may report with @farthershore/backend.
+     */
+    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> | MeterEstimate | MeterEstimate[];
+    /** Override the default successful-response range. */
+    onStatusCodes?: string | number[];
+    /** Disable product.defaultMeters()/product.requests() for this route only. */
+    inheritDefaultMeters?: boolean;
+    unmetered?: boolean;
+};
+type RouteBindingOptions = RouteMeteringOptions & {
+    action?: KeyRef;
+    /** BYO-Backend V1 — bind this route to a declared backend. Omitted = the
+     *  product's sole / default backend (single-backend products stay
+     *  zero-config). */
+    backend?: KeyRef;
+};
+type RouteMeteringDeps = {
+    normalizeMeterCost(cost: MeterCost): MeterCost;
+    getMeterDefinition(key: string): MeterDefinitionJson | undefined;
+};
+export declare function makeMeterRef(key: string): MeterRef;
+export declare function normalizeMeterCost(cost: MeterCost, hasMeter: (meter: string) => boolean): MeterCost;
+export declare function buildRouteDefinition(match: string, options: RouteBindingOptions, deps: RouteMeteringDeps): RouteDefinitionJson;
+export declare function materializeRoute(route: RouteDefinitionJson, defaultMeterCosts: readonly MeterCost[]): RouteDefinitionJson;
+export declare function routeMeterDependencyKeys(route: RouteDefinitionJson): string[];
+export declare function assertRouteMeteringValid(files: RouteLayerJson[], meterDefinitions: Iterable<MeterDefinitionJson>): void;
+export {};