@supersolutions/super-router-core 0.0.0 → 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,14 @@
+SuperRouter
+Copyright 2026 SUPER SOLUTION LABS INC
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/dist/credit-rates.d.ts

@@ -0,0 +1,173 @@
+import { z, Price, type Principal, type Service } from "@supersolutions/super-router-contracts";
+/** Credits are a fixed accounting unit. Developers configure units per credit, never the scale. */
+export declare const CREDIT_ATOMS = 1000000000n;
+export declare const CreditRateConfig: z.ZodObject<{
+    asset: z.ZodString;
+    tokens: z.ZodOptional<z.ZodObject<{
+        input: z.ZodObject<{
+            units: z.ZodString;
+            credits: z.ZodDefault<z.ZodString>;
+        }, z.core.$strict>;
+        cached: z.ZodObject<{
+            units: z.ZodString;
+            credits: z.ZodDefault<z.ZodString>;
+        }, z.core.$strict>;
+        cache_write: z.ZodObject<{
+            units: z.ZodString;
+            credits: z.ZodDefault<z.ZodString>;
+        }, z.core.$strict>;
+        output: z.ZodObject<{
+            units: z.ZodString;
+            credits: z.ZodDefault<z.ZodString>;
+        }, z.core.$strict>;
+    }, z.core.$strict>>;
+    media: z.ZodOptional<z.ZodObject<{
+        images: z.ZodOptional<z.ZodObject<{
+            units: z.ZodString;
+            credits: z.ZodDefault<z.ZodString>;
+        }, z.core.$strict>>;
+        video_ms: z.ZodOptional<z.ZodObject<{
+            units: z.ZodString;
+            credits: z.ZodDefault<z.ZodString>;
+        }, z.core.$strict>>;
+        audio_ms: z.ZodOptional<z.ZodObject<{
+            units: z.ZodString;
+            credits: z.ZodDefault<z.ZodString>;
+        }, z.core.$strict>>;
+        tasks: z.ZodOptional<z.ZodObject<{
+            units: z.ZodString;
+            credits: z.ZodDefault<z.ZodString>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type CreditRateConfig = z.input<typeof CreditRateConfig>;
+/** Compile exact rational units-per-credit to existing wire Price. Token mode requires all four categories; media categories are explicit. */
+export declare function compileCreditPrice(raw: unknown): Price;
+export interface CreditRatePublisher {
+    getService(p: Principal, id: string, version?: number): Promise<Service>;
+    publish(p: Principal, service: unknown, mode?: "cloud" | "self-host", expectedVersion?: number): Promise<Service | undefined>;
+}
+/** Atomically advance only the customer-sale price; supply and platform prices remain server snapshots. */
+export declare function publishCreditRateVersion(store: CreditRatePublisher, p: Principal, id: string, expectedVersion: number, config: unknown, mode?: "cloud" | "self-host"): Promise<{
+    version: number;
+    price: {
+        asset: string;
+        input: string;
+        cached: string;
+        cache_write: string;
+        output: string;
+        per: number;
+        media?: {
+            images?: {
+                atoms: string;
+                per: number;
+            } | undefined;
+            video_ms?: {
+                atoms: string;
+                per: number;
+            } | undefined;
+            audio_ms?: {
+                atoms: string;
+                per: number;
+            } | undefined;
+            tasks?: {
+                atoms: string;
+                per: number;
+            } | undefined;
+        } | undefined;
+    };
+    id: string;
+    mode: "tier" | "specific" | "pool";
+    offerings: {
+        id: string;
+        provider: string;
+        model: string;
+        upstream_model: string;
+        region: string;
+        labels: string[];
+        enabled: boolean;
+        source: "platform" | "byok";
+        max_input_tokens: number;
+        max_output_tokens: number;
+        price: {
+            asset: string;
+            input: string;
+            cached: string;
+            cache_write: string;
+            output: string;
+            per: number;
+            media?: {
+                images?: {
+                    atoms: string;
+                    per: number;
+                } | undefined;
+                video_ms?: {
+                    atoms: string;
+                    per: number;
+                } | undefined;
+                audio_ms?: {
+                    atoms: string;
+                    per: number;
+                } | undefined;
+                tasks?: {
+                    atoms: string;
+                    per: number;
+                } | undefined;
+            } | undefined;
+        };
+        task_kind?: "image" | "video" | "audio" | "task" | undefined;
+        max_usage?: {
+            images?: number | undefined;
+            video_ms?: number | undefined;
+            audio_ms?: number | undefined;
+            tasks?: number | undefined;
+        } | undefined;
+        latency_ms?: number | undefined;
+        reliability?: number | undefined;
+        quality?: number | undefined;
+    }[];
+    regions: string[];
+    required_labels: string[];
+    max_attempts: number;
+    max_provider_cost: string;
+    max_output_tokens: number;
+    weights: {
+        cost: number;
+        latency: number;
+        reliability: number;
+        quality: number;
+    };
+    cost_scale: string;
+    latency_scale_ms: number;
+    unknown_score: number;
+    task_kind?: "image" | "video" | "audio" | "task" | undefined;
+    model?: string | undefined;
+    tier?: string | undefined;
+    platform_price?: {
+        asset: string;
+        input: string;
+        cached: string;
+        cache_write: string;
+        output: string;
+        per: number;
+        media?: {
+            images?: {
+                atoms: string;
+                per: number;
+            } | undefined;
+            video_ms?: {
+                atoms: string;
+                per: number;
+            } | undefined;
+            audio_ms?: {
+                atoms: string;
+                per: number;
+            } | undefined;
+            tasks?: {
+                atoms: string;
+                per: number;
+            } | undefined;
+        } | undefined;
+    } | undefined;
+    requires_subscription?: boolean | undefined;
+}>;

package/dist/credit-rates.js

@@ -0,0 +1,121 @@
+import { z, Price, RouterError, } from "@supersolutions/super-router-contracts";
+/** Credits are a fixed accounting unit. Developers configure units per credit, never the scale. */
+export const CREDIT_ATOMS = 1000000000n;
+const integer = z.string().regex(/^[1-9][0-9]{0,29}$/);
+const ratio = z
+    .object({ units: integer, credits: integer.default("1") })
+    .strict();
+export const CreditRateConfig = z
+    .object({
+    asset: z
+        .string()
+        .min(1)
+        .max(120)
+        .regex(/^[a-zA-Z0-9_.:/-]+$/),
+    tokens: z
+        .object({
+        input: ratio,
+        cached: ratio,
+        cache_write: ratio,
+        output: ratio,
+    })
+        .strict()
+        .optional(),
+    media: z
+        .object({
+        images: ratio.optional(),
+        video_ms: ratio.optional(),
+        audio_ms: ratio.optional(),
+        tasks: ratio.optional(),
+    })
+        .strict()
+        .optional(),
+})
+    .strict();
+const tokenKeys = ["input", "cached", "cache_write", "output"];
+const mediaKeys = ["images", "video_ms", "audio_ms", "tasks"];
+function gcd(a, b) {
+    while (b) {
+        [a, b] = [b, a % b];
+    }
+    return a;
+}
+function rate(value) {
+    const numerator = CREDIT_ATOMS * BigInt(value.credits), denominator = BigInt(value.units), g = gcd(numerator, denominator);
+    return { numerator: numerator / g, denominator: denominator / g };
+}
+/** Compile exact rational units-per-credit to existing wire Price. Token mode requires all four categories; media categories are explicit. */
+export function compileCreditPrice(raw) {
+    const parsed = CreditRateConfig.safeParse(raw);
+    if (!parsed.success)
+        throw new RouterError("invalid_credit_rates");
+    const config = parsed.data;
+    if ((!config.tokens && !mediaKeys.some((k) => config.media?.[k])) ||
+        (config.tokens && tokenKeys.some((k) => !config.tokens?.[k])))
+        throw new RouterError("invalid_credit_rates");
+    const rates = tokenKeys.map((key) => config.tokens?.[key]
+        ? rate(config.tokens[key])
+        : { numerator: 0n, denominator: 1n });
+    let per = 1n;
+    for (const r of rates) {
+        per = (per / gcd(per, r.denominator)) * r.denominator;
+        if (per > 1000000000n)
+            throw new RouterError("unsupported_rate_precision", 422);
+    }
+    const tokens = Object.fromEntries(tokenKeys.map((key, i) => [
+        key,
+        (rates[i].numerator * (per / rates[i].denominator)).toString(),
+    ]));
+    const media = {};
+    for (const key of mediaKeys) {
+        const value = config.media?.[key];
+        if (!value)
+            continue;
+        const r = rate(value);
+        if (r.denominator > 1000000000n)
+            throw new RouterError("unsupported_rate_precision", 422);
+        media[key] = { atoms: r.numerator.toString(), per: Number(r.denominator) };
+    }
+    const compiled = Price.safeParse({
+        asset: config.asset,
+        ...tokens,
+        per: Number(per),
+        ...(Object.keys(media).length ? { media } : {}),
+    });
+    if (!compiled.success)
+        throw new RouterError("unsupported_rate_precision", 422);
+    return compiled.data;
+}
+/** Atomically advance only the customer-sale price; supply and platform prices remain server snapshots. */
+export async function publishCreditRateVersion(store, p, id, expectedVersion, config, mode = "self-host") {
+    if (!p.scopes.includes("service:write"))
+        throw new RouterError("scope_denied", 403);
+    if (!Number.isSafeInteger(expectedVersion) ||
+        expectedVersion < 1 ||
+        expectedVersion >= Number.MAX_SAFE_INTEGER)
+        throw new RouterError("invalid_service_version");
+    const current = await store.getService(p, id);
+    if (current.version !== expectedVersion)
+        throw new RouterError("service_version_conflict", 409);
+    const price = compileCreditPrice(config);
+    const parsedConfig = CreditRateConfig.parse(config);
+    const requiredMeter = current.task_kind
+        ? {
+            image: "images",
+            video: "video_ms",
+            audio: "audio_ms",
+            task: "tasks",
+        }[current.task_kind]
+        : undefined;
+    if (requiredMeter
+        ? !parsedConfig.media?.[requiredMeter] ||
+            !!parsedConfig.tokens ||
+            mediaKeys.some((k) => k !== requiredMeter && !!parsedConfig.media?.[k])
+        : !parsedConfig.tokens || !!parsedConfig.media)
+        throw new RouterError("credit_rate_kind_mismatch", 422);
+    if (price.asset !== current.price.asset)
+        throw new RouterError("credit_asset_mismatch", 422);
+    const next = { ...current, version: current.version + 1, price };
+    await store.publish(p, next, mode, expectedVersion);
+    return next;
+}

package/dist/index.d.ts

@@ -0,0 +1,264 @@
+import { Invocation, Service, RouterError, type Principal, type Provider, type Offering, type Usage, type Price, type StreamEvent } from "@supersolutions/super-router-contracts";
+export { RouterError };
+export interface Leg {
+    kind: "customer_sale" | "platform_sale";
+    account: string;
+    price: Price;
+    reserved: string;
+}
+export interface RequestRecord {
+    id: string;
+    workspace: string;
+    environment: string;
+    customer: string;
+    service: Service;
+    execution: string;
+    billing: string;
+    cancel_requested: boolean;
+    output_started: boolean;
+    deadline: string;
+    legs: Leg[];
+    provider_spent: string;
+}
+export interface Store {
+    replay(p: Principal, key: string, digest: string): Promise<RequestRecord | null>;
+    getService(p: Principal, id: string, version?: number): Promise<Service>;
+    accounts(p: Principal, service: Service): Promise<Leg[]>;
+    reserve(p: Principal, key: string, digest: string, service: Service, legs: Leg[], deadline: string, decision?: unknown): Promise<{
+        request: RequestRecord;
+        fresh: boolean;
+    }>;
+    get(p: Principal, id: string): Promise<RequestRecord>;
+    begin(p: Principal, id: string, offering: Offering, bound: string): Promise<string>;
+    output(p: Principal, id: string): Promise<void>;
+    attemptResult(p: Principal, id: string, attempt: string, status: string, usage: Usage | null, cost: string | null, upstream?: string): Promise<void>;
+    finish(p: Principal, id: string, execution: string, usage: Usage | null, pending: boolean): Promise<void>;
+    cancel(p: Principal, id: string): Promise<void>;
+}
+export interface BalanceRow {
+    id: string;
+    kind: string;
+    asset: string;
+    balance: string;
+    held: string;
+    available: string;
+}
+/** A source of epoch milliseconds. Stores and the router accept one so tests and conformance runs control time. */
+export type Clock = () => number;
+/**
+ * Everything the data-plane server and worker need from storage, beyond the router's own {@link Store} port.
+ * Implement this to plug in another database; run the store contract suite against it.
+ */
+export interface DataStore extends Store {
+    publish(p: Principal, service: unknown, mode?: "cloud" | "self-host", expectedVersion?: number): Promise<Service | undefined>;
+    list(p: Principal): Promise<Service[]>;
+    balance(p: Principal): Promise<BalanceRow[]>;
+    grant(p: Principal, kind: "customer_sale" | "platform_sale", asset: string, amount: string, source: string, expires?: Date): Promise<string>;
+    disable(p: Principal, offering: string): Promise<void>;
+    /** Settle or release expired reservations. Returns how many requests were processed. */
+    recover(): Promise<number>;
+    /** Optional operator view: recent requests with attempts and settled amounts. */
+    recent?(p: Principal, limit?: number, customer?: string): Promise<RecentRequest[]>;
+}
+export interface RecentRequest {
+    id: string;
+    customer: string;
+    service: string;
+    service_version: number;
+    execution: string;
+    billing: string;
+    provider_cost: string;
+    created_at: Date;
+    attempts: {
+        offering: string;
+        status: string;
+        cost: string | null;
+        usage: unknown;
+    }[];
+    settled: Record<string, string>;
+}
+export declare const mediaKeys: readonly ["images", "video_ms", "audio_ms", "tasks"];
+export declare const kindMeter: {
+    readonly image: "images";
+    readonly video: "video_ms";
+    readonly audio: "audio_ms";
+    readonly task: "tasks";
+};
+export declare function charge(usage: Usage, price: Price): bigint;
+export declare function bound(input: number, output: number, price: Price): bigint;
+/** The canonical JSON of a value: object keys sorted, no whitespace. It is the input of the idempotency digest. */
+export declare function canonical(value: unknown): string;
+export declare function route(service: Service, input: Invocation): {
+    candidates: {
+        offering: {
+            id: string;
+            provider: string;
+            model: string;
+            upstream_model: string;
+            region: string;
+            labels: string[];
+            enabled: boolean;
+            source: "platform" | "byok";
+            max_input_tokens: number;
+            max_output_tokens: number;
+            price: {
+                asset: string;
+                input: string;
+                cached: string;
+                cache_write: string;
+                output: string;
+                per: number;
+                media?: {
+                    images?: {
+                        atoms: string;
+                        per: number;
+                    } | undefined;
+                    video_ms?: {
+                        atoms: string;
+                        per: number;
+                    } | undefined;
+                    audio_ms?: {
+                        atoms: string;
+                        per: number;
+                    } | undefined;
+                    tasks?: {
+                        atoms: string;
+                        per: number;
+                    } | undefined;
+                } | undefined;
+            };
+            task_kind?: "image" | "video" | "audio" | "task" | undefined;
+            max_usage?: {
+                images?: number | undefined;
+                video_ms?: number | undefined;
+                audio_ms?: number | undefined;
+                tasks?: number | undefined;
+            } | undefined;
+            latency_ms?: number | undefined;
+            reliability?: number | undefined;
+            quality?: number | undefined;
+        };
+        cost: bigint;
+        score: number;
+    }[];
+    excluded: {
+        id: string;
+        reason: string;
+    }[];
+};
+export declare class Router {
+    store: Store;
+    private providers;
+    private digestKey;
+    private clock;
+    constructor(store: Store, providers: Record<string, Provider>, digestKey: string, clock?: Clock);
+    /** Own providers only: an offering may name its provider `constructor` or `toString`, which `providers[name]` finds on Object.prototype. */
+    private providerFor;
+    infer(principal: Principal, raw: unknown, key: string, emit?: (event: StreamEvent) => Promise<void>, signal?: AbortSignal): Promise<{
+        replayed: boolean;
+        id: string;
+        execution_status: string;
+        billing_status: string;
+        service_version?: undefined;
+        model?: undefined;
+        tier?: undefined;
+        output?: undefined;
+        usage?: undefined;
+        billing?: undefined;
+    } | {
+        id: string;
+        execution_status: string;
+        billing_status: string;
+        service_version: number;
+        model: string | undefined;
+        tier: string | undefined;
+        output: {
+            role: string;
+            content: string;
+        };
+        usage: {
+            status: string;
+            meters: {
+                input: number;
+                cached: number;
+                cache_write: number;
+                output: number;
+                images?: number | undefined;
+                video_ms?: number | undefined;
+                audio_ms?: number | undefined;
+                tasks?: number | undefined;
+            };
+        } | {
+            status: string;
+            meters?: undefined;
+        };
+        billing: {
+            charges: {
+                kind: "customer_sale" | "platform_sale";
+                asset: string;
+                atoms: string;
+                scale: number;
+            }[];
+        };
+        replayed?: undefined;
+    }>;
+}
+export declare class MockProvider implements Provider {
+    private behavior;
+    private delay;
+    calls: number;
+    constructor(behavior?: "success" | "reject" | "unknown" | "partial", delay?: number);
+    invoke(input: Invocation, _offering: Offering, signal: AbortSignal): AsyncGenerator<{
+        type: "delta";
+        text: string;
+        usage?: undefined;
+        upstream_id?: undefined;
+    } | {
+        type: "usage";
+        usage: {
+            input: number;
+            cached: number;
+            cache_write: number;
+            output: number;
+        };
+        upstream_id: `${string}-${string}-${string}-${string}-${string}`;
+        text?: undefined;
+    } | {
+        type: "done";
+        text?: undefined;
+        usage?: undefined;
+        upstream_id?: undefined;
+    }, void, unknown>;
+}
+/** Simulated bounded task adapter. Produces a receipt, never actual image/video/audio. */
+export declare class MockTaskProvider implements Provider {
+    private behavior;
+    calls: number;
+    constructor(behavior?: "success" | "reject" | "unknown" | "partial");
+    invoke(input: Invocation, offering: Offering, signal: AbortSignal): AsyncGenerator<{
+        type: "delta";
+        text: string;
+        usage?: undefined;
+        upstream_id?: undefined;
+        completion?: undefined;
+    } | {
+        type: "usage";
+        usage: {
+            [x: string]: number;
+            input: number;
+            cached: number;
+            cache_write: number;
+            output: number;
+        };
+        upstream_id: `${string}-${string}-${string}-${string}-${string}`;
+        text?: undefined;
+        completion?: undefined;
+    } | {
+        type: "done";
+        completion: "succeeded" | "partial";
+        text?: undefined;
+        usage?: undefined;
+        upstream_id?: undefined;
+    }, void, unknown>;
+}
+export * from "./credit-rates.js";

package/dist/index.js

@@ -0,0 +1,448 @@
+import { createHmac, randomUUID } from "node:crypto";
+import { Invocation, Meters, RouterError, ProviderError, } from "@supersolutions/super-router-contracts";
+export { RouterError };
+export const mediaKeys = ["images", "video_ms", "audio_ms", "tasks"];
+export const kindMeter = {
+    image: "images",
+    video: "video_ms",
+    audio: "audio_ms",
+    task: "tasks",
+};
+export function charge(usage, price) {
+    const numerator = ["input", "cached", "cache_write", "output"].reduce((sum, key) => sum + BigInt(usage[key]) * BigInt(price[key]), 0n);
+    let total = (numerator + BigInt(price.per) - 1n) / BigInt(price.per);
+    for (const key of mediaKeys) {
+        const units = usage[key] ?? 0;
+        const rate = price.media?.[key];
+        if (units && !rate)
+            throw new RouterError("unpriced_meter", 422);
+        if (rate)
+            total +=
+                (BigInt(units) * BigInt(rate.atoms) + BigInt(rate.per) - 1n) /
+                    BigInt(rate.per);
+    }
+    return total;
+}
+function invocationBound(input, maxInput, price) {
+    if (!input.input.task)
+        return bound(maxInput, input.limits.max_output_tokens, price);
+    return charge({
+        input: 0,
+        cached: 0,
+        cache_write: 0,
+        output: 0,
+        ...input.limits.max_usage,
+    }, price);
+}
+export function bound(input, output, price) {
+    const rate = [price.input, price.cached, price.cache_write]
+        .map(BigInt)
+        .reduce((a, b) => (a > b ? a : b));
+    return ((BigInt(input) * rate +
+        BigInt(output) * BigInt(price.output) +
+        BigInt(price.per) -
+        1n) /
+        BigInt(price.per));
+}
+/** The canonical JSON of a value: object keys sorted, no whitespace. It is the input of the idempotency digest. */
+export function canonical(value) {
+    if (Array.isArray(value))
+        return "[" + value.map(canonical).join(",") + "]";
+    if (value && typeof value === "object")
+        return ("{" +
+            Object.entries(value)
+                .sort(([a], [b]) => a.localeCompare(b))
+                .map(([k, v]) => JSON.stringify(k) + ":" + canonical(v))
+                .join(",") +
+            "}");
+    return JSON.stringify(value);
+}
+export function route(service, input) {
+    const excluded = [];
+    const candidates = service.offerings
+        .flatMap((o) => {
+        let reason = "";
+        if (o.task_kind !== input.input.task?.kind ||
+            service.task_kind !== input.input.task?.kind)
+            reason = "task_kind_mismatch";
+        else if (!o.enabled)
+            reason = "disabled";
+        else if (service.mode === "specific" && o.model !== service.model)
+            reason = "model_mismatch";
+        else if (!service.regions.includes(o.region))
+            reason = "region_mismatch";
+        else if (service.required_labels.some((x) => !o.labels.includes(x)))
+            reason = "label_mismatch";
+        else if (input.limits.max_output_tokens > o.max_output_tokens)
+            reason = "output_limit";
+        if (!reason && input.input.task) {
+            const key = kindMeter[input.input.task.kind];
+            const units = input.limits.max_usage?.[key];
+            if (!units ||
+                units > (o.max_usage?.[key] ?? 0) ||
+                !o.price.media?.[key])
+                reason = "meter_limit";
+        }
+        const cost = reason
+            ? 0n
+            : invocationBound(input, o.max_input_tokens, o.price);
+        if (!reason && cost > BigInt(service.max_provider_cost))
+            reason = "budget_exceeded";
+        if (reason) {
+            excluded.push({ id: o.id, reason });
+            return [];
+        }
+        const ratio = Number((cost * 1000000n) / BigInt(service.cost_scale)) / 1_000_000;
+        const score = service.weights.cost * (1 - Math.min(1, ratio)) +
+            service.weights.latency *
+                (o.latency_ms === undefined
+                    ? service.unknown_score
+                    : 1 - Math.min(1, o.latency_ms / service.latency_scale_ms)) +
+            service.weights.reliability * (o.reliability ?? service.unknown_score) +
+            service.weights.quality * (o.quality ?? service.unknown_score);
+        return [{ offering: o, cost, score }];
+    })
+        .sort((a, b) => b.score - a.score || a.offering.id.localeCompare(b.offering.id));
+    return { candidates, excluded };
+}
+export class Router {
+    store;
+    providers;
+    digestKey;
+    clock;
+    constructor(store, providers, digestKey, clock = Date.now) {
+        this.store = store;
+        this.providers = providers;
+        this.digestKey = digestKey;
+        this.clock = clock;
+        if (digestKey.length < 32)
+            throw new Error("digest key must be >=32 characters");
+    }
+    /** Own providers only: an offering may name its provider `constructor` or `toString`, which `providers[name]` finds on Object.prototype. */
+    providerFor(name) {
+        return Object.hasOwn(this.providers, name)
+            ? this.providers[name]
+            : undefined;
+    }
+    async infer(principal, raw, key, emit, signal) {
+        if (!principal.scopes.includes("invoke"))
+            throw new RouterError("scope_denied", 403);
+        const parsed = Invocation.safeParse(raw);
+        if (!parsed.success)
+            throw new RouterError("invalid_request", 400);
+        const input = parsed.data;
+        if (input.input.task) {
+            const meter = kindMeter[input.input.task.kind];
+            const limits = input.limits.max_usage;
+            if (input.input.messages.length ||
+                !limits?.[meter] ||
+                mediaKeys.some((k) => k !== meter && (limits[k] ?? 0) !== 0) ||
+                (meter === "tasks" && limits.tasks !== 1))
+                throw new RouterError("invalid_task_limits", 400);
+        }
+        else if (!input.input.messages.length || input.limits.max_usage)
+            throw new RouterError("invalid_request", 400);
+        if (principal.service_ids && !principal.service_ids.includes(input.service))
+            throw new RouterError("scope_denied", 403);
+        if (input.customer_id !== principal.customer)
+            throw new RouterError("scope_denied", 403);
+        if (!key || key.length > 200)
+            throw new RouterError("missing_idempotency_key", 400);
+        const digest = createHmac("sha256", this.digestKey)
+            .update(canonical(input))
+            .digest("hex");
+        const existing = await this.store.replay(principal, key, digest);
+        if (existing)
+            return {
+                replayed: true,
+                id: existing.id,
+                execution_status: existing.execution,
+                billing_status: existing.billing,
+            };
+        const service = await this.store.getService(principal, input.service, input.service_version);
+        if (input.service_version !== undefined) {
+            const active = await this.store.getService(principal, input.service);
+            if (active.version !== service.version)
+                throw new RouterError("inactive_service_version", 409);
+        }
+        if (input.limits.max_output_tokens > service.max_output_tokens)
+            throw new RouterError("unsupported_capability", 422);
+        const decision = route(service, input);
+        if (!decision.candidates.length)
+            throw new RouterError("no_eligible_offering", 422);
+        if (decision.candidates.some((c) => !this.providerFor(c.offering.provider)))
+            throw new RouterError("provider_unavailable", 503);
+        const maxInput = Math.max(...decision.candidates.map((c) => c.offering.max_input_tokens));
+        const legs = await this.store.accounts(principal, service);
+        for (const leg of legs) {
+            leg.reserved = invocationBound(input, maxInput, leg.price).toString();
+            if (leg.kind === "customer_sale" &&
+                input.limits.max_charge &&
+                (input.limits.max_charge.asset !== leg.price.asset ||
+                    BigInt(input.limits.max_charge.atoms) < BigInt(leg.reserved)))
+                throw new RouterError("budget_exceeded", 402);
+        }
+        const reservation = await this.store.reserve(principal, key, digest, service, legs, new Date(this.clock() + input.limits.timeout_ms).toISOString(), {
+            excluded: decision.excluded,
+            candidates: decision.candidates.map((c) => ({
+                id: c.offering.id,
+                score: c.score,
+                cost: c.cost.toString(),
+            })),
+        });
+        const request = reservation.request;
+        if (!reservation.fresh)
+            return {
+                replayed: true,
+                id: request.id,
+                execution_status: request.execution,
+                billing_status: request.billing,
+            };
+        let seq = 0, text = "", started = false, finalUsage = null, execution = "failed", pending = false, lastModel;
+        const send = async (type, data = {}) => {
+            await emit?.({ type, request_id: request.id, sequence: ++seq, ...data });
+        };
+        const controller = new AbortController();
+        const abort = () => controller.abort();
+        signal?.addEventListener("abort", abort, { once: true });
+        if (signal?.aborted)
+            abort();
+        const timeout = setTimeout(abort, input.limits.timeout_ms);
+        let polling = false;
+        const poll = setInterval(() => {
+            if (polling)
+                return;
+            polling = true;
+            void this.store
+                .get(principal, request.id)
+                .then((r) => {
+                if (r.cancel_requested)
+                    abort();
+            })
+                .catch(abort)
+                .finally(() => {
+                polling = false;
+            });
+        }, 100);
+        poll.unref();
+        try {
+            await send("request.started", { service_version: service.version });
+            for (const candidate of decision.candidates.slice(0, service.max_attempts)) {
+                if (controller.signal.aborted) {
+                    execution = "cancelled";
+                    break;
+                }
+                const provider = this.providerFor(candidate.offering.provider);
+                if (!provider)
+                    throw new RouterError("provider_unavailable", 503);
+                let attempt;
+                try {
+                    attempt = await this.store.begin(principal, request.id, candidate.offering, candidate.cost.toString());
+                }
+                catch (e) {
+                    if (e instanceof RouterError &&
+                        ["budget_exceeded", "connection_disabled", "cancelled"].includes(e.code)) {
+                        execution = e.code === "cancelled" ? "cancelled" : "failed";
+                        continue;
+                    }
+                    throw e;
+                }
+                let usage = null, upstream, done = false, completion = "succeeded";
+                lastModel = candidate.offering.model;
+                try {
+                    for await (const event of provider.invoke(input, candidate.offering, controller.signal)) {
+                        if (event.type === "delta") {
+                            if (!started) {
+                                await this.store.output(principal, request.id);
+                                started = true;
+                            }
+                            text += event.text;
+                            if (Buffer.byteLength(text) > 1_000_000)
+                                throw new ProviderError(false, false, "output_too_large");
+                            await send("output.delta", { text: event.text });
+                        }
+                        else if (event.type === "usage") {
+                            const parsedUsage = Meters.safeParse(event.usage);
+                            if (!parsedUsage.success)
+                                throw new ProviderError(false, false, "invalid_usage");
+                            usage = parsedUsage.data;
+                            upstream = event.upstream_id;
+                        }
+                        else {
+                            done = true;
+                            completion = event.completion ?? "succeeded";
+                        }
+                    }
+                    if (!done || !usage)
+                        throw new ProviderError(false, false, "usage_unknown");
+                    if (input.input.task) {
+                        const meter = kindMeter[input.input.task.kind];
+                        if (["input", "cached", "cache_write", "output"].some((k) => usage[k] !== 0) ||
+                            mediaKeys.some((k) => (usage[k] ?? 0) > (input.limits.max_usage?.[k] ?? 0)) ||
+                            (meter === "tasks" &&
+                                usage.tasks !== (completion === "succeeded" ? 1 : 0))) {
+                            usage = null;
+                            throw new ProviderError(false, false, "usage_out_of_bounds");
+                        }
+                    }
+                    else if (mediaKeys.some((k) => (usage[k] ?? 0) !== 0)) {
+                        usage = null;
+                        throw new ProviderError(false, false, "unexpected_meter");
+                    }
+                    await this.store.attemptResult(principal, request.id, attempt, completion, usage, charge(usage, candidate.offering.price).toString(), upstream);
+                    finalUsage = usage;
+                    execution = completion;
+                    pending = charge(usage, candidate.offering.price) > candidate.cost;
+                    break;
+                }
+                catch (e) {
+                    const definitive = e instanceof ProviderError && e.definitive && !started;
+                    await this.store.attemptResult(principal, request.id, attempt, definitive ? "failed" : "unknown", usage, usage
+                        ? charge(usage, candidate.offering.price).toString()
+                        : definitive
+                            ? "0"
+                            : null, upstream);
+                    if (!definitive) {
+                        pending = true;
+                        execution = started ? "partial" : "unknown";
+                        break;
+                    }
+                    if (!(e instanceof ProviderError && e.retryable))
+                        break;
+                }
+            }
+            await this.store.finish(principal, request.id, execution, finalUsage, pending);
+            const settled = await this.store.get(principal, request.id);
+            await send(execution === "succeeded" ? "request.completed" : "request.failed", { execution_status: execution, billing_status: settled.billing });
+            return {
+                id: request.id,
+                execution_status: execution,
+                billing_status: settled.billing,
+                service_version: service.version,
+                model: lastModel,
+                tier: service.tier,
+                output: { role: "assistant", content: text },
+                usage: finalUsage
+                    ? { status: "confirmed", meters: finalUsage }
+                    : {
+                        status: settled.billing === "released" ? "not_billable" : "pending",
+                    },
+                billing: {
+                    charges: finalUsage && settled.billing === "settled"
+                        ? legs
+                            .filter((l) => l.kind === "customer_sale" ||
+                            principal.scopes.includes("billing:read"))
+                            .map((l) => ({
+                            kind: l.kind,
+                            asset: l.price.asset,
+                            atoms: charge(finalUsage, l.price).toString(),
+                            scale: 9,
+                        }))
+                        : [],
+                },
+            };
+        }
+        catch (e) {
+            // Unexpected storage/transport failure must never turn an uncertain dispatch into a refund.
+            await this.store
+                .finish(principal, request.id, started ? "partial" : "unknown", null, true)
+                .catch(() => { });
+            const failure = e instanceof RouterError
+                ? e
+                : new RouterError("execution_unknown", 503, false);
+            failure.request_id = request.id;
+            throw failure;
+        }
+        finally {
+            clearTimeout(timeout);
+            clearInterval(poll);
+            signal?.removeEventListener("abort", abort);
+        }
+    }
+}
+export class MockProvider {
+    behavior;
+    delay;
+    calls = 0;
+    constructor(behavior = "success", delay = 0) {
+        this.behavior = behavior;
+        this.delay = delay;
+    }
+    async *invoke(input, _offering, signal) {
+        this.calls++;
+        if (input.input.task)
+            throw new ProviderError(true, false, "unsupported_task");
+        if (this.delay)
+            await new Promise((resolve, reject) => {
+                const t = setTimeout(resolve, this.delay);
+                signal.addEventListener("abort", () => {
+                    clearTimeout(t);
+                    reject(new ProviderError(false, false));
+                }, { once: true });
+            });
+        if (this.behavior === "reject")
+            throw new ProviderError(true, true, "rate_limited");
+        if (this.behavior === "unknown" || signal.aborted)
+            throw new ProviderError(false, false);
+        yield { type: "delta", text: "Hello from SuperRouter." };
+        if (this.behavior === "partial")
+            throw new ProviderError(false, false);
+        yield {
+            type: "usage",
+            usage: {
+                input: 10,
+                cached: 0,
+                cache_write: 0,
+                output: Math.min(5, input.limits.max_output_tokens),
+            },
+            upstream_id: randomUUID(),
+        };
+        yield { type: "done" };
+    }
+}
+/** Simulated bounded task adapter. Produces a receipt, never actual image/video/audio. */
+export class MockTaskProvider {
+    behavior;
+    calls = 0;
+    constructor(behavior = "success") {
+        this.behavior = behavior;
+    }
+    async *invoke(input, offering, signal) {
+        this.calls++;
+        const task = input.input.task;
+        if (!task || task.kind !== offering.task_kind || this.behavior === "reject")
+            throw new ProviderError(true, false, "unsupported_task");
+        if (signal.aborted || this.behavior === "unknown")
+            throw new ProviderError(false, false, "usage_unknown");
+        const meter = kindMeter[task.kind];
+        const units = input.limits.max_usage?.[meter] ?? 0;
+        if (!units || units > (offering.max_usage?.[meter] ?? 0))
+            throw new ProviderError(true, false, "meter_limit");
+        const partial = this.behavior === "partial";
+        const completed = partial
+            ? meter === "tasks"
+                ? 0
+                : Math.floor(units / 2)
+            : units;
+        yield {
+            type: "delta",
+            text: `Simulated ${task.kind} task receipt; no media generated.`,
+        };
+        yield {
+            type: "usage",
+            usage: {
+                input: 0,
+                cached: 0,
+                cache_write: 0,
+                output: 0,
+                [meter]: completed,
+            },
+            upstream_id: randomUUID(),
+        };
+        yield {
+            type: "done",
+            completion: partial ? "partial" : "succeeded",
+        };
+    }
+}
+export * from "./credit-rates.js";

package/package.json

@@ -1,16 +1,36 @@
 {
   "name": "@supersolutions/super-router-core",
-  "version": "0.0.0",
-  "description": "Placeholder; real releases come from GitHub Actions.",
+  "version": "0.1.0",
   "license": "Apache-2.0",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/Super-Solution/super-router.git"
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
   },
   "files": [
-    "README.md"
+    "dist",
+    "LICENSE",
+    "NOTICE"
   ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json"
+  },
+  "dependencies": {
+    "@supersolutions/super-router-contracts": "0.1.0"
+  },
+  "author": "SUPER SOLUTION LABS INC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Super-Solution/super-router.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://github.com/Super-Solution/super-router#readme",
+  "bugs": {
+    "url": "https://github.com/Super-Solution/super-router/issues"
+  },
   "publishConfig": {
     "access": "public"
   }
-}
+}

package/README.md

@@ -1,3 +0,0 @@
-# @supersolutions/super-router-core
-
-Placeholder. Releases are published from https://github.com/Super-Solution/super-router by GitHub Actions.