@farthershore/cli 0.3.8 → 0.3.10

package/node_modules/@farther-shore/shared-types/dist/edge-kv-keys.d.ts

@@ -0,0 +1,254 @@
+/**
+ * Incremented whenever a key format or artifact envelope shape changes.
+ * Writers stamp this version on every record; readers inspect it and can
+ * log / fall back / refuse on mismatch.
+ */
+export declare const KV_KEY_SCHEMA_VERSION = 1;
+export declare const kvKeys: {
+    /** Tenant routing key — "which product does this subdomain belong to?" */
+    readonly subdomain: (slug: string) => string;
+    /**
+     * Per-product config record. Env-scoped when `environmentId` is set —
+     * the gateway looks up the env-scoped key first and falls back to the
+     * production key when it misses.
+     */
+    readonly product: (productId: string, environmentId?: string | null) => string;
+    /** Per-plan config record. Shared across envs — plan IDs are globally unique. */
+    readonly plan: (planId: string) => string;
+    /**
+     * Credential record keyed by the hash of the presented API key. The
+     * gateway hashes inbound keys and looks up this record to resolve the
+     * caller's subject. Never key by the raw API key.
+     */
+    readonly credential: (keyHash: string) => string;
+    /**
+     * Compiled entitlement record.
+     *
+     * v0.14.0 — keyed by `compiledPlanId` (immutable CompiledPlan pointer).
+     * All subscribers on the same CompiledPlan share one KV entry.
+     *
+     * Prior to v0.14.0 this was keyed by `subjectKey`. Writers must call
+     * the builder with the new argument name; readers that still receive a
+     * subject-keyed record should fall back gracefully (treated as cache
+     * miss and re-read from DB).
+     */
+    readonly entitlement: (compiledPlanId: string) => string;
+    /** Shard policy record. One per product; env shares the production policy. */
+    readonly shardPolicy: (productId: string) => string;
+    /**
+     * Per-subscriber lifecycle state overlay.
+     *
+     * One entry per (subjectKey, environmentId). The gateway reads this on
+     * every request to resolve:
+     *   - which CompiledPlan's entitlement is currently active for the sub
+     *     (`activeCompiledPlanId` → fetch `entitlement:<that>`)
+     *   - the enforcement mode (STRICT | GRACE | TRACK_ONLY)
+     *   - per-subscriber overrides (spend cap, reduced grace limits, …)
+     *   - whether a transition is scheduled (so it can pre-cache the next
+     *     entitlement)
+     *
+     * Together with `entitlement:<compiledPlanId>` (shared across subs on
+     * the same plan version) + `subscription_state:<subjectKey>` (per-sub
+     * overlay), the gateway has everything it needs to make a per-request
+     * enforcement decision without recompiling entitlements per subscriber.
+     */
+    readonly subscriptionState: (subjectKey: string, environmentId?: string | null) => string;
+    /**
+     * Per-lineage atomic snapshot — the xDS pattern for long-horizon API
+     * versioning (Phase A8a).
+     *
+     * Single-key bundle of every CompiledPlan currently serving a lineage:
+     * the ACTIVE head + the optional LEGACY_STABLE secondary head + every
+     * EXPERIMENTAL variant. The gateway prefers this key over the
+     * per-CompiledPlan `entitlement:<id>` keys so it can read the full
+     * "current entitlement set for lineage L" with one round-trip and zero
+     * possibility of torn state.
+     *
+     * Atomicity: writes are last-writer-wins on a single Cloudflare KV
+     * key. Two concurrent compiles on the same lineage produce a
+     * deterministic resolution — the later `publishedAt` wins; the
+     * `reconcileEdgeKvKeys` cron heals drift.
+     *
+     * Backward compat: gateway falls back to per-CP key
+     * (`entitlement:<compiledPlanId>`) when the snapshot is missing.
+     * Writers dual-publish during the rollout; eventual consistency on
+     * the snapshot is fine.
+     */
+    readonly lineageSnapshot: (lineageId: string) => string;
+    /**
+     * Per-lineage tombstone (Phase A8c). Written briefly when a CP is
+     * removed from the snapshot mid-flight (e.g. variant rollback) so
+     * late readers in the gateway's 2-second cache window see a clear
+     * "this lineage's experimental set is shrinking" signal instead of
+     * "key not found." Cleared on next successful publish; cron sweeps
+     * after 24h.
+     */
+    readonly lineageTombstone: (lineageId: string) => string;
+};
+export type KvKeyBuilder = typeof kvKeys;
+/**
+ * What the gateway reads + applies on every request, layered on top of
+ * the shared `entitlement:<compiledPlanId>` record.
+ *
+ * Written by core's `subscription-state-publisher` whenever the
+ * subscription's lifecycle / scheduledTransition / overrides change.
+ * Read by the gateway worker on every request after credential lookup.
+ */
+export type EdgeSubscriptionState = {
+    /** Internal Subscription.id — for diagnostics / cross-ref into core. */
+    subscriptionId: string;
+    /** SubscriptionPeriod.id of the currently-active period (Phase 6 stub —
+     *  may be undefined until SubscriptionPeriod is fully wired). */
+    activePeriodId?: string;
+    /** Points at `entitlement:<compiledPlanId>`. The gateway fetches that
+     *  separately; this overlay just routes to the right one. */
+    activeCompiledPlanId: string;
+    /** Enforcement mode for this subscriber RIGHT NOW.
+     *    STRICT     — hard limits, BLOCK on overage
+     *    GRACE      — limits soft (track) until gracePeriodEndsAt
+     *    TRACK_ONLY — log everything, never block (trial prep, dunning) */
+    enforcementMode: "STRICT" | "GRACE" | "TRACK_ONLY";
+    /** Set when enforcementMode = GRACE. ISO 8601 string. Gateway compares
+     *  against now; expired grace self-heals to STRICT on the next
+     *  request. Absent when enforcementMode != GRACE. */
+    gracePeriodEndsAt?: string;
+    /** Per-subscriber overrides applied AFTER the base entitlement loads. */
+    overrides?: {
+        /** Hard cap on monthly consumer spend. Compiled into a dollars/month
+         *  enforce-mode rule even if the plan otherwise lets overage through. */
+        maxMonthlySpendCents?: number;
+        /** Reduced limits during grace, e.g. {requests: 100} drops the
+         *  requests-per-minute cap to 100 instead of the plan's 1000. */
+        limitOverrides?: Record<string, number>;
+        /** Per-subscriber feature-gate overrides — flip individual flags
+         *  without rebuilding the CompiledPlan. */
+        featureGateOverrides?: Record<string, boolean>;
+    };
+    /** Heads-up to the gateway about an upcoming transition. Lets it
+     *  pre-warm the next entitlement record so the cutover is hot. */
+    scheduledTransition?: {
+        kind: string;
+        timing: string;
+        scheduledFor: string;
+        toCompiledPlanId: string | null;
+    };
+    /** Monotonic generation counter — bumped on every state change so
+     *  caches downstream of the gateway can detect staleness. */
+    generation: number;
+    /** When this overlay was last written. */
+    updatedAt: string;
+};
+/**
+ * One member of a lineage's experimental rollout. The gateway uses these
+ * to bucket new subscribers (sticky-assigned via SHA-256 hash) without
+ * re-querying core. Mirrors `CompiledPlan.{rolloutPercent, assignmentSeed,
+ * prorationOnRollback}` from Phase A1 schema.
+ */
+export type LineageSnapshotExperimentalMember = {
+    compiledPlanId: string;
+    rolloutPercent: number;
+    assignmentSeed: string;
+    prorationOnRollback: "NONE" | "PRORATE" | "CREDIT";
+    /** SHA-256 of the entitlement payload — lets the gateway detect a
+     *  bypass / KV inconsistency without refetching the per-CP key. */
+    entitlementHash: string;
+};
+/**
+ * One member of a lineage's stable head. There are at most two: the
+ * `ACTIVE` head (always present) and the optional `LEGACY_STABLE` head
+ * (the grandfathered cohort).
+ */
+export type LineageSnapshotStableMember = {
+    compiledPlanId: string;
+    /** SHA-256 of the entitlement payload. */
+    entitlementHash: string;
+};
+/**
+ * Atomic snapshot of every CompiledPlan currently serving a lineage.
+ * The gateway reads ONE key (`lineage:<lineageId>:current`) and has the
+ * full set — no torn state where ACTIVE is updated but LEGACY_STABLE
+ * still on the previous content.
+ *
+ * Signature: HMAC-SHA256 over `{ lineageId, publishedAt, active,
+ * secondaryActive?, experimental[] }` (everything except the signature
+ * field itself), using the same signing secret as
+ * `entitlement-compiler.ts`. Gateway verifies; mismatch → log + treat
+ * as miss + fall back to per-CP key.
+ */
+export type EdgeLineageSnapshot = {
+    /** Internal PlanLineage.id — stable across compiles. */
+    lineageId: string;
+    /** ISO 8601. Last-writer-wins tiebreaker for concurrent compiles. */
+    publishedAt: string;
+    /** The current ACTIVE head — non-null at all times for any lineage
+     *  that has subscribers. */
+    active: LineageSnapshotStableMember;
+    /** The LEGACY_STABLE head, if YAML declared `legacy: true` on a peer
+     *  plan. */
+    secondaryActive?: LineageSnapshotStableMember;
+    /** Every EXPERIMENTAL variant currently in this lineage. Empty when
+     *  no variants are running. */
+    experimental: LineageSnapshotExperimentalMember[];
+    /** HMAC signature over the snapshot fields (excluding `signature`). */
+    signature: string;
+};
+/**
+ * Tombstone payload for a temporarily-shrinking lineage. Written when
+ * a CP is being removed from the snapshot AND the new snapshot hasn't
+ * landed yet (KV consistency window). Cleared on next successful
+ * publish; cron sweeps after 24h.
+ */
+export type EdgeLineageTombstone = {
+    /** Same id as `EdgeLineageSnapshot.lineageId`. */
+    lineageId: string;
+    /** When the tombstone was written. */
+    archivedAt: string;
+    /** Set of compiledPlanIds being removed from the snapshot. */
+    removedCompiledPlanIds: string[];
+};
+/**
+ * Tombstone payload written to `ent:<compiledPlanId>` when a
+ * CompiledPlan transitions to ARCHIVED but the key isn't yet eligible
+ * for hard-delete (within the 7-day retention window).
+ *
+ * Late readers in the gateway's 2-second cache window get a clear
+ * "this CP is archived" signal instead of a "key not found" miss
+ * (which the gateway would otherwise treat as an unknown CP).
+ *
+ * The reconcileEdgeKvKeys cron promotes tombstones past the retention
+ * window into hard deletes. The envelope's `kind: "ARCHIVED"`
+ * discriminator distinguishes it from a live `CompiledEntitlement`
+ * payload — gateway readers branch on it.
+ */
+export type EdgeEntitlementTombstone = {
+    kind: "ARCHIVED";
+    compiledPlanId: string;
+    /** When the tombstone was written. */
+    archivedAt: string;
+    /** Optional pointer to the lineage's current ACTIVE head; lets the
+     *  gateway emit a useful 410 Gone with redirect hint. */
+    lineageActiveCompiledPlanId?: string;
+};
+/**
+ * Every artifact written to KV is wrapped in an envelope that records the
+ * schema version it was written with. Readers unwrap on load; if the
+ * version has advanced the reader can branch or fall back.
+ */
+export type EdgeArtifactEnvelope<T> = {
+    version: number;
+    payload: T;
+};
+/** Wrap a payload for write. Stamps the current schema version. */
+export declare function wrapEnvelope<T>(payload: T): EdgeArtifactEnvelope<T>;
+/**
+ * Unwrap a record from KV. Tolerates three shapes:
+ *   1. `{ version, payload }` — modern envelope. Returned as-is.
+ *   2. Raw payload object — legacy writes that pre-date versioning.
+ *      Returned as `{ version: 0, payload: raw }` so readers can detect
+ *      the legacy case and migrate in place if desired.
+ *   3. `null` / non-object — treated as a miss.
+ *
+ * Does NOT throw on version mismatch. Callers inspect `version` and decide.
+ */
+export declare function readEnvelope<T>(raw: unknown): EdgeArtifactEnvelope<T> | null;
+//# sourceMappingURL=edge-kv-keys.d.ts.map

package/node_modules/@farther-shore/shared-types/dist/edge-kv-keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"edge-kv-keys.d.ts","sourceRoot":"","sources":["../src/edge-kv-keys.ts"],"names":[],"mappings":"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"}

package/node_modules/@farther-shore/shared-types/dist/edge-kv-keys.js

@@ -0,0 +1,134 @@
+// Canonical edge-KV key builders + versioned artifact envelope.
+//
+// Single source of truth for the key formats that the gateway (reader) and
+// core (writer) must agree on. If the format changes, bump
+// `KV_KEY_SCHEMA_VERSION` here and both ends pick it up atomically when
+// they rebuild against the new shared-types release.
+//
+// Gateway reads these keys; core writes them. Every KV key ever put into
+// the product/plan/credential/entitlement/shard/subdomain namespace must
+// go through one of the `kvKeys.*` builders.
+//
+// Envelope (Phase 4.2): every artifact is wrapped with a `version` field
+// so schema changes have a migration lane. Legacy unwrapped values are
+// tolerated by `readEnvelope` as `{ version: 0, payload: raw }`.
+/**
+ * Incremented whenever a key format or artifact envelope shape changes.
+ * Writers stamp this version on every record; readers inspect it and can
+ * log / fall back / refuse on mismatch.
+ */
+export const KV_KEY_SCHEMA_VERSION = 1;
+export const kvKeys = {
+    /** Tenant routing key — "which product does this subdomain belong to?" */
+    subdomain: (slug) => `subdomain:${slug.toLowerCase()}`,
+    /**
+     * Per-product config record. Env-scoped when `environmentId` is set —
+     * the gateway looks up the env-scoped key first and falls back to the
+     * production key when it misses.
+     */
+    product: (productId, environmentId) => environmentId
+        ? `product:${productId}:env:${environmentId}`
+        : `product:${productId}`,
+    /** Per-plan config record. Shared across envs — plan IDs are globally unique. */
+    plan: (planId) => `plan:${planId}`,
+    /**
+     * Credential record keyed by the hash of the presented API key. The
+     * gateway hashes inbound keys and looks up this record to resolve the
+     * caller's subject. Never key by the raw API key.
+     */
+    credential: (keyHash) => `cred:${keyHash}`,
+    /**
+     * Compiled entitlement record.
+     *
+     * v0.14.0 — keyed by `compiledPlanId` (immutable CompiledPlan pointer).
+     * All subscribers on the same CompiledPlan share one KV entry.
+     *
+     * Prior to v0.14.0 this was keyed by `subjectKey`. Writers must call
+     * the builder with the new argument name; readers that still receive a
+     * subject-keyed record should fall back gracefully (treated as cache
+     * miss and re-read from DB).
+     */
+    entitlement: (compiledPlanId) => `ent:${compiledPlanId}`,
+    /** Shard policy record. One per product; env shares the production policy. */
+    shardPolicy: (productId) => `shard:${productId}`,
+    /**
+     * Per-subscriber lifecycle state overlay.
+     *
+     * One entry per (subjectKey, environmentId). The gateway reads this on
+     * every request to resolve:
+     *   - which CompiledPlan's entitlement is currently active for the sub
+     *     (`activeCompiledPlanId` → fetch `entitlement:<that>`)
+     *   - the enforcement mode (STRICT | GRACE | TRACK_ONLY)
+     *   - per-subscriber overrides (spend cap, reduced grace limits, …)
+     *   - whether a transition is scheduled (so it can pre-cache the next
+     *     entitlement)
+     *
+     * Together with `entitlement:<compiledPlanId>` (shared across subs on
+     * the same plan version) + `subscription_state:<subjectKey>` (per-sub
+     * overlay), the gateway has everything it needs to make a per-request
+     * enforcement decision without recompiling entitlements per subscriber.
+     */
+    subscriptionState: (subjectKey, environmentId) => environmentId
+        ? `substate:${environmentId}:${subjectKey}`
+        : `substate:${subjectKey}`,
+    /**
+     * Per-lineage atomic snapshot — the xDS pattern for long-horizon API
+     * versioning (Phase A8a).
+     *
+     * Single-key bundle of every CompiledPlan currently serving a lineage:
+     * the ACTIVE head + the optional LEGACY_STABLE secondary head + every
+     * EXPERIMENTAL variant. The gateway prefers this key over the
+     * per-CompiledPlan `entitlement:<id>` keys so it can read the full
+     * "current entitlement set for lineage L" with one round-trip and zero
+     * possibility of torn state.
+     *
+     * Atomicity: writes are last-writer-wins on a single Cloudflare KV
+     * key. Two concurrent compiles on the same lineage produce a
+     * deterministic resolution — the later `publishedAt` wins; the
+     * `reconcileEdgeKvKeys` cron heals drift.
+     *
+     * Backward compat: gateway falls back to per-CP key
+     * (`entitlement:<compiledPlanId>`) when the snapshot is missing.
+     * Writers dual-publish during the rollout; eventual consistency on
+     * the snapshot is fine.
+     */
+    lineageSnapshot: (lineageId) => `lineage:${lineageId}:current`,
+    /**
+     * Per-lineage tombstone (Phase A8c). Written briefly when a CP is
+     * removed from the snapshot mid-flight (e.g. variant rollback) so
+     * late readers in the gateway's 2-second cache window see a clear
+     * "this lineage's experimental set is shrinking" signal instead of
+     * "key not found." Cleared on next successful publish; cron sweeps
+     * after 24h.
+     */
+    lineageTombstone: (lineageId) => `lineage:${lineageId}:tombstone`,
+};
+/** Wrap a payload for write. Stamps the current schema version. */
+export function wrapEnvelope(payload) {
+    return { version: KV_KEY_SCHEMA_VERSION, payload };
+}
+/**
+ * Unwrap a record from KV. Tolerates three shapes:
+ *   1. `{ version, payload }` — modern envelope. Returned as-is.
+ *   2. Raw payload object — legacy writes that pre-date versioning.
+ *      Returned as `{ version: 0, payload: raw }` so readers can detect
+ *      the legacy case and migrate in place if desired.
+ *   3. `null` / non-object — treated as a miss.
+ *
+ * Does NOT throw on version mismatch. Callers inspect `version` and decide.
+ */
+export function readEnvelope(raw) {
+    if (raw === null || raw === undefined)
+        return null;
+    if (typeof raw !== "object")
+        return null;
+    const obj = raw;
+    if (typeof obj.version === "number" &&
+        "payload" in obj &&
+        obj.payload !== undefined) {
+        return { version: obj.version, payload: obj.payload };
+    }
+    // Legacy pre-envelope shape — the whole object is the payload.
+    return { version: 0, payload: raw };
+}
+//# sourceMappingURL=edge-kv-keys.js.map

package/node_modules/@farther-shore/shared-types/dist/edge-kv-keys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"edge-kv-keys.js","sourceRoot":"","sources":["../src/edge-kv-keys.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAChE,EAAE;AACF,2EAA2E;AAC3E,2DAA2D;AAC3D,wEAAwE;AACxE,qDAAqD;AACrD,EAAE;AACF,yEAAyE;AACzE,yEAAyE;AACzE,6CAA6C;AAC7C,EAAE;AACF,yEAAyE;AACzE,uEAAuE;AACvE,iEAAiE;AAEjE;;;;GAIG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC;AAEvC,MAAM,CAAC,MAAM,MAAM,GAAG;IACpB,0EAA0E;IAC1E,SAAS,EAAE,CAAC,IAAY,EAAE,EAAE,CAAC,aAAa,IAAI,CAAC,WAAW,EAAE,EAAE;IAE9D;;;;OAIG;IACH,OAAO,EAAE,CAAC,SAAiB,EAAE,aAA6B,EAAE,EAAE,CAC5D,aAAa;QACX,CAAC,CAAC,WAAW,SAAS,QAAQ,aAAa,EAAE;QAC7C,CAAC,CAAC,WAAW,SAAS,EAAE;IAE5B,iFAAiF;IACjF,IAAI,EAAE,CAAC,MAAc,EAAE,EAAE,CAAC,QAAQ,MAAM,EAAE;IAE1C;;;;OAIG;IACH,UAAU,EAAE,CAAC,OAAe,EAAE,EAAE,CAAC,QAAQ,OAAO,EAAE;IAElD;;;;;;;;;;OAUG;IACH,WAAW,EAAE,CAAC,cAAsB,EAAE,EAAE,CAAC,OAAO,cAAc,EAAE;IAEhE,8EAA8E;IAC9E,WAAW,EAAE,CAAC,SAAiB,EAAE,EAAE,CAAC,SAAS,SAAS,EAAE;IAExD;;;;;;;;;;;;;;;;OAgBG;IACH,iBAAiB,EAAE,CAAC,UAAkB,EAAE,aAA6B,EAAE,EAAE,CACvE,aAAa;QACX,CAAC,CAAC,YAAY,aAAa,IAAI,UAAU,EAAE;QAC3C,CAAC,CAAC,YAAY,UAAU,EAAE;IAE9B;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,eAAe,EAAE,CAAC,SAAiB,EAAE,EAAE,CAAC,WAAW,SAAS,UAAU;IAEtE;;;;;;;OAOG;IACH,gBAAgB,EAAE,CAAC,SAAiB,EAAE,EAAE,CAAC,WAAW,SAAS,YAAY;CACjE,CAAC;AAgLX,mEAAmE;AACnE,MAAM,UAAU,YAAY,CAAI,OAAU;IACxC,OAAO,EAAE,OAAO,EAAE,qBAAqB,EAAE,OAAO,EAAE,CAAC;AACrD,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,YAAY,CAC1B,GAAY;IAEZ,IAAI,GAAG,KAAK,IAAI,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACnD,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IACzC,MAAM,GAAG,GAAG,GAA8B,CAAC;IAC3C,IACE,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ;QAC/B,SAAS,IAAI,GAAG;QAChB,GAAG,CAAC,OAAO,KAAK,SAAS,EACzB,CAAC;QACD,OAAO,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,CAAC,OAAY,EAAE,CAAC;IAC7D,CAAC;IACD,+DAA+D;IAC/D,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,GAAQ,EAAE,CAAC;AAC3C,CAAC"}

package/node_modules/@farther-shore/shared-types/dist/entitlements.d.ts

@@ -0,0 +1,86 @@
+import type { OverageBehavior } from "./enums.js";
+export type CompiledFloorSpec = {
+    perRequestMinUnitsByDim?: Record<string, number>;
+    creditPoolMicros?: number;
+    perDimUnitCostMicros?: Record<string, number>;
+};
+export type CompiledConsumptiveRule = {
+    d: number;
+    w: number;
+    c: number;
+    m?: "e" | "t";
+};
+export type CompiledOccupancyRule = {
+    d: number;
+    max: number;
+    ttl: number;
+};
+/**
+ * Compiled entitlement record. Published to KV at `ent:<compiledPlanId>`
+ * and SHARED across all subscribers on the same CompiledPlan. The record
+ * does NOT identify an individual subject — it is strictly a plan-level
+ * artifact.
+ *
+ * Subject-scoped authorization happens at the gateway by comparing
+ * `CredentialRecord.compiledPlanId` (signed at credential-sync time)
+ * against `CompiledEntitlement.compiledPlanId` (signed at compile time).
+ * Use {@link verifyCredentialBindsToEntitlement} for this check — it is
+ * the single canonical trust-boundary comparison now that the
+ * entitlement artifact no longer carries subject identity.
+ *
+ * The `sub` field is retained ONLY for audit / correlation and MAY hold
+ * a representative or constant placeholder (e.g. `"cp:<compiledPlanId>"`).
+ * Consumers MUST NOT use it for authorization decisions; a stale
+ * credential paired with the wrong compiledPlanId would otherwise still
+ * resolve against a valid entitlement and defeat fail-closed semantics.
+ */
+export type CompiledEntitlement = {
+    v: number;
+    /**
+     * Subject key for audit + correlation ONLY. NOT authoritative; NOT the
+     * KV lookup key (that's `compiledPlanId`). When a CompiledPlan is
+     * shared across many subscribers, this holds a representative or
+     * constant placeholder (e.g. `"cp:<compiledPlanId>"`). Do NOT use for
+     * authorization; see the type-level doc for the correct pattern.
+     */
+    sub: string;
+    /**
+     * Immutable CompiledPlan.id pointer. Replaces legacy `planId`. This
+     * is the field the gateway compares against `CredentialRecord.compiledPlanId`
+     * to bind a request to an entitlement.
+     */
+    compiledPlanId: string;
+    planType: string;
+    ts: number;
+    cr: CompiledConsumptiveRule[];
+    or: CompiledOccupancyRule[];
+    fg: Record<string, boolean>;
+    dm: Record<string, number>;
+    dmv: number;
+    floor: CompiledFloorSpec | null;
+    displayDims: number[];
+    ovr: OverageBehavior;
+    sig: string;
+    environmentId?: string;
+};
+/**
+ * Verify that a credential binds to a given entitlement — the single
+ * canonical trust-boundary check now that `CompiledEntitlement.sub` no
+ * longer identifies a subject.
+ *
+ * Returns `true` iff `cred.compiledPlanId === ent.compiledPlanId`. The
+ * gateway MUST call this (or an equivalent check) before honoring any
+ * entitlement decision for a given request; relying on `ent.sub` would
+ * miss the case where a stale credential is paired with a newly-compiled
+ * plan for a different subscriber.
+ *
+ * Both arguments are deliberately structurally typed so the helper works
+ * with partial / projected shapes in tests and integration layers
+ * without requiring the full record.
+ */
+export declare function verifyCredentialBindsToEntitlement(cred: {
+    compiledPlanId: string;
+}, ent: {
+    compiledPlanId: string;
+}): boolean;
+//# sourceMappingURL=entitlements.d.ts.map

package/node_modules/@farther-shore/shared-types/dist/entitlements.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entitlements.d.ts","sourceRoot":"","sources":["../src/entitlements.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD,MAAM,MAAM,iBAAiB,GAAG;IAC9B,uBAAuB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,oBAAoB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC/C,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG;IACpC,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,CAAC,EAAE,GAAG,GAAG,GAAG,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IAClC,CAAC,EAAE,MAAM,CAAC;IACV,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;CACb,CAAC;AAEF;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC,CAAC,EAAE,MAAM,CAAC;IACV;;;;;;OAMG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ;;;;OAIG;IACH,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,EAAE,EAAE,MAAM,CAAC;IAEX,EAAE,EAAE,uBAAuB,EAAE,CAAC;IAC9B,EAAE,EAAE,qBAAqB,EAAE,CAAC;IAC5B,EAAE,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC5B,EAAE,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAChC,WAAW,EAAE,MAAM,EAAE,CAAC;IAEtB,GAAG,EAAE,eAAe,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kCAAkC,CAChD,IAAI,EAAE;IAAE,cAAc,EAAE,MAAM,CAAA;CAAE,EAChC,GAAG,EAAE;IAAE,cAAc,EAAE,MAAM,CAAA;CAAE,GAC9B,OAAO,CAMT"}

package/node_modules/@farther-shore/shared-types/dist/entitlements.js

@@ -0,0 +1,30 @@
+// ---------------------------------------------------------------------------
+// Compiled entitlement types — wire format pushed to edge KV
+//
+// v0.14.0 — `planId` renamed to `compiledPlanId` to line up with the new
+// immutable CompiledPlan model. The `sub` (subject) field is retained for
+// audit / correlation but is NO LONGER the KV key (see ./edge-kv-keys.ts);
+// the gateway looks up entitlements by compiledPlanId and then reads the
+// subject off the CredentialRecord.
+// ---------------------------------------------------------------------------
+/**
+ * Verify that a credential binds to a given entitlement — the single
+ * canonical trust-boundary check now that `CompiledEntitlement.sub` no
+ * longer identifies a subject.
+ *
+ * Returns `true` iff `cred.compiledPlanId === ent.compiledPlanId`. The
+ * gateway MUST call this (or an equivalent check) before honoring any
+ * entitlement decision for a given request; relying on `ent.sub` would
+ * miss the case where a stale credential is paired with a newly-compiled
+ * plan for a different subscriber.
+ *
+ * Both arguments are deliberately structurally typed so the helper works
+ * with partial / projected shapes in tests and integration layers
+ * without requiring the full record.
+ */
+export function verifyCredentialBindsToEntitlement(cred, ent) {
+    return (typeof cred.compiledPlanId === "string" &&
+        cred.compiledPlanId.length > 0 &&
+        cred.compiledPlanId === ent.compiledPlanId);
+}
+//# sourceMappingURL=entitlements.js.map

package/node_modules/@farther-shore/shared-types/dist/entitlements.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entitlements.js","sourceRoot":"","sources":["../src/entitlements.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,6DAA6D;AAC7D,EAAE;AACF,yEAAyE;AACzE,0EAA0E;AAC1E,2EAA2E;AAC3E,yEAAyE;AACzE,oCAAoC;AACpC,8EAA8E;AA0E9E;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,kCAAkC,CAChD,IAAgC,EAChC,GAA+B;IAE/B,OAAO,CACL,OAAO,IAAI,CAAC,cAAc,KAAK,QAAQ;QACvC,IAAI,CAAC,cAAc,CAAC,MAAM,GAAG,CAAC;QAC9B,IAAI,CAAC,cAAc,KAAK,GAAG,CAAC,cAAc,CAC3C,CAAC;AACJ,CAAC"}

package/node_modules/@farther-shore/shared-types/dist/enums.d.ts

@@ -0,0 +1,36 @@
+export type PlanType = "FREE" | "FLAT_RATE" | "INCLUDED_USAGE" | "PAY_AS_YOU_GO" | "CONFIGURABLE_USAGE";
+export type ProductStatus = "DRAFT" | "ACTIVE";
+/**
+ * Subscriber status — replaces ConsumerStatus in v0.14.0.
+ * Values kept identical so persisted rows don't need remapping.
+ */
+export type SubscriberStatus = "ONBOARDING" | "ACTIVE" | "SUSPENDED";
+/** Subscriber kind on the `Subscriber` model and wire DTOs. */
+export type SubscriberKind = "INDIVIDUAL" | "ORGANIZATION";
+/** Display ownership for API subscriptions across builder + consumer UIs. */
+export type SubscriptionOwnerType = "personal_organization" | "team_organization";
+export type BillingStrategy = "subscription" | "usage_based" | "hybrid";
+export type ApiKeyStatus = "ACTIVE" | "REVOKED";
+export type AuthStrategy = "API_KEY";
+export type OverageBehavior = "BLOCK" | "ALLOW_AND_BILL";
+export type PlanStatus = "DRAFT" | "ACTIVE" | "ARCHIVED";
+/**
+ * Lifecycle status of a CompiledPlan row.
+ *
+ * Phase A1 (long-horizon API versioning) added `EXPERIMENTAL` and
+ * `LEGACY_STABLE`:
+ *   - `ACTIVE`: the current head new subscribers join
+ *   - `EXPERIMENTAL`: A/B variant of an ACTIVE plan; sticky-assigned
+ *     to a percentage of new subscribers via the variant-assignment
+ *     hash. Promoted to ACTIVE or rolled back to ARCHIVED.
+ *   - `LEGACY_STABLE`: a frozen plan version kept alive for the
+ *     existing subscriber cohort alongside an `ACTIVE` head. Hidden
+ *     from public pricing; new subscribers cannot join.
+ *   - `PHASING_OUT`: a previous ACTIVE that's being migrated to a
+ *     newer version; counts down to SUPERSEDED on count=0.
+ *   - `SUPERSEDED`: empty version retained for audit; flips to
+ *     ARCHIVED after `archiveAfterDays`.
+ *   - `ARCHIVED`: cold storage; KV entry + Stripe Product removed.
+ */
+export type CompiledPlanStatus = "ACTIVE" | "EXPERIMENTAL" | "LEGACY_STABLE" | "PHASING_OUT" | "SUPERSEDED" | "ARCHIVED";
+//# sourceMappingURL=enums.d.ts.map

package/node_modules/@farther-shore/shared-types/dist/enums.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"enums.d.ts","sourceRoot":"","sources":["../src/enums.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,QAAQ,GAChB,MAAM,GACN,WAAW,GACX,gBAAgB,GAChB,eAAe,GACf,oBAAoB,CAAC;AAEzB,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,QAAQ,CAAC;AAE/C;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG,YAAY,GAAG,QAAQ,GAAG,WAAW,CAAC;AAErE,+DAA+D;AAC/D,MAAM,MAAM,cAAc,GAAG,YAAY,GAAG,cAAc,CAAC;AAE3D,6EAA6E;AAC7E,MAAM,MAAM,qBAAqB,GAC7B,uBAAuB,GACvB,mBAAmB,CAAC;AAExB,MAAM,MAAM,eAAe,GAAG,cAAc,GAAG,aAAa,GAAG,QAAQ,CAAC;AAExE,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,SAAS,CAAC;AAEhD,MAAM,MAAM,YAAY,GAAG,SAAS,CAAC;AAErC,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG,gBAAgB,CAAC;AAEzD,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,QAAQ,GAAG,UAAU,CAAC;AAEzD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,kBAAkB,GAC1B,QAAQ,GACR,cAAc,GACd,eAAe,GACf,aAAa,GACb,YAAY,GACZ,UAAU,CAAC"}

package/node_modules/@farther-shore/shared-types/dist/enums.js

@@ -0,0 +1,5 @@
+// ---------------------------------------------------------------------------
+// Canonical enums and union types — single source of truth
+// ---------------------------------------------------------------------------
+export {};
+//# sourceMappingURL=enums.js.map

package/node_modules/@farther-shore/shared-types/dist/enums.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"enums.js","sourceRoot":"","sources":["../src/enums.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,2DAA2D;AAC3D,8EAA8E"}

package/node_modules/@farther-shore/shared-types/dist/format.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Format cents as a dollar string.
+ * @example formatPrice(2999) → "$29.99"
+ * @example formatPrice(0) → "$0"
+ * @example formatPrice(1000) → "$10"
+ */
+export declare function formatPrice(cents: number): string;
+//# sourceMappingURL=format.d.ts.map

package/node_modules/@farther-shore/shared-types/dist/format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../src/format.ts"],"names":[],"mappings":"AAIA;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAGjD"}

package/node_modules/@farther-shore/shared-types/dist/format.js

@@ -0,0 +1,14 @@
+// ---------------------------------------------------------------------------
+// Shared formatting utilities — single source of truth
+// ---------------------------------------------------------------------------
+/**
+ * Format cents as a dollar string.
+ * @example formatPrice(2999) → "$29.99"
+ * @example formatPrice(0) → "$0"
+ * @example formatPrice(1000) → "$10"
+ */
+export function formatPrice(cents) {
+    const dollars = cents / 100;
+    return dollars % 1 === 0 ? `$${dollars}` : `$${dollars.toFixed(2)}`;
+}
+//# sourceMappingURL=format.js.map

package/node_modules/@farther-shore/shared-types/dist/format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.js","sourceRoot":"","sources":["../src/format.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,uDAAuD;AACvD,8EAA8E;AAE9E;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,KAAa;IACvC,MAAM,OAAO,GAAG,KAAK,GAAG,GAAG,CAAC;IAC5B,OAAO,OAAO,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,OAAO,EAAE,CAAC,CAAC,CAAC,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;AACtE,CAAC"}

package/node_modules/@farther-shore/shared-types/dist/index.d.ts

@@ -0,0 +1,24 @@
+export * from "./enums.js";
+export * from "./metering.js";
+export * from "./limits.js";
+export * from "./entitlements.js";
+export * from "./billing.js";
+export * from "./base.js";
+export * from "./projections.js";
+export * from "./api.js";
+export * from "./format.js";
+export * from "./web-ui.js";
+export * from "./builder-context.js";
+export * from "./portal.js";
+export * from "./admin.js";
+export * from "./consumer.js";
+export * from "./edge-kv-keys.js";
+export * from "./pricing-model.js";
+export * from "./scope-matcher.js";
+export * from "./service-auth.js";
+export * from "./analytics.js";
+export * from "./dlq.js";
+export * from "./auth/permissions.js";
+export * from "./webhooks/events.js";
+export * from "./webhooks/migration.js";
+//# sourceMappingURL=index.d.ts.map

package/node_modules/@farther-shore/shared-types/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAClC,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC;AAC1B,cAAc,kBAAkB,CAAC;AACjC,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,sBAAsB,CAAC;AACrC,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,UAAU,CAAC;AACzB,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,yBAAyB,CAAC"}