@oxy.so/contracts 4.11.0 → 4.13.0

package/dist/esm/accountGraph.js

@@ -7,6 +7,7 @@
  * {@link ACCOUNT_CATEGORY_IDS} for the four rules that govern it.
  */
 import { z } from 'zod';
+import { avatarCharacterSchema } from './avatarCharacter.js';
 import { usernameSchema, usernameSchemaForAccountKind } from './username.js';
 /**
  * The union is spelled out above and the array proves coverage BOTH ways
@@ -466,8 +467,22 @@ export const createAccountRequestSchema = z
      * remedy must not either.
      */
     isPrivateAccount: z.boolean().optional(),
+    /**
+     * The 3D avatar character of a `bot` — and ONLY of a bot (the refinement
+     * below). Optional on the wire: a bot created without one is given a look
+     * seeded from its handle (`avatarCharacterFor`), so every bot account has a
+     * character from birth and the owner customizes it afterwards.
+     */
+    character: avatarCharacterSchema.optional(),
 })
     .superRefine((request, ctx) => {
+    if (request.character !== undefined && request.kind !== 'bot') {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['character'],
+            message: 'Only a bot account carries an avatar character',
+        });
+    }
     // The ONE place `kind` and `username` arrive in the same object, so it is the
     // only place a wire schema CAN apply the per-kind half of the policy: a bot's
     // handle must end in `bot`. Not a second rule — it asks

package/dist/esm/avatarCharacter.js

@@ -0,0 +1,115 @@
+/**
+ * The 3D avatar character a `bot` account carries.
+ *
+ * ONE definition for the wire shape, its validator and the generator that picks
+ * a look for a new bot, shared by the Oxy API (which stores and serves it) and
+ * every client. It mirrors Bloom's flat `AvatarCharacter`
+ * (`@oxy.so/bloom/agent-avatar`).
+ *
+ * ## The vocabulary is Bloom's and is NOT enforced here
+ *
+ * Bloom is a React Native package this one cannot depend on, so the ids a
+ * character is made of are restated below as a curated SUBSET, only to PICK a
+ * look for a new bot ({@link avatarCharacterFor}). A STORED character is never
+ * checked against them: validating against a stale copy of somebody else's
+ * catalogue is how a working look starts being refused. What the schema checks
+ * is the SHAPE of what a client writes: only the keys a character has, each an
+ * id-like string, a `#rrggbb` paint, a spacing in range. The client resolves
+ * the ids and falls back on a default look for one it cannot draw.
+ */
+import { z } from 'zod';
+const ID = /^[a-z][a-z0-9_]{0,39}$/;
+const HEX = /^#[0-9a-fA-F]{6}$/;
+/** Bounds of {@link AvatarCharacter.eyeSpacing}. */
+export const AVATAR_EYE_SPACING = { min: 0.5, max: 1.5 };
+const idSchema = z.string().regex(ID);
+/**
+ * A character a client sends. `.strict()` so a misspelled field is a refusal
+ * now rather than a look that never takes effect. A character with nothing in
+ * it draws nothing: it needs a preset, or a shape and a paint.
+ */
+export const avatarCharacterSchema = z
+    .object({
+    preset: idSchema.optional(),
+    shape: idSchema.optional(),
+    eyes: idSchema.optional(),
+    eyewear: idSchema.optional(),
+    accessory: idSchema.optional(),
+    color: idSchema.optional(),
+    bodyColor: z
+        .string()
+        .regex(HEX)
+        .transform((hex) => hex.toLowerCase())
+        .optional(),
+    eyeSpacing: z
+        .number()
+        .finite()
+        .min(AVATAR_EYE_SPACING.min)
+        .max(AVATAR_EYE_SPACING.max)
+        .optional(),
+})
+    .strict()
+    .refine((c) => c.preset !== undefined ||
+    (c.shape !== undefined && (c.color !== undefined || c.bodyColor !== undefined)), { message: 'A character needs a preset, or a shape and a color' });
+/** The validated character, or `null` for anything that is not one. */
+export function parseAvatarCharacter(value) {
+    const parsed = avatarCharacterSchema.safeParse(value);
+    return parsed.success ? parsed.data : null;
+}
+/** The parts a new bot's look is picked from: the plain, friendly shapes, in the editor's order. */
+export const AVATAR_PICKABLE_SHAPES = [
+    'rounded_triangle',
+    'capsule',
+    'rounded_head_two_ears',
+    'six_lobed_flower',
+    'heart',
+    'four_lobed_butterfly',
+    'circle_two_ears',
+    'twelve_scalloped_rosette',
+    'rounded_cube',
+    'rounded_diamond',
+    'slender',
+    'pocket',
+    'petal',
+    'star',
+    'cloud',
+    'shield',
+    'pebble',
+    'squircle',
+];
+/** Bloom's named paints. */
+export const AVATAR_PICKABLE_COLORS = [
+    'pink',
+    'orchid',
+    'violet',
+    'blue',
+    'cyan',
+    'teal',
+    'lime',
+    'yellow',
+    'coral',
+];
+/** A small, stable hash: the same seed always picks the same look. */
+function hash(seed) {
+    let h = 2166136261;
+    for (let i = 0; i < seed.length; i++) {
+        h ^= seed.charCodeAt(i);
+        h = Math.imul(h, 16777619);
+    }
+    return h >>> 0;
+}
+/**
+ * A look for a new bot, picked from its seed (its handle): a shape and a paint,
+ * plain oval eyes, nothing on its head. Stable — the same seed is the same look
+ * — and the owner changes it afterwards.
+ */
+export function avatarCharacterFor(seed) {
+    const h = hash(seed);
+    return {
+        shape: AVATAR_PICKABLE_SHAPES[h % AVATAR_PICKABLE_SHAPES.length],
+        eyes: 'oval',
+        eyewear: 'none',
+        accessory: 'none',
+        color: AVATAR_PICKABLE_COLORS[Math.floor(h / AVATAR_PICKABLE_SHAPES.length) % AVATAR_PICKABLE_COLORS.length],
+    };
+}

package/dist/esm/index.js

@@ -10,6 +10,7 @@
  * expo, no `require()` in the ESM build.
  */
 export { ACCOUNT_KINDS, accountKindSchema, CHILD_ACCOUNT_KINDS, childAccountKindSchema, isAccountKind, isDelegatedActAsEligibleKind, isOperatorSwitchTargetKind, ACCOUNT_CATEGORY_IDS, ACCOUNT_CATEGORY_KINDS, accountCategoriesSchema, accountCategoryIdSchema, isSelectableAccountCategoryId, kindAcceptsAccountCategories, MAX_ACCOUNT_CATEGORIES, newlyAddedRetiredCategories, RETIRED_ACCOUNT_CATEGORY_IDS, SELECTABLE_ACCOUNT_CATEGORY_IDS, createAccountRequestSchema, } from './accountGraph.js';
+export { AVATAR_EYE_SPACING, AVATAR_PICKABLE_COLORS, AVATAR_PICKABLE_SHAPES, avatarCharacterFor, avatarCharacterSchema, parseAvatarCharacter, } from './avatarCharacter.js';
 export { ACCOUNT_ACTOR_NATURES, ACCOUNT_SUBJECT_CONTRACT_VERSION, FINANCIAL_EFFECT_DIRECTIONS, KIND_INDEPENDENT_ACCOUNT_DIMENSIONS, accountActorChainFromSession, accountActorChainSchema, accountActorNatureSchema, accountKindActorNature, accountKindActsAsItself, attributeFinancialEffect, financialEffectAttributionSchema, } from './accountSubject.js';
 export { usernameSchema, usernameSchemaForAccountKind, isValidUsername, stripDisallowedUsernameCharacters, applyBotUsernameSuffix, USERNAME_MIN_LENGTH, USERNAME_MAX_LENGTH, USERNAME_INVALID_MESSAGE, BOT_USERNAME_INVALID_MESSAGE, RESERVED_USERNAME_MESSAGE, NUMERIC_USERNAME_MESSAGE, } from './username.js';
 export { 
@@ -119,7 +120,9 @@ oxyAccountIdSchema, delegatedUserIdSchema, oxyApplicationIdSchema, oxyCredential
 // Wire primitives
 inferenceTimestampSchema, inferenceDateSchema, inferenceHttpsUrlSchema, sha256DigestSchema, 
 // Catalogue references
-publisherSlugSchema, modelSlugSchema, modelIdSchema, modelRevisionLabelSchema, modelReferenceSchema, routingProfileIdSchema, routingProfileSlugSchema, inferenceProviderSlugSchema, deploymentIdSchema, inferenceRegionSchema, RESERVED_ALIA_PUBLISHER, } from './inference/identifiers.js';
+publisherSlugSchema, modelSlugSchema, modelIdSchema, modelRevisionLabelSchema, modelReferenceSchema, routingProfileIdSchema, routingProfileSlugSchema, inferenceProviderSlugSchema, deploymentIdSchema, inferenceRegionSchema, 
+// The economic tier Oxy bounds a route by and Kaana reports (ADR 0038)
+inferenceFundingTierSchema, RESERVED_ALIA_PUBLISHER, } from './inference/identifiers.js';
 export { 
 // Exact money and metered units — never floats, units never money.
 currencyCodeSchema, INFERENCE_MONEY_SCALE, exactDecimalSchema, moneySchema, USAGE_UNITS, usageUnitSchema, USAGE_SOURCES, usageSourceSchema, usageQuantitySchema, unitPriceSchema, } from './inference/money.js';

package/dist/esm/inference/identifiers.js

@@ -221,3 +221,16 @@ export const inferenceRegionSchema = z
  * this constant exists to be checked against.
  */
 export const RESERVED_ALIA_PUBLISHER = 'alia';
+/**
+ * The economic tier of the provider capacity that funds a request, in the
+ * order Kaana spends it: `free` (costs nothing), `credit` (a promotional or
+ * trial grant, or a prepaid balance), `paid` (ordinary metered spend).
+ *
+ * Kaana owns provider keys, their economics and which key serves (Oxy ADR
+ * 0038, Kaana ADR 0001); Oxy owns what a customer may spend. The tier is the
+ * one economic fact the two exchange: Oxy BOUNDS a route by it
+ * (`maxFundingTier`), and Kaana REPORTS the tier that served
+ * (`normalizedUsageReportSchema.fundingTier`). No key id, label or price
+ * travels with it.
+ */
+export const inferenceFundingTierSchema = z.enum(['free', 'credit', 'paid']);

package/dist/esm/inference/routingPolicy.js

@@ -32,7 +32,7 @@
  * docs/adr/0017-authorized-routes-in-the-envelope.md, issue #972 workstream 6.
  */
 import { z } from "zod";
-import { deploymentIdSchema, inferenceProviderSlugSchema, inferenceRegionSchema, inferenceTimestampSchema, modelReferenceSchema, oxyAccountIdSchema, oxyApplicationIdSchema, routingProfileIdSchema, } from "./identifiers.js";
+import { deploymentIdSchema, inferenceProviderSlugSchema, inferenceFundingTierSchema, inferenceRegionSchema, inferenceTimestampSchema, modelReferenceSchema, oxyAccountIdSchema, oxyApplicationIdSchema, routingProfileIdSchema, } from "./identifiers.js";
 import { kaanaCredentialHandleSchema } from "./providerConnection.js";
 import { exactDecimalSchema, currencyCodeSchema, unitPriceSchema, } from "./money.js";
 /**
@@ -291,6 +291,16 @@ const authorizedRouteFields = {
     modelReference: modelReferenceSchema,
     provider: inferenceProviderSlugSchema,
     regions: z.array(inferenceRegionSchema),
+    /**
+     * The dearest funding tier the data plane may spend on this route. Absent
+     * means no ceiling. Present, the data plane walks only provider keys whose
+     * STATED tier is at or below it — a key whose economics nobody stated is
+     * never admitted — and refuses the route rather than fall through to a
+     * dearer key. It is how Oxy authorizes a route only while credit funds it
+     * (Alia Pro and Ultra spend credits only, ADR 0038). Meaningless with a
+     * customer credential, which the provider bills to the customer.
+     */
+    maxFundingTier: inferenceFundingTierSchema.optional(),
     /**
      * Exact customer credential binding. Absence means a platform credential;
      * presence names the immutable Kaana generation this route may use.
@@ -345,6 +355,13 @@ export const authorizedRouteSchema = z
         .strict(),
 ])
     .superRefine((route, ctx) => {
+    if (route.maxFundingTier !== undefined && route.customerProviderCredential !== undefined) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['maxFundingTier'],
+            message: 'a funding ceiling bounds platform keys; a customer credential is billed to the customer',
+        });
+    }
     // Same rule as `modelDeploymentSchema`: a route serves specific weights. An
     // unpinned entry would leave the data plane choosing a revision, which is
     // the one substitution the customer never authorized by naming a model.

package/dist/esm/inference/usage.js

@@ -30,7 +30,7 @@
  */
 import { z } from 'zod';
 import { inferenceAttributionSchema } from './attribution.js';
-import { deploymentIdSchema, generationIdSchema, idempotencyKeySchema, inferenceProviderSlugSchema, inferenceTimestampSchema, modelReferenceSchema, requestIdSchema, } from './identifiers.js';
+import { deploymentIdSchema, generationIdSchema, idempotencyKeySchema, inferenceFundingTierSchema, inferenceProviderSlugSchema, inferenceTimestampSchema, modelReferenceSchema, requestIdSchema, } from './identifiers.js';
 import { currencyCodeSchema, exactDecimalSchema, usageQuantitySchema, usageSourceSchema, } from './money.js';
 import { priceSnapshotSchema } from './priceVersion.js';
 /* -------------------------------------------------------------------------- */
@@ -170,6 +170,14 @@ export const normalizedUsageReportSchema = z
     deploymentId: deploymentIdSchema,
     /** How many allowed route switches occurred while serving this request. */
     routeSwitches: z.number().int().nonnegative().max(100),
+    /**
+     * The funding tier of the platform key that served the final attempt, as
+     * the data plane states it (ADR 0038). Absent when the key's economics
+     * were never stated, when a customer credential served, or when nothing
+     * was served. Oxy reads it to account for what the request cost the
+     * platform; it is never a key identity and never reaches a customer.
+     */
+    fundingTier: inferenceFundingTierSchema.optional(),
     startedAt: inferenceTimestampSchema,
     completedAt: inferenceTimestampSchema,
     timeToFirstTokenMs: z.number().int().nonnegative().safe().optional(),

package/dist/esm/inference/version.js

@@ -99,4 +99,4 @@
  * change to, say, the catalogue reject every in-flight inference request; the
  * per-shape `schemaVersion` is what a message is validated against.
  */
-export const INFERENCE_CONTRACT_VERSION = '3.5.0';
+export const INFERENCE_CONTRACT_VERSION = '3.8.0';

package/dist/esm/recommendations.js

@@ -11,6 +11,7 @@
  * / expo, ESM-safe).
  */
 import { z } from 'zod';
+import { avatarCharacterSchema } from './avatarCharacter.js';
 import { userNameSchema } from './userResponse.js';
 /** User-type filters a caller may exclude from the recommendation surface. */
 export const recommendationExcludeTypeSchema = z.enum(['federated', 'agent', 'automated']);
@@ -77,6 +78,8 @@ export const recommendationItemSchema = z
     username: z.string().optional(),
     name: userNameSchema,
     avatar: z.string().nullable().optional(),
+    /** A bot's 3D avatar character; absent for every other kind. */
+    character: avatarCharacterSchema.optional(),
     /** The account's accent colour, as on every profile; absent when unset. */
     color: z.string().optional(),
     description: z.string().nullable().optional(),

package/dist/esm/userResponse.js

@@ -46,6 +46,7 @@ export const USER_PROFILE_COLOR_PRESETS = [
 import { z } from 'zod';
 import { verifiedDomainSchema } from './identity.js';
 import { accountCategoriesSchema, accountKindSchema } from './accountGraph.js';
+import { avatarCharacterSchema } from './avatarCharacter.js';
 export const userNameSchema = z
     .object({
     first: z.string().optional(),
@@ -222,6 +223,12 @@ export const userResponseSchema = z
      * `user.accountCategories ?? []`.
      */
     accountCategories: accountCategoriesSchema.optional(),
+    /**
+     * The 3D avatar character of a `kind: 'bot'` account — what Bloom's
+     * `Avatar` draws instead of a picture. Present ONLY on a bot's payload,
+     * never on a person's or an organization's, so those DTOs do not grow.
+     */
+    character: avatarCharacterSchema.optional(),
     /**
      * The authenticated viewer's relationship to this profile. Present ONLY
      * on single-profile fetches (`GET /profiles/username/:username`,