@oxy.so/contracts 1.0.0

package/dist/esm/inference/identifiers.js

@@ -0,0 +1,221 @@
+/**
+ * Identifiers, references and wire primitives shared by every Oxy↔data-plane
+ * inference contract.
+ *
+ * Two kinds of identifier live here, and the difference matters:
+ *
+ *  - **Principal identifiers** owned by Oxy (`accountId`, `applicationId`,
+ *    `credentialId`, the optional delegated `userId`). The data plane may store
+ *    them as immutable references; it never owns, mints or mutates them.
+ *  - **Catalogue references** (`<publisher>/<model>`, `<publisher>/<model>@<revision>`,
+ *    a routing-profile slug). These are the strings a customer types, so their
+ *    grammar is part of the public contract, not an implementation detail.
+ *
+ * Platform-agnostic — zod only. Every regex here is plain ASCII: this package
+ * is imported by React Native apps running on Hermes, which rejects Unicode
+ * property escapes (`\p{…}`) at runtime.
+ *
+ * Decided in: docs/adr/0007-canonical-request-attribution.md, docs/adr/0008-catalogue-concept-separation.md.
+ */
+import { z } from 'zod';
+/* -------------------------------------------------------------------------- */
+/*  Principal identifiers                                                     */
+/* -------------------------------------------------------------------------- */
+/**
+ * An Oxy account id — the account that owns the workload and is financially
+ * responsible for it.
+ *
+ * Branded, and that brand is load-bearing rather than decorative: it is the
+ * type-level half of the rule that a delegated end-user identity can never
+ * become the billing identity (see {@link delegatedUserIdSchema} and
+ * `billingPrincipalSchema`). A plain `string` — and therefore any id read out
+ * of a header, a JWT claim or a request body — is not assignable to it; the
+ * only way to obtain one is to parse a value through this schema.
+ */
+export const oxyAccountIdSchema = z.string().min(1).max(64).brand();
+/**
+ * A delegated end-user identity (Alia's `X-Oxy-User-Id`), branded with a
+ * DIFFERENT brand from {@link oxyAccountIdSchema} so the two cannot be
+ * substituted for one another in either direction, in any consumer, without a
+ * cast that review would catch.
+ *
+ * It exists for attribution and product-side personalisation only. It is never
+ * a billing principal, never an access-control principal, and its presence
+ * never changes which account is charged.
+ */
+export const delegatedUserIdSchema = z.string().min(1).max(64).brand();
+/**
+ * An Oxy `Application._id`. Not branded: no invariant in this contract turns on
+ * confusing it with another id, and brand inflation costs every producer a
+ * parse call for no safety. The two ids above are branded because ADR 0007's
+ * rule is exactly that they must not be interchangeable.
+ */
+export const oxyApplicationIdSchema = z.string().min(1).max(64);
+/** An Oxy `ApplicationCredential._id` — the credential used for this request. */
+export const oxyCredentialIdSchema = z.string().min(1).max(64);
+/**
+ * A request id allocated by the Oxy EDGE, at admission and BEFORE
+ * authentication, so that a request rejected for a bad credential is as
+ * traceable as one that was served (ADR 0007, and step 1 of ADR 0010's edge
+ * order). It is required on the inbound envelope, which is what makes the data
+ * plane a consumer of this id rather than its source: the data plane echoes it
+ * on every stream event, on the usage report, in its response header and on
+ * anything it can be asked about later. It never mints one for a request it
+ * received.
+ *
+ * The one case that is NOT an exception to that: an envelope the data plane
+ * cannot read or authenticate carries no id to echo, so its rejection is
+ * labelled with an id of the data plane's own — visibly local, and never
+ * correlated with an Oxy request, because there is no Oxy request it belongs to.
+ * Saying so is what stops "consumer, not source" from being read as forbidding
+ * the only id such a rejection could have.
+ *
+ * Correlates the Oxy edge, the data plane, the financial ledger and the
+ * customer-visible receipt, so it appears on every stream event and every
+ * ledger record.
+ */
+export const requestIdSchema = z.string().min(1).max(128);
+/**
+ * A generation id generated by the data plane, present when a request produced
+ * a generation that can be looked up later (`GET /v1/generations/:id`).
+ */
+export const generationIdSchema = z.string().min(1).max(128);
+/**
+ * A caller-supplied idempotency key. Every reserve/settle/refund call is keyed
+ * on one so a retry, a redelivered event or a duplicated webhook can never
+ * charge twice.
+ */
+export const idempotencyKeySchema = z.string().min(1).max(255);
+/** Credential environments. A credential is issued into exactly one of them. */
+export const inferenceEnvironmentSchema = z.enum(['development', 'staging', 'production']);
+/* -------------------------------------------------------------------------- */
+/*  Wire primitives                                                           */
+/* -------------------------------------------------------------------------- */
+/**
+ * An instant, as an ISO 8601 string in UTC (`2026-08-15T09:41:00.000Z`).
+ *
+ * Validated rather than left free-form — unlike the session contracts, which
+ * carry legacy expiry strings no consumer interprets, every instant here is
+ * read: a reservation expires, a price version starts applying, a receipt is
+ * settled. One canonical spelling (UTC, `Z`) so two records that describe the
+ * same moment compare and sort as equal, which a mix of offsets would not.
+ */
+export const inferenceTimestampSchema = z.string().datetime();
+/**
+ * A calendar DATE with no instant attached (`2026-05-01`) — a knowledge cutoff
+ * or a release date, which are published as days and become wrong when a
+ * timezone is invented for them.
+ */
+export const inferenceDateSchema = z
+    .string()
+    .regex(/^[0-9]{4}-[0-9]{2}-[0-9]{2}$/, 'must be an ISO 8601 calendar date (YYYY-MM-DD)');
+/** An absolute https URL, for model cards, licenses and provider documentation. */
+export const inferenceHttpsUrlSchema = z
+    .string()
+    .max(2048)
+    .regex(/^https:\/\/[^\s]+$/, 'must be an absolute https URL');
+/**
+ * A content digest, `sha256:<64 lowercase hex>`.
+ *
+ * ONE spelling, because a digest is compared for equality and nothing else: an
+ * uppercase or unprefixed variant of the same hash is a different string, so two
+ * records describing the same bytes would not match. Lowercase hex with the
+ * algorithm prefix is what the `inference_model_revisions` CHECK stores and what
+ * every artifact registry emits.
+ */
+export const sha256DigestSchema = z
+    .string()
+    .regex(/^sha256:[a-f0-9]{64}$/, 'digest must be sha256:<64 lowercase hex>');
+/* -------------------------------------------------------------------------- */
+/*  Catalogue references                                                      */
+/* -------------------------------------------------------------------------- */
+/** One path segment of a canonical model id: a lowercase, URL-safe slug. */
+const SLUG_PATTERN = '[a-z0-9](?:[a-z0-9._-]*[a-z0-9])?';
+/** A revision label. Case-preserving, because upstream revisions often are. */
+const REVISION_PATTERN = '[a-zA-Z0-9](?:[a-zA-Z0-9._-]*[a-zA-Z0-9])?';
+/** A publisher slug, e.g. `openai`, `anthropic`, `meta`, `alia`. */
+export const publisherSlugSchema = z
+    .string()
+    .max(64)
+    .regex(new RegExp(`^${SLUG_PATTERN}$`), 'publisher must be a lowercase URL-safe slug');
+/** A model slug within its publisher's namespace, e.g. `gpt-5`, `llama-3.1-70b`. */
+export const modelSlugSchema = z
+    .string()
+    .max(64)
+    .regex(new RegExp(`^${SLUG_PATTERN}$`), 'model must be a lowercase URL-safe slug');
+/**
+ * A canonical model id, `<publisher>/<model>`. This names a MODEL — a
+ * long-lived product identity whose behaviour changes as revisions ship. It
+ * does not name a revision, a deployment or a provider.
+ */
+export const modelIdSchema = z
+    .string()
+    .max(129)
+    .regex(new RegExp(`^${SLUG_PATTERN}/${SLUG_PATTERN}$`), 'model id must be <publisher>/<model>');
+/** An immutable revision label, unique within its model, e.g. `2026-05-01`. */
+export const modelRevisionLabelSchema = z
+    .string()
+    .max(64)
+    .regex(new RegExp(`^${REVISION_PATTERN}$`), 'revision must be a URL-safe label');
+/**
+ * A model reference as a customer writes it: `<publisher>/<model>` (the model's
+ * current revision, chosen by Oxy) or `<publisher>/<model>@<revision>` (an
+ * immutable revision the customer pinned).
+ *
+ * Both forms name a CONCRETE MODEL. Neither can name a routing profile — see
+ * {@link routingProfileSlugSchema} — which is what makes "a request for a
+ * concrete model is never silently replaced with a different model" a
+ * distinction the type system can carry rather than a convention.
+ */
+export const modelReferenceSchema = z
+    .string()
+    .max(194)
+    .regex(new RegExp(`^${SLUG_PATTERN}/${SLUG_PATTERN}(?:@${REVISION_PATTERN})?$`), 'model reference must be <publisher>/<model> or <publisher>/<model>@<revision>');
+/**
+ * A routing-profile slug, e.g. `auto`, `fast`, `quality`.
+ *
+ * Deliberately refuses a `/`, so a profile can never be written in the shape of
+ * a model id and no caller can be confused about whether they asked for a
+ * concrete model or for Oxy to choose one. Modes like `auto`/`fast`/`quality`
+ * are profiles or product presets; they are never model objects.
+ */
+export const routingProfileSlugSchema = z
+    .string()
+    .max(64)
+    .regex(new RegExp(`^${SLUG_PATTERN}$`), 'routing profile must be a lowercase URL-safe slug');
+/**
+ * The opaque PostgreSQL identity of one routing profile.
+ *
+ * No trim, case-folding or format heuristic: callers selecting by id must name
+ * the exact stored bytes. The database lookup is the authority for existence.
+ */
+export const routingProfileIdSchema = z.string().min(1).max(128);
+/** An inference provider slug, e.g. `openai`, `bedrock`, `oxy-hosted`. */
+export const inferenceProviderSlugSchema = z
+    .string()
+    .max(64)
+    .regex(new RegExp(`^${SLUG_PATTERN}$`), 'provider must be a lowercase URL-safe slug');
+/**
+ * A deployment/endpoint id. Opaque to customers: which concrete endpoint served
+ * a request is the data plane's operational detail, and only the customer-safe
+ * subset of it is ever attributed back (see the catalogue's serving-boundary
+ * rules).
+ */
+export const deploymentIdSchema = z.string().min(1).max(128);
+/**
+ * A region identifier, e.g. `us-west-2`, `eu-central-1`. Free-form rather than
+ * a closed enum because the set is provider-defined and grows without any
+ * contract change; residency policies match on exact strings.
+ */
+export const inferenceRegionSchema = z
+    .string()
+    .max(64)
+    .regex(new RegExp(`^${SLUG_PATTERN}$`), 'region must be a lowercase URL-safe slug');
+/**
+ * The publisher namespace reserved for models Alia actually owns or derives.
+ *
+ * `alia/*` is never a re-badged third-party route and never a prompt preset —
+ * enforcing that is the job of `modelSchema`'s provenance refinement, which
+ * this constant exists to be checked against.
+ */
+export const RESERVED_ALIA_PUBLISHER = 'alia';

package/dist/esm/inference/inbox.js

@@ -0,0 +1,102 @@
+import { z } from 'zod';
+import { inferenceErrorSchema } from './errors.js';
+const inboxTextSchema = z.string().trim().min(1).max(20000);
+const inboxMessageIdSchema = z.string().min(1).max(128);
+const DAILY_BRIEF_MIN_WINDOW_MS = 23 * 60 * 60 * 1000;
+const DAILY_BRIEF_MAX_WINDOW_MS = 25 * 60 * 60 * 1000;
+const inboxUtcTimestampSchema = z
+    .string()
+    .datetime({ offset: false })
+    .refine((value) => value.endsWith('Z'), 'Timestamp must use the UTC Z suffix');
+export const inboxComposeRequestSchema = z.discriminatedUnion('operation', [
+    z.object({
+        operation: z.literal('draft'),
+        prompt: inboxTextSchema,
+        tone: z.enum(['professional', 'casual', 'friendly', 'formal']),
+        stream: z.boolean().optional(),
+    }).strict(),
+    z.object({ operation: z.literal('polish'), text: inboxTextSchema }).strict(),
+    z.object({
+        operation: z.literal('change_tone'),
+        text: inboxTextSchema,
+        tone: z.enum(['professional', 'casual', 'friendly', 'formal']),
+    }).strict(),
+    z.object({
+        operation: z.literal('adjust_length'),
+        text: inboxTextSchema,
+        direction: z.enum(['shorter', 'longer']),
+    }).strict(),
+    z.object({ operation: z.literal('suggest_subject'), body: inboxTextSchema }).strict(),
+]);
+/**
+ * The client owns the user's timezone and therefore supplies the UTC instants
+ * that bracket one local calendar day. The server treats this as [start, end):
+ * requiring a 23-25 hour window admits both DST transitions but refuses an
+ * arbitrary history export disguised as a brief.
+ */
+export const inboxDailyBriefRequestSchema = z.object({
+    startAt: inboxUtcTimestampSchema,
+    endAt: inboxUtcTimestampSchema,
+    stream: z.boolean().optional(),
+}).strict().superRefine((value, context) => {
+    const durationMs = Date.parse(value.endAt) - Date.parse(value.startAt);
+    if (!Number.isFinite(durationMs) || durationMs <= 0) {
+        context.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['endAt'],
+            message: 'endAt must be after startAt',
+        });
+        return;
+    }
+    if (durationMs < DAILY_BRIEF_MIN_WINDOW_MS || durationMs > DAILY_BRIEF_MAX_WINDOW_MS) {
+        context.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['endAt'],
+            message: 'Daily brief window must be between 23 and 25 hours',
+        });
+    }
+});
+export const inboxNaturalSearchRequestSchema = z.object({ query: z.string().trim().min(1).max(512) }).strict();
+export const inboxMessageInferenceParamsSchema = z.object({ messageId: inboxMessageIdSchema }).strict();
+export const inboxInferenceTextResponseSchema = z.object({
+    schemaVersion: z.literal(1),
+    requestId: z.string().min(1).max(128),
+    generationId: z.string().min(1).max(128).optional(),
+    text: z.string().max(40000),
+}).strict();
+export const inboxNaturalSearchResponseSchema = z.object({
+    query: z.object({
+        q: z.string().max(512).optional(),
+        from: z.string().max(320).optional(),
+        to: z.string().max(320).optional(),
+        subject: z.string().max(512).optional(),
+        hasAttachment: z.boolean().optional(),
+        starred: z.boolean().optional(),
+        unread: z.boolean().optional(),
+        after: z.string().date().optional(),
+        before: z.string().date().optional(),
+        mailbox: z.enum(['inbox', 'sent', 'drafts', 'trash', 'spam', 'archive']).optional(),
+    }).strict(),
+    interpretation: z.string().max(1000),
+}).strict();
+export const inboxSmartRepliesResponseSchema = z.object({
+    replies: z.array(z.string().trim().min(1).max(500)).max(3),
+}).strict();
+export const inboxThreadSummaryResponseSchema = z.object({
+    summary: z.string().max(4000),
+    keyPoints: z.array(z.string().max(1000)).max(12),
+    actionItems: z.array(z.object({
+        text: z.string().max(1000),
+        owner: z.string().max(320).nullable(),
+        deadline: z.string().max(128).nullable(),
+    }).strict()).max(12),
+}).strict();
+export const inboxInferenceStreamEventSchema = z.discriminatedUnion('type', [
+    z.object({ type: z.literal('delta'), text: z.string().min(1).max(16384) }).strict(),
+    z.object({
+        type: z.literal('done'),
+        requestId: z.string().min(1).max(128),
+        generationId: z.string().min(1).max(128).optional(),
+    }).strict(),
+    z.object({ type: z.literal('error'), error: inferenceErrorSchema }).strict(),
+]);