@oxyhq/contracts 0.30.0 → 0.32.0

package/dist/esm/accountGraph.js

@@ -347,6 +347,64 @@ export const createAccountRequestSchema = z.object({
     bio: z.string().trim().max(500).optional(),
     avatar: z.string().optional(),
     description: z.string().trim().max(1000).optional(),
+    /**
+     * A named color preset KEY (`"blue"`, `"mint"`, …), never a hex value.
+     *
+     * Here at CREATION for the reason `isPrivateAccount` is, in miniature: for a
+     * managed account the color is a visual identity, and an account that is
+     * discoverable without one and acquires it on a second request is a face that
+     * changes by itself. One statement, one row, born looking like what its owner
+     * chose.
+     *
+     * The VALUE is checked in the API rather than here. The vocabulary is
+     * `USER_COLOR_PRESETS`, which is declared next to the `users_color_check` CHECK
+     * that is rendered from it — pinning the list a second time in this package
+     * would be a second source of truth for what the database accepts, and the two
+     * would drift apart silently. What this shape does is keep an over-long or
+     * non-string value from reaching the service at all.
+     */
+    color: z.string().trim().max(32).optional(),
     /** Ordered, PRIMARY FIRST — see rule 2 above {@link ACCOUNT_CATEGORY_IDS}. */
     accountCategories: accountCategoriesSchema.optional(),
+    /**
+     * Create the account already opted OUT of discovery.
+     *
+     * ## Why this belongs at CREATION and not only on the privacy route
+     *
+     * Every account is born discoverable: the column defaults to `false` and
+     * nothing on the create path wrote it, so a new account appears in people
+     * search the instant it exists. For a human signing themselves up that is the
+     * right default and it is NOT changed here. For an account a program creates
+     * on someone's behalf — an agent, an unlaunched project, an organization for
+     * something not yet announced — it publishes the thing before its owner ever
+     * decided to.
+     *
+     * The alternative is a second call right after create, which is a window in
+     * which the account IS public, and a window whose closing depends on a second
+     * request succeeding. A field here has neither: one statement, one row, born
+     * in the state the caller asked for.
+     *
+     * ## It reuses the existing flag deliberately
+     *
+     * This is `privacy_is_private_account`, the same one `PUT /users/:id/privacy`
+     * toggles — not a new "published" column. A second visibility flag would be a
+     * second source of truth for one question, and the two would disagree.
+     *
+     * Inherited semantics, stated because reusing a flag means inheriting ALL of
+     * it: the account is kept out of people search, out of the follow-graph lists
+     * (`followers` / `following` / `mutuals`), out of `/similar` and out of the
+     * recommendation candidate pools, and its non-public, non-unlisted media
+     * becomes follower-gated. It does NOT hide the profile from someone who knows
+     * the handle, and it carries NO follow-approval flow — following is immediate
+     * and unilateral whatever this says, so nothing here creates a request queue
+     * nobody attends.
+     *
+     * ## Not conditioned on `kind`, on purpose
+     *
+     * The same reasoning as `accountCategories` above: this object does not
+     * refine on kind, and an unlaunched organization has exactly the problem an
+     * unpublished agent does. The discovery predicate never reads `kind`, so the
+     * remedy must not either.
+     */
+    isPrivateAccount: z.boolean().optional(),
 });

package/dist/esm/index.js

@@ -141,6 +141,11 @@ export {
 // The signed Alia model release manifest (ingestion contract; no endpoint).
 aliaReleaseArtifactSchema, aliaReleaseSignatureSchema, aliaModelReleaseManifestSchema, } from './inference/aliaModelRelease.js';
 export { 
+// Model documentation: the GPAI/EU AI Act record, the ingestion request that
+// accepts it beside a signed manifest, and the revision-scoped documentation
+// view a downstream developer reads.
+modelDistributionMethodSchema, modelSystemicRiskTierSchema, trainingComputeFlopsSchema, SYSTEMIC_RISK_COMPUTE_THRESHOLD_FLOPS, modelDownstreamDocumentationSchema, modelGpaiDocumentationSchema, modelLineDeclarationSchema, modelReleaseIngestionRequestSchema, modelReleaseIngestionResultSchema, modelDocumentationSchema, } from './inference/modelDocumentation.js';
+export { 
 // The normalized Oxy→data-plane request envelope.
 inferenceContentSourceSchema, inferenceContentPartSchema, inferenceToolCallSchema, inferenceMessageRoleSchema, inferenceMessageSchema, inferenceInputSchema, samplingParametersSchema, toolDefinitionSchema, toolChoiceSchema, responseFormatSchema, clientRequestMetadataSchema, inferenceRequestSchema, } from './inference/request.js';
 export { 
@@ -151,7 +156,7 @@ export {
 usageReservationRequestSchema, usageReservationStatusSchema, usageReservationSchema, inferenceRequestOutcomeSchema, normalizedUsageReportSchema, usageReceiptSchema, usageRefundSubjectSchema, usageRefundReasonSchema, usageRefundSchema, } from './inference/usage.js';
 export { 
 // BYOK connection metadata that structurally cannot carry a secret.
-providerConnectionScopeSchema, providerSecretReferenceSchema, providerConnectionValidationSchema, providerConnectionStatusSchema, providerConnectionSchema, } from './inference/providerConnection.js';
+PROVIDER_SECRET_REFERENCE_NAMESPACE, providerConnectionScopeSchema, providerSecretReferenceSchema, providerConnectionValidationSchema, providerConnectionStatusSchema, providerConnectionSchema, } from './inference/providerConnection.js';
 export { 
 // Account-scoped billing: who pays, what they hold, what bounds them, and
 // how it reconciles against the payment processor. A grant and a purchase

package/dist/esm/inference/aliaModelRelease.js

@@ -35,14 +35,22 @@
  * bounded: ingestion is a release-time operation an operator retries once Oxy
  * takes the newer contract, not a served request that becomes unsettleable.
  *
- * ## What is deliberately NOT here
+ * ## The ingestion path, which this file used to say did not exist
+ *
+ * It does now: `POST /inference/admin/model-releases`, defined by
+ * `modelReleaseIngestionRequestSchema` in `modelDocumentation.ts`. This shape is
+ * unchanged — the request COMPOSES it, alongside two records that are Oxy's own
+ * rather than the signer's (the GPAI documentation and the capability sheet a
+ * manifest does not carry), precisely so the bytes a signature covers stay
+ * exactly the bytes described here.
  *
- * **No HTTP write path.** The catalogue's emptiness is currently a safety
- * property — `scripts/seed-inference-catalogue.ts` refuses to invent a licence
- * or a retention flag because "a plausible invented value in a catalogue is
- * worse than an absent one" — and a staff write path into it with nothing to
- * ingest is an unexercised hazard. The schema lands; the endpoint waits for a
- * real manifest to ingest.
+ * The earlier objection was that a staff write path into an empty catalogue is
+ * an unexercised hazard. What answers it is containment rather than emptiness: an
+ * ingested revision lands with `is_current = false` and no deployment, so nothing
+ * it creates is servable or listed, and a route still needs an approved
+ * contract/legal review before any customer can select it.
+ *
+ * ## What is deliberately NOT here
  *
  * **No `payloadDigest` field.** The signature is over the canonical
  * serialization of this manifest with `signatures` removed, and a verifier
@@ -64,7 +72,11 @@
  * custody, rotation and revocation consequences. So `keyId` is an OPAQUE
  * identifier and this file names no registry that resolves it: either answer
  * fits, and neither is presupposed. Until it is answered a manifest can be
- * parsed and cannot be verified, which is the second reason no endpoint ships.
+ * parsed and cannot be VERIFIED, so the ingestion path records no verification
+ * finding at all: it stores the signatures and the manifest as received, and the
+ * authority for the ingest is the staff member who performed it. A nullable
+ * `verified` column nothing ever writes would read, to whoever scanned the table
+ * later, as a check that ran.
  *
  * Decided in: docs/adr/0008-catalogue-concept-separation.md,
  * docs/adr/0017-authorized-routes-in-the-envelope.md, issue #972 §12.

package/dist/esm/inference/modelDocumentation.js

@@ -0,0 +1,430 @@
+/**
+ * Model documentation: what a first-party release must DECLARE, what a
+ * downstream developer may READ, and the request that ingests both.
+ *
+ * Issue #972 §12, the three items under "Future Alia model
+ * publication/compliance" that `aliaModelRelease.ts` deliberately left open:
+ * accepting the documentation set, publicising the customer-safe half of it, and
+ * preserving the metadata an EU AI Act / GPAI documentation workflow needs.
+ *
+ * ## The section's own scope is what makes the compliance claim falsifiable
+ *
+ * The issue section is titled "Future Alia model publication/compliance", so the
+ * obligations in play are the ones binding a PROVIDER of a general-purpose AI
+ * model — Oxy/Alia, for an `alia/*` release it trained or derived. Oxy's position
+ * on third-party weights is a different one (it received documentation rather
+ * than produced it) with different obligations, and nothing here claims to
+ * discharge those. Every field below names the obligation it serves; a field
+ * whose obligation could not be named is not here, and two are listed at the
+ * bottom as deliberately absent.
+ *
+ * References are to Regulation (EU) 2024/1689 (the AI Act): Article 50(2)
+ * (marking synthetic output), Article 51 (classification as a model with
+ * systemic risk), Article 53 (obligations of providers of general-purpose AI
+ * models), Article 55 (additional obligations for systemic-risk models), Annex XI
+ * (the technical documentation), Annex XII (the information for downstream
+ * providers).
+ *
+ * ## Two shapes, and the Act itself draws the line between them
+ *
+ * {@link modelGpaiDocumentationSchema} is the whole record. {@link
+ * modelDownstreamDocumentationSchema} is the subset served publicly. The split
+ * is NOT editorial taste: Annex XI is documentation a provider keeps and
+ * provides to the AI Office and national competent authorities on request, while
+ * Annex XII is information a provider MAKES AVAILABLE to downstream providers.
+ * Training compute, training time, energy consumption and the adversarial-testing
+ * report are Annex XI Section 2 and Article 55(1)(a) — the first audience — so
+ * they are in the record and not in the public projection, and
+ * `db/schema/protectedColumns.ts` says the same thing a second time at the type
+ * level.
+ *
+ * ## The conditionals are the Act's, not a convenience
+ *
+ * Article 53(2) exempts a model released under a free and open-source licence
+ * from 53(1)(a) and 53(1)(b) — the Annex XI and Annex XII sets — UNLESS it is a
+ * model with systemic risk. It does not exempt 53(1)(c) or 53(1)(d). So the
+ * copyright policy and the training-content summary are required of every
+ * release here, while the Annex XI/XII set is required of every release that is
+ * not covered by that exemption. Writing it the other way round — everything
+ * optional, checked by a human — is what makes a compliance record a field nobody
+ * filled in.
+ *
+ * ## What is deliberately NOT here
+ *
+ * **The modality and FORMAT of inputs and outputs (Annex XI §1(6), Annex XII
+ * §1(b)).** The modality half is already stored, as `inference_models`'
+ * `input_modalities` / `output_modalities`. The format half is a property of the
+ * Oxy API — one request envelope, one set of endpoints, identical for every model
+ * — so a per-model column would record the same value on every row and invite a
+ * reader to believe it could differ.
+ *
+ * **The technical means required for integration (Annex XII §1(c)).** Same
+ * reason: for a model served over the Oxy API that is Oxy's own API
+ * documentation, not a fact about the weights.
+ *
+ * **A verification finding for a release signature.** See
+ * `aliaModelRelease.ts`: whether a signature checked out is Oxy's finding about
+ * the document and not a claim the document makes, and no verifier exists yet
+ * because what signs is undecided. The ingestion path stores the signatures and
+ * the manifest as received so a verifier that lands later can check them; it
+ * records no finding, because there is none.
+ *
+ * Decided in: docs/adr/0008-catalogue-concept-separation.md, issue #972 §12.
+ */
+import { z } from 'zod';
+import { aliaModelReleaseManifestSchema } from './aliaModelRelease.js';
+import { modelCapabilitiesSchema, modelEvaluationResultSchema, modelLicenseSchema, modelProvenanceSchema, modelSafetyMetadataSchema, } from './catalogue.js';
+import { inferenceDateSchema, inferenceHttpsUrlSchema, inferenceTimestampSchema, modelIdSchema, modelReferenceSchema, modelRevisionLabelSchema, sha256DigestSchema, } from './identifiers.js';
+/* -------------------------------------------------------------------------- */
+/*  Vocabulary                                                                */
+/* -------------------------------------------------------------------------- */
+/**
+ * How a release reaches the people who use it — Annex XI §1(4) and Annex XII
+ * §1(a), "methods of distribution".
+ *
+ * TWO members, and both exist today: a release is served through the Oxy API, or
+ * its weights are published for download, or both. A third channel is a
+ * distribution decision somebody would have to make, and a closed enum gaining a
+ * member is a MINOR contract-set change the handshake surfaces (`version.ts`),
+ * which is the right amount of ceremony for it.
+ *
+ * `downloadable_weights` is also what the Article 53(2) free-and-open-source
+ * exemption is assessed against — that exemption requires the model to be
+ * "released under a free and open-source licence that allows for the access,
+ * usage, modification and distribution of the model" — so it is required even
+ * where the Annex XI set it belongs to is exempt.
+ */
+export const modelDistributionMethodSchema = z.enum(['oxy_api', 'downloadable_weights']);
+/**
+ * Whether this is a model with systemic risk, and on what basis — Article 51.
+ *
+ * Three states, because the two ways a model acquires the classification have
+ * different evidence and a record that flattened them could not be checked:
+ *
+ * - `not_designated` — neither presumed nor designated.
+ * - `presumed_by_training_compute` — Article 51(2): the cumulative compute used
+ *   for training exceeds 10^25 floating point operations, which the Act makes a
+ *   presumption of high-impact capabilities. The FIGURE is what creates it, so
+ *   {@link modelGpaiDocumentationSchema} requires the figure alongside this
+ *   value.
+ * - `designated_by_commission` — Article 51(1)(b): a Commission decision, ex
+ *   officio or following a qualified alert, that the model has capabilities
+ *   equivalent to the presumption. Not derivable from anything Oxy holds, which
+ *   is exactly why it is a declared value.
+ */
+export const modelSystemicRiskTierSchema = z.enum([
+    'not_designated',
+    'presumed_by_training_compute',
+    'designated_by_commission',
+]);
+/**
+ * Cumulative training compute in floating point operations — Annex XI §2(b).
+ *
+ * TEXT, in the same spirit as `modelEvaluationResultSchema.score` and for a
+ * sharper reason: this is a PUBLISHED figure (`4.2e25`, `2.5e26`), the numbers
+ * involved are far outside the exactly-representable integer range, and the
+ * value is never arithmetic Oxy performs on a customer's behalf. A JSON number
+ * would round it silently and make two records of one published figure compare
+ * unequal.
+ *
+ * The one comparison that IS made — against Article 51(2)'s 10^25 threshold — is
+ * a magnitude test, and `Number()` on a string this regex admits is exact enough
+ * for a magnitude test by a factor of about 10^9. The refinement that performs
+ * it is on {@link modelGpaiDocumentationSchema}.
+ */
+export const trainingComputeFlopsSchema = z
+    .string()
+    .max(40)
+    .regex(/^(?:0|[1-9][0-9]*)(?:\.[0-9]+)?(?:e\+?(?:0|[1-9][0-9]?))?$/, 'training compute must be a decimal or scientific figure, e.g. 4.2e25');
+/**
+ * Article 51(2)'s presumption threshold, as a number.
+ *
+ * Named rather than inlined so the refinement that applies it and the enum
+ * member that describes it (`presumed_by_training_compute`) cannot come to mean
+ * different things.
+ */
+export const SYSTEMIC_RISK_COMPUTE_THRESHOLD_FLOPS = 1e25;
+/* -------------------------------------------------------------------------- */
+/*  The record                                                                */
+/* -------------------------------------------------------------------------- */
+/**
+ * The subset of the documentation set that is served to downstream developers —
+ * Annex XII, plus the two Article 53(1) items that are public by their own terms.
+ *
+ * Rides inside {@link modelDocumentationSchema} and inherits its version.
+ *
+ * Every field here is one a developer integrating the model needs in order to
+ * decide whether they may use it and what they must say about it: what it is for,
+ * how it is distributed, what it is built out of, where the training-content
+ * summary and the copyright policy are, and whether it carries the systemic-risk
+ * classification that puts obligations on them too.
+ *
+ * The optional members are optional for a REASON stated in the parent record's
+ * refinement — Article 53(2) — and not because a value may be skipped.
+ */
+export const modelDownstreamDocumentationSchema = z
+    .object({
+    /** Annex XI §1(2), Annex XII §1(a): the tasks the model is intended for. */
+    intendedTasks: z.string().min(1).max(2000).optional(),
+    /** Annex XI §1(4), Annex XII §1(a). */
+    distributionMethods: z.array(modelDistributionMethodSchema).min(1),
+    /** Annex XI §1(5), reachable through Annex XII §1(a) ("points 1 to 5"). */
+    architecture: z.string().min(1).max(500).optional(),
+    /** Annex XI §1(5): the number of parameters. */
+    parameterCount: z.number().int().positive().safe().optional(),
+    /** Article 53(1)(d): the publicly available summary of training content. */
+    trainingDataSummaryUrl: inferenceHttpsUrlSchema,
+    /**
+     * Article 53(1)(c): the policy for complying with Union copyright law,
+     * including the reservation of rights under Article 4(3) of Directive
+     * (EU) 2019/790. Required of every release — Article 53(2) does not exempt it.
+     */
+    copyrightPolicyUrl: inferenceHttpsUrlSchema,
+    /** Article 51. */
+    systemicRisk: modelSystemicRiskTierSchema,
+    /**
+     * Whether the release is under a free and open-source licence in the sense
+     * of Article 53(2). Distinct from `modelLicenseSchema.commercialUseAllowed`,
+     * which answers whether OXY may serve the model — a licence can permit
+     * commercial use and still not permit access, modification and
+     * redistribution of the weights, and it is the second question the exemption
+     * turns on.
+     */
+    freeAndOpenSourceRelease: z.boolean(),
+})
+    .strict();
+/**
+ * The whole documentation record for one revision, as ingested.
+ *
+ * `.strict()`, because this is a compliance record arriving over the wire: a
+ * field silently dropped at the parse is a field the record does not contain,
+ * and "we accepted your documentation" would then be true of less than was sent.
+ *
+ * Not versioned on its own — it rides inside
+ * {@link modelReleaseIngestionRequestSchema} on the way in and inside
+ * {@link modelDocumentationSchema} on the way out, and inherits whichever
+ * message carries it.
+ */
+export const modelGpaiDocumentationSchema = modelDownstreamDocumentationSchema
+    .extend({
+    /** Annex XI §2(b): the computational resources used for training. */
+    trainingComputeFlops: trainingComputeFlopsSchema.optional(),
+    /** Annex XI §2(b): the training time. */
+    trainingTimeHours: z.number().positive().safe().optional(),
+    /**
+     * Annex XI §2(c): the known or ESTIMATED energy consumption. The Act asks
+     * for an estimate where the figure is not known, so absence here means the
+     * Annex XI set is exempt rather than that the number was hard to obtain.
+     */
+    energyConsumptionMwh: z.number().nonnegative().safe().optional(),
+    /**
+     * Article 55(1)(a): the model evaluation, including adversarial testing,
+     * performed for a model with systemic risk. A pointer, like every other
+     * document reference here — the catalogue holds no report.
+     */
+    adversarialTestingReportUrl: inferenceHttpsUrlSchema.optional(),
+})
+    .strict()
+    .superRefine((documentation, ctx) => {
+    // Article 53(2): the free-and-open-source exemption from 53(1)(a) and (b)
+    // does not apply to a model with systemic risk. So the Annex XI/XII set is
+    // required of everything else, and the ONE state that may omit it is a
+    // free-and-open-source release that is not designated.
+    const exempt = documentation.freeAndOpenSourceRelease && documentation.systemicRisk === 'not_designated';
+    if (!exempt) {
+        const required = [
+            'intendedTasks',
+            'architecture',
+            'parameterCount',
+            'trainingTimeHours',
+            'energyConsumptionMwh',
+        ];
+        for (const field of required) {
+            if (documentation[field] === undefined) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    path: [field],
+                    message: 'required by Annex XI unless the Article 53(2) free-and-open-source exemption applies, which it does not for this release',
+                });
+            }
+        }
+    }
+    // The presumption IS the compute figure (Article 51(2)). Declaring the tier
+    // without the figure asserts a threshold was crossed while withholding the
+    // only thing that says so.
+    if (documentation.systemicRisk === 'presumed_by_training_compute' &&
+        documentation.trainingComputeFlops === undefined) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['trainingComputeFlops'],
+            message: 'a systemic-risk presumption under Article 51(2) is the training-compute figure; declare it',
+        });
+    }
+    // The other direction, which is the one that matters: a release whose own
+    // declared compute is past the threshold cannot also declare that no
+    // classification applies. Without this the field pair would let the record
+    // contradict itself and still parse.
+    if (documentation.trainingComputeFlops !== undefined &&
+        documentation.systemicRisk === 'not_designated' &&
+        Number(documentation.trainingComputeFlops) >= SYSTEMIC_RISK_COMPUTE_THRESHOLD_FLOPS) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['systemicRisk'],
+            message: 'training compute at or above 10^25 FLOP is presumed to be a model with systemic risk under Article 51(2)',
+        });
+    }
+    // Article 55(1)(a) applies to every model with systemic risk, however it
+    // acquired the classification.
+    if (documentation.systemicRisk !== 'not_designated' &&
+        documentation.adversarialTestingReportUrl === undefined) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['adversarialTestingReportUrl'],
+            message: 'a model with systemic risk documents its evaluation including adversarial testing (Article 55(1)(a))',
+        });
+    }
+});
+/* -------------------------------------------------------------------------- */
+/*  Ingestion                                                                 */
+/* -------------------------------------------------------------------------- */
+/**
+ * What OXY states about the model line a release belongs to.
+ *
+ * A signed release manifest carries a revision, a licence, a provenance block,
+ * evaluations, safety metadata and an artifact inventory. It carries no
+ * CAPABILITY SHEET — no modalities, no `maxContextTokens`, none of the
+ * tool/streaming flags — and every one of those is required to create a model
+ * line at all.
+ *
+ * That is not a gap in the manifest. A capability sheet is a statement about what
+ * the Oxy API will serve, which is Oxy's to make and not the signer's: the same
+ * weights behind a different gateway answer a different set of these questions.
+ * So it travels beside the manifest, like the documentation record, and the
+ * signature keeps covering exactly the document its signer wrote.
+ *
+ * Ignored when the model line already exists — a release does not edit a model.
+ * The licence and provenance in the MANIFEST are checked against the stored ones
+ * instead, because those are claims about somebody's rights rather than Oxy's own
+ * editorial choices.
+ */
+export const modelLineDeclarationSchema = z
+    .object({
+    displayName: z.string().min(1).max(200),
+    description: z.string().max(4000).optional(),
+    capabilities: modelCapabilitiesSchema,
+    knowledgeCutoff: inferenceDateSchema.optional(),
+    releasedOn: inferenceDateSchema.optional(),
+})
+    .strict();
+/**
+ * The body of the release-ingestion request.
+ *
+ * The documentation and the capability sheet travel BESIDE the manifest rather
+ * than inside it, and that is the whole reason this wrapper exists.
+ * `aliaModelReleaseManifestSchema` is a SIGNED document: adding a field to it
+ * would change the bytes a signer covers and the version the data plane and Alia
+ * compile against, for records that are Oxy's own rather than the signer's.
+ * Keeping them separate means the signature still covers exactly what it covered.
+ *
+ * A signer that later chooses to cover the documentation too can: it would
+ * become a second signed document with its own manifest, which is a contract
+ * addition rather than a change to this one.
+ */
+export const modelReleaseIngestionRequestSchema = z
+    .object({
+    /** See `version.ts`: an ingestion payload is a whole message on the wire. */
+    schemaVersion: z.literal(1),
+    manifest: aliaModelReleaseManifestSchema,
+    gpaiDocumentation: modelGpaiDocumentationSchema,
+    model: modelLineDeclarationSchema,
+})
+    .strict();
+/**
+ * What ingestion reports back.
+ *
+ * COUNTS for the artifacts and signatures rather than echoing them: the caller
+ * sent them and the interesting fact is that all of them landed. Echoing a
+ * signature would also make this response a place a credential-shaped value gets
+ * logged, for no gain.
+ *
+ * No verification field — see this module's header, and `aliaModelRelease.ts`.
+ */
+export const modelReleaseIngestionResultSchema = z
+    .object({
+    /** See `version.ts`: served on its own, so it is versioned. */
+    schemaVersion: z.literal(1),
+    releaseId: z.string().min(1).max(128),
+    modelId: modelIdSchema,
+    revision: modelRevisionLabelSchema,
+    reference: modelReferenceSchema,
+    /** Whether this request created the release, or found it already ingested. */
+    outcome: z.enum(['ingested', 'already_ingested']),
+    artifactCount: z.number().int().positive().safe(),
+    signatureCount: z.number().int().positive().safe(),
+    evaluationCount: z.number().int().nonnegative().safe(),
+    ingestedAt: inferenceTimestampSchema,
+})
+    .strict();
+/* -------------------------------------------------------------------------- */
+/*  The customer-safe documentation view                                      */
+/* -------------------------------------------------------------------------- */
+/**
+ * The documentation for ONE revision, as a downstream developer reads it.
+ *
+ * Revision-scoped, and that is the point of it existing beside
+ * `modelCatalogueEntrySchema`. The catalogue entry carries the documentation of
+ * whichever revision is CURRENT, so a customer who pinned
+ * `<publisher>/<model>@<revision>` — which the catalogue invites, and which the
+ * immutability trigger on `inference_model_revisions` exists to make meaningful —
+ * had no way to read the model card, evaluations or safety metadata of the
+ * revision they are actually calling. A model card that only describes the
+ * newest weights is the exact conflation ADR 0008 separates revisions to prevent.
+ *
+ * `license` and `provenance` are the MODEL's, repeated here rather than linked,
+ * for the same reason `modelCatalogueEntrySchema` repeats its fields: a
+ * projection that nests the operational descriptors is one accident of nesting
+ * away from serving an internal identifier.
+ */
+export const modelDocumentationSchema = z
+    .object({
+    /** See `version.ts`: this is a public response shape. */
+    schemaVersion: z.literal(1),
+    modelId: modelIdSchema,
+    revision: modelRevisionLabelSchema,
+    /** The exact string a customer pins. */
+    reference: modelReferenceSchema,
+    /** Whether a bare `<publisher>/<model>` resolves to this revision today. */
+    isCurrentRevision: z.boolean(),
+    releasedAt: inferenceTimestampSchema,
+    retiredAt: inferenceTimestampSchema.optional(),
+    modelCardUrl: inferenceHttpsUrlSchema.optional(),
+    /**
+     * The digest of the served artifact, where Oxy hosts the weights.
+     *
+     * Customer-safe, deliberately: it is the one field on this view that lets a
+     * developer check that the weights they were handed are the weights the
+     * documentation describes, and a digest discloses nothing but the identity of
+     * bytes Oxy is already serving them.
+     */
+    artifactDigest: sha256DigestSchema.optional(),
+    license: modelLicenseSchema,
+    provenance: modelProvenanceSchema,
+    evaluations: z.array(modelEvaluationResultSchema).default([]),
+    safety: modelSafetyMetadataSchema.optional(),
+    /** Absent for a revision with no documentation record — i.e. every one Oxy did not release. */
+    gpai: modelDownstreamDocumentationSchema.optional(),
+})
+    .strict()
+    .superRefine((documentation, ctx) => {
+    // The same check `modelRevisionSchema` makes, and it is load-bearing for a
+    // different reason here: this view exists so a customer can read the
+    // documentation of the revision they PINNED, so a reference that resolves
+    // elsewhere would attach a model card to weights nobody is calling.
+    if (documentation.reference !== `${documentation.modelId}@${documentation.revision}`) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['reference'],
+            message: 'reference must be exactly <modelId>@<revision>',
+        });
+    }
+});