@oxyhq/contracts 0.30.0 → 0.32.0

package/dist/cjs/accountGraph.js

@@ -355,6 +355,64 @@ exports.createAccountRequestSchema = zod_1.z.object({
     bio: zod_1.z.string().trim().max(500).optional(),
     avatar: zod_1.z.string().optional(),
     description: zod_1.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: zod_1.z.string().trim().max(32).optional(),
     /** Ordered, PRIMARY FIRST — see rule 2 above {@link ACCOUNT_CATEGORY_IDS}. */
     accountCategories: exports.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: zod_1.z.boolean().optional(),
 });

package/dist/cjs/index.js

@@ -17,9 +17,9 @@ exports.moderationDecisionEventSubjectSchema = exports.moderationFindingSchema =
 exports.browserHubErrorSchema = exports.browserHubResolveResponseSchema = exports.browserHubHandleResponseSchema = exports.browserHubHandleRequestSchema = exports.browserHubHandleSchema = exports.BROWSER_HUB_HANDLE_TTL_MS = exports.BROWSER_HUB_COOKIE_ATTRIBUTES = exports.BROWSER_HUB_COOKIE_NAME = exports.oauthAuthorizeCodeResponseSchema = exports.oauthConsentDecisionSchema = exports.deviceDirectorySyncSchema = exports.deviceActivateResponseSchema = exports.deviceActivateRequestSchema = exports.deviceDirectorySchema = exports.devicePrincipalSchema = exports.deviceAccountContextSchema = exports.deviceDirectoryProfileSchema = exports.deviceContextRelationshipSchema = exports.sessionAccountsChangedEventSchema = exports.sessionAccountsChangedReasonSchema = exports.SESSION_ACCOUNTS_CHANGED_EVENT = exports.deviceBackgroundTokenResponseSchema = exports.deviceBackgroundTokenRequestSchema = exports.deviceBackgroundCredentialResponseSchema = exports.deviceTokenMintResponseSchema = exports.deviceTokenMintRequestSchema = exports.deviceSessionSyncSchema = exports.activeTokenSchema = exports.deviceSessionStateSchema = exports.sessionAccountSchema = exports.linkPreviewResponseSchema = exports.linkPreviewBatchResponseSchema = exports.linkPreviewBatchRequestSchema = exports.linkPreviewSchema = exports.applicationModerationTrustSchema = exports.reputationContextualInfluenceSchema = exports.reputationReviewingSchema = exports.reputationReportingSchema = exports.reputationConductSchema = exports.reputationContributionSchema = exports.reputationPersonhoodSchema = exports.identityBindingSchema = exports.registerIdentityBindingSchema = exports.reverseModerationEffectResultSchema = exports.applyModerationDecisionResultSchema = exports.moderationEffectSchema = exports.reverseModerationEffectSchema = exports.finalizeModerationDecisionSchema = exports.moderationDecisionEventSchema = exports.moderationPolicyVersionsSchema = void 0;
 exports.deviceTransferApproveResponseSchema = exports.deviceTransferApproveRequestSchema = exports.deviceTransferInfoResponseSchema = exports.deviceTransferInitResponseSchema = exports.deviceTransferInitRequestSchema = exports.devicePairingStatusSchema = exports.webauthnLoginVerifyRequestSchema = exports.webauthnRegisterVerifyRequestSchema = exports.webauthnLoginOptionsRequestSchema = exports.webauthnRegisterOptionsRequestSchema = exports.updateRolloutPatchSchema = exports.promoteRequestSchema = exports.rollbackToEmbeddedRequestSchema = exports.rollbackRequestSchema = exports.updateListResponseSchema = exports.channelListResponseSchema = exports.channelSchema = exports.rollbackToEmbeddedEntrySchema = exports.createUpdateResponseSchema = exports.updateSchema = exports.createUpdateRequestSchema = exports.updateAssetRefSchema = exports.assetCompleteResponseSchema = exports.assetCompleteResultItemSchema = exports.assetCompleteRequestSchema = exports.assetInitResponseSchema = exports.assetUploadTicketSchema = exports.assetInitRequestSchema = exports.assetInitItemSchema = exports.rolloutPercentSchema = exports.runtimeVersionSchema = exports.channelNameSchema = exports.sha256HexSchema = exports.updateAssetStatusSchema = exports.updateStatusSchema = exports.updatePlatformSchema = exports.backupStatusResponseSchema = exports.backupUploadRequestSchema = exports.encryptedBackupEnvelopeSchema = exports.backupLookupIdSchema = exports.rotateKeyCompleteResponseSchema = exports.rotateKeyCompleteRequestSchema = exports.rotateKeyChallengeResponseSchema = exports.loginResultSchema = exports.hubAuthorizeResultSchema = exports.hubAuthorizeRequestSchema = exports.hubActivateRequestSchema = exports.hubClaimRequestSchema = exports.hubSessionSchema = exports.browserHubRevokeResponseSchema = void 0;
 exports.providerErrorPassthroughSchema = exports.safeErrorTextSchema = exports.upstreamErrorCategorySchema = exports.inferenceErrorCodeSchema = exports.NON_RETRYABLE_INFERENCE_ERROR_CODES = exports.INFERENCE_ERROR_CODES = exports.inferenceAttributionSchema = exports.authenticatedPrincipalSchema = exports.billingPrincipalSchema = exports.inferenceScopeSchema = exports.INFERENCE_SCOPES = exports.unitPriceSchema = exports.usageQuantitySchema = exports.usageSourceSchema = exports.USAGE_SOURCES = exports.usageUnitSchema = exports.USAGE_UNITS = exports.moneySchema = exports.exactDecimalSchema = exports.INFERENCE_MONEY_SCALE = exports.currencyCodeSchema = exports.RESERVED_ALIA_PUBLISHER = exports.inferenceRegionSchema = exports.deploymentIdSchema = exports.inferenceProviderSlugSchema = exports.routingProfileSlugSchema = exports.modelReferenceSchema = exports.modelRevisionLabelSchema = exports.modelIdSchema = exports.modelSlugSchema = exports.publisherSlugSchema = exports.sha256DigestSchema = exports.inferenceHttpsUrlSchema = exports.inferenceDateSchema = exports.inferenceTimestampSchema = exports.inferenceEnvironmentSchema = exports.idempotencyKeySchema = exports.generationIdSchema = exports.requestIdSchema = exports.oxyCredentialIdSchema = exports.oxyApplicationIdSchema = exports.delegatedUserIdSchema = exports.oxyAccountIdSchema = exports.INFERENCE_CONTRACT_VERSION = exports.transparencyCheckpointListSchema = exports.transparencyInclusionProofSchema = exports.transparencyCheckpointSchema = exports.transparencyAnchorSchema = exports.transparencyCheckpointSignatureSchema = exports.deviceTransferDenyResponseSchema = void 0;
-exports.inferenceRouteSwitchDetailSchema = exports.inferenceStreamUsageEventSchema = exports.inferenceStreamToolCallEventSchema = exports.inferenceStreamDeltaEventSchema = exports.inferenceStreamStartEventSchema = exports.inferenceRequestSchema = exports.clientRequestMetadataSchema = exports.responseFormatSchema = exports.toolChoiceSchema = exports.toolDefinitionSchema = exports.samplingParametersSchema = exports.inferenceInputSchema = exports.inferenceMessageSchema = exports.inferenceMessageRoleSchema = exports.inferenceToolCallSchema = exports.inferenceContentPartSchema = exports.inferenceContentSourceSchema = exports.aliaModelReleaseManifestSchema = exports.aliaReleaseSignatureSchema = exports.aliaReleaseArtifactSchema = exports.authorizedRouteSchema = exports.routingPolicyReferenceSchema = exports.routingPolicySchema = exports.routingFallbackPolicySchema = exports.routingPolicyScopeSchema = exports.routingTargetSchema = exports.modelCatalogueEntrySchema = exports.catalogueServingProviderSummarySchema = exports.cataloguePublisherSummarySchema = exports.routingProfileSchema = exports.routingProfileCandidateSchema = exports.modelDeploymentSchema = exports.inferenceProviderSchema = exports.modelRevisionSchema = exports.catalogueModelSchema = exports.modelPublisherSchema = exports.modelSafetyMetadataSchema = exports.modelEvaluationResultSchema = exports.modelDeprecationSchema = exports.commercialPermissionSchema = exports.availabilityScopeSchema = exports.inferenceDataPolicySchema = exports.modelProvenanceSchema = exports.modelLicenseSchema = exports.modelCapabilitiesSchema = exports.inferenceModalitySchema = exports.priceSnapshotSchema = exports.priceVersionSchema = exports.priceVersionStatusSchema = exports.inferenceErrorSchema = void 0;
-exports.productPlanSchema = exports.planAllowanceSchema = exports.LIVE_PRODUCT_PLAN_STATUSES = exports.productPlanStatusSchema = exports.PRODUCT_PLAN_STATUSES = exports.reconciliationReportSchema = exports.reconciliationRunSchema = exports.reconciliationDiscrepancySchema = exports.reconciliationRunStatusSchema = exports.RECONCILIATION_RUN_STATUSES = exports.reconciliationDiscrepancyKindSchema = exports.RECONCILIATION_DISCREPANCY_KINDS = exports.autoRechargeAttemptSchema = exports.autoRechargeStatusSchema = exports.AUTO_RECHARGE_STATUSES = exports.externalPaymentSchema = exports.externalPaymentKindSchema = exports.EXTERNAL_PAYMENT_KINDS = exports.externalPaymentProviderSchema = exports.EXTERNAL_PAYMENT_PROVIDERS = exports.billingInvoiceSchema = exports.billingInvoiceStatusSchema = exports.BILLING_INVOICE_STATUSES = exports.accountBillingStateSchema = exports.billingProfileSchema = exports.autoRechargeSchema = exports.billingProfileStatusSchema = exports.BILLING_PROFILE_STATUSES = exports.billingModeSchema = exports.BILLING_MODES = exports.providerConnectionSchema = exports.providerConnectionStatusSchema = exports.providerConnectionValidationSchema = exports.providerSecretReferenceSchema = exports.providerConnectionScopeSchema = exports.usageRefundSchema = exports.usageRefundReasonSchema = exports.usageRefundSubjectSchema = exports.usageReceiptSchema = exports.normalizedUsageReportSchema = exports.inferenceRequestOutcomeSchema = exports.usageReservationSchema = exports.usageReservationStatusSchema = exports.usageReservationRequestSchema = exports.inferenceStreamEventSchema = exports.inferenceStreamDoneEventSchema = exports.inferenceFinishReasonSchema = exports.inferenceStreamErrorEventSchema = exports.inferenceStreamRouteSwitchEventSchema = exports.inferenceRouteSwitchReasonSchema = void 0;
-exports.productEntitlementSchema = exports.costCenterSpendSchema = exports.costCenterSchema = exports.costCenterStatusSchema = exports.COST_CENTER_STATUSES = exports.payAsYouGoEntitlementSchema = void 0;
+exports.samplingParametersSchema = exports.inferenceInputSchema = exports.inferenceMessageSchema = exports.inferenceMessageRoleSchema = exports.inferenceToolCallSchema = exports.inferenceContentPartSchema = exports.inferenceContentSourceSchema = exports.modelDocumentationSchema = exports.modelReleaseIngestionResultSchema = exports.modelReleaseIngestionRequestSchema = exports.modelLineDeclarationSchema = exports.modelGpaiDocumentationSchema = exports.modelDownstreamDocumentationSchema = exports.SYSTEMIC_RISK_COMPUTE_THRESHOLD_FLOPS = exports.trainingComputeFlopsSchema = exports.modelSystemicRiskTierSchema = exports.modelDistributionMethodSchema = exports.aliaModelReleaseManifestSchema = exports.aliaReleaseSignatureSchema = exports.aliaReleaseArtifactSchema = exports.authorizedRouteSchema = exports.routingPolicyReferenceSchema = exports.routingPolicySchema = exports.routingFallbackPolicySchema = exports.routingPolicyScopeSchema = exports.routingTargetSchema = exports.modelCatalogueEntrySchema = exports.catalogueServingProviderSummarySchema = exports.cataloguePublisherSummarySchema = exports.routingProfileSchema = exports.routingProfileCandidateSchema = exports.modelDeploymentSchema = exports.inferenceProviderSchema = exports.modelRevisionSchema = exports.catalogueModelSchema = exports.modelPublisherSchema = exports.modelSafetyMetadataSchema = exports.modelEvaluationResultSchema = exports.modelDeprecationSchema = exports.commercialPermissionSchema = exports.availabilityScopeSchema = exports.inferenceDataPolicySchema = exports.modelProvenanceSchema = exports.modelLicenseSchema = exports.modelCapabilitiesSchema = exports.inferenceModalitySchema = exports.priceSnapshotSchema = exports.priceVersionSchema = exports.priceVersionStatusSchema = exports.inferenceErrorSchema = void 0;
+exports.RECONCILIATION_DISCREPANCY_KINDS = exports.autoRechargeAttemptSchema = exports.autoRechargeStatusSchema = exports.AUTO_RECHARGE_STATUSES = exports.externalPaymentSchema = exports.externalPaymentKindSchema = exports.EXTERNAL_PAYMENT_KINDS = exports.externalPaymentProviderSchema = exports.EXTERNAL_PAYMENT_PROVIDERS = exports.billingInvoiceSchema = exports.billingInvoiceStatusSchema = exports.BILLING_INVOICE_STATUSES = exports.accountBillingStateSchema = exports.billingProfileSchema = exports.autoRechargeSchema = exports.billingProfileStatusSchema = exports.BILLING_PROFILE_STATUSES = exports.billingModeSchema = exports.BILLING_MODES = exports.providerConnectionSchema = exports.providerConnectionStatusSchema = exports.providerConnectionValidationSchema = exports.providerSecretReferenceSchema = exports.providerConnectionScopeSchema = exports.PROVIDER_SECRET_REFERENCE_NAMESPACE = exports.usageRefundSchema = exports.usageRefundReasonSchema = exports.usageRefundSubjectSchema = exports.usageReceiptSchema = exports.normalizedUsageReportSchema = exports.inferenceRequestOutcomeSchema = exports.usageReservationSchema = exports.usageReservationStatusSchema = exports.usageReservationRequestSchema = exports.inferenceStreamEventSchema = exports.inferenceStreamDoneEventSchema = exports.inferenceFinishReasonSchema = exports.inferenceStreamErrorEventSchema = exports.inferenceStreamRouteSwitchEventSchema = exports.inferenceRouteSwitchReasonSchema = exports.inferenceRouteSwitchDetailSchema = exports.inferenceStreamUsageEventSchema = exports.inferenceStreamToolCallEventSchema = exports.inferenceStreamDeltaEventSchema = exports.inferenceStreamStartEventSchema = exports.inferenceRequestSchema = exports.clientRequestMetadataSchema = exports.responseFormatSchema = exports.toolChoiceSchema = exports.toolDefinitionSchema = void 0;
+exports.productEntitlementSchema = exports.costCenterSpendSchema = exports.costCenterSchema = exports.costCenterStatusSchema = exports.COST_CENTER_STATUSES = exports.payAsYouGoEntitlementSchema = exports.productPlanSchema = exports.planAllowanceSchema = exports.LIVE_PRODUCT_PLAN_STATUSES = exports.productPlanStatusSchema = exports.PRODUCT_PLAN_STATUSES = exports.reconciliationReportSchema = exports.reconciliationRunSchema = exports.reconciliationDiscrepancySchema = exports.reconciliationRunStatusSchema = exports.RECONCILIATION_RUN_STATUSES = exports.reconciliationDiscrepancyKindSchema = void 0;
 var accountGraph_1 = require("./accountGraph");
 Object.defineProperty(exports, "ACCOUNT_KINDS", { enumerable: true, get: function () { return accountGraph_1.ACCOUNT_KINDS; } });
 Object.defineProperty(exports, "accountKindSchema", { enumerable: true, get: function () { return accountGraph_1.accountKindSchema; } });
@@ -440,6 +440,20 @@ var aliaModelRelease_1 = require("./inference/aliaModelRelease");
 Object.defineProperty(exports, "aliaReleaseArtifactSchema", { enumerable: true, get: function () { return aliaModelRelease_1.aliaReleaseArtifactSchema; } });
 Object.defineProperty(exports, "aliaReleaseSignatureSchema", { enumerable: true, get: function () { return aliaModelRelease_1.aliaReleaseSignatureSchema; } });
 Object.defineProperty(exports, "aliaModelReleaseManifestSchema", { enumerable: true, get: function () { return aliaModelRelease_1.aliaModelReleaseManifestSchema; } });
+var modelDocumentation_1 = require("./inference/modelDocumentation");
+// 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.
+Object.defineProperty(exports, "modelDistributionMethodSchema", { enumerable: true, get: function () { return modelDocumentation_1.modelDistributionMethodSchema; } });
+Object.defineProperty(exports, "modelSystemicRiskTierSchema", { enumerable: true, get: function () { return modelDocumentation_1.modelSystemicRiskTierSchema; } });
+Object.defineProperty(exports, "trainingComputeFlopsSchema", { enumerable: true, get: function () { return modelDocumentation_1.trainingComputeFlopsSchema; } });
+Object.defineProperty(exports, "SYSTEMIC_RISK_COMPUTE_THRESHOLD_FLOPS", { enumerable: true, get: function () { return modelDocumentation_1.SYSTEMIC_RISK_COMPUTE_THRESHOLD_FLOPS; } });
+Object.defineProperty(exports, "modelDownstreamDocumentationSchema", { enumerable: true, get: function () { return modelDocumentation_1.modelDownstreamDocumentationSchema; } });
+Object.defineProperty(exports, "modelGpaiDocumentationSchema", { enumerable: true, get: function () { return modelDocumentation_1.modelGpaiDocumentationSchema; } });
+Object.defineProperty(exports, "modelLineDeclarationSchema", { enumerable: true, get: function () { return modelDocumentation_1.modelLineDeclarationSchema; } });
+Object.defineProperty(exports, "modelReleaseIngestionRequestSchema", { enumerable: true, get: function () { return modelDocumentation_1.modelReleaseIngestionRequestSchema; } });
+Object.defineProperty(exports, "modelReleaseIngestionResultSchema", { enumerable: true, get: function () { return modelDocumentation_1.modelReleaseIngestionResultSchema; } });
+Object.defineProperty(exports, "modelDocumentationSchema", { enumerable: true, get: function () { return modelDocumentation_1.modelDocumentationSchema; } });
 var request_1 = require("./inference/request");
 // The normalized Oxy→data-plane request envelope.
 Object.defineProperty(exports, "inferenceContentSourceSchema", { enumerable: true, get: function () { return request_1.inferenceContentSourceSchema; } });
@@ -480,6 +494,7 @@ Object.defineProperty(exports, "usageRefundReasonSchema", { enumerable: true, ge
 Object.defineProperty(exports, "usageRefundSchema", { enumerable: true, get: function () { return usage_1.usageRefundSchema; } });
 var providerConnection_1 = require("./inference/providerConnection");
 // BYOK connection metadata that structurally cannot carry a secret.
+Object.defineProperty(exports, "PROVIDER_SECRET_REFERENCE_NAMESPACE", { enumerable: true, get: function () { return providerConnection_1.PROVIDER_SECRET_REFERENCE_NAMESPACE; } });
 Object.defineProperty(exports, "providerConnectionScopeSchema", { enumerable: true, get: function () { return providerConnection_1.providerConnectionScopeSchema; } });
 Object.defineProperty(exports, "providerSecretReferenceSchema", { enumerable: true, get: function () { return providerConnection_1.providerSecretReferenceSchema; } });
 Object.defineProperty(exports, "providerConnectionValidationSchema", { enumerable: true, get: function () { return providerConnection_1.providerConnectionValidationSchema; } });

package/dist/cjs/inference/aliaModelRelease.js

@@ -36,14 +36,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
@@ -65,7 +73,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/cjs/inference/modelDocumentation.js

@@ -0,0 +1,433 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.modelDocumentationSchema = exports.modelReleaseIngestionResultSchema = exports.modelReleaseIngestionRequestSchema = exports.modelLineDeclarationSchema = exports.modelGpaiDocumentationSchema = exports.modelDownstreamDocumentationSchema = exports.SYSTEMIC_RISK_COMPUTE_THRESHOLD_FLOPS = exports.trainingComputeFlopsSchema = exports.modelSystemicRiskTierSchema = exports.modelDistributionMethodSchema = void 0;
+const zod_1 = require("zod");
+const aliaModelRelease_1 = require("./aliaModelRelease");
+const catalogue_1 = require("./catalogue");
+const identifiers_1 = require("./identifiers");
+/* -------------------------------------------------------------------------- */
+/*  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.
+ */
+exports.modelDistributionMethodSchema = zod_1.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.
+ */
+exports.modelSystemicRiskTierSchema = zod_1.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}.
+ */
+exports.trainingComputeFlopsSchema = zod_1.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.
+ */
+exports.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.
+ */
+exports.modelDownstreamDocumentationSchema = zod_1.z
+    .object({
+    /** Annex XI §1(2), Annex XII §1(a): the tasks the model is intended for. */
+    intendedTasks: zod_1.z.string().min(1).max(2000).optional(),
+    /** Annex XI §1(4), Annex XII §1(a). */
+    distributionMethods: zod_1.z.array(exports.modelDistributionMethodSchema).min(1),
+    /** Annex XI §1(5), reachable through Annex XII §1(a) ("points 1 to 5"). */
+    architecture: zod_1.z.string().min(1).max(500).optional(),
+    /** Annex XI §1(5): the number of parameters. */
+    parameterCount: zod_1.z.number().int().positive().safe().optional(),
+    /** Article 53(1)(d): the publicly available summary of training content. */
+    trainingDataSummaryUrl: identifiers_1.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: identifiers_1.inferenceHttpsUrlSchema,
+    /** Article 51. */
+    systemicRisk: exports.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: zod_1.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.
+ */
+exports.modelGpaiDocumentationSchema = exports.modelDownstreamDocumentationSchema
+    .extend({
+    /** Annex XI §2(b): the computational resources used for training. */
+    trainingComputeFlops: exports.trainingComputeFlopsSchema.optional(),
+    /** Annex XI §2(b): the training time. */
+    trainingTimeHours: zod_1.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: zod_1.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: identifiers_1.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: zod_1.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: zod_1.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) >= exports.SYSTEMIC_RISK_COMPUTE_THRESHOLD_FLOPS) {
+        ctx.addIssue({
+            code: zod_1.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: zod_1.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.
+ */
+exports.modelLineDeclarationSchema = zod_1.z
+    .object({
+    displayName: zod_1.z.string().min(1).max(200),
+    description: zod_1.z.string().max(4000).optional(),
+    capabilities: catalogue_1.modelCapabilitiesSchema,
+    knowledgeCutoff: identifiers_1.inferenceDateSchema.optional(),
+    releasedOn: identifiers_1.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.
+ */
+exports.modelReleaseIngestionRequestSchema = zod_1.z
+    .object({
+    /** See `version.ts`: an ingestion payload is a whole message on the wire. */
+    schemaVersion: zod_1.z.literal(1),
+    manifest: aliaModelRelease_1.aliaModelReleaseManifestSchema,
+    gpaiDocumentation: exports.modelGpaiDocumentationSchema,
+    model: exports.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`.
+ */
+exports.modelReleaseIngestionResultSchema = zod_1.z
+    .object({
+    /** See `version.ts`: served on its own, so it is versioned. */
+    schemaVersion: zod_1.z.literal(1),
+    releaseId: zod_1.z.string().min(1).max(128),
+    modelId: identifiers_1.modelIdSchema,
+    revision: identifiers_1.modelRevisionLabelSchema,
+    reference: identifiers_1.modelReferenceSchema,
+    /** Whether this request created the release, or found it already ingested. */
+    outcome: zod_1.z.enum(['ingested', 'already_ingested']),
+    artifactCount: zod_1.z.number().int().positive().safe(),
+    signatureCount: zod_1.z.number().int().positive().safe(),
+    evaluationCount: zod_1.z.number().int().nonnegative().safe(),
+    ingestedAt: identifiers_1.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.
+ */
+exports.modelDocumentationSchema = zod_1.z
+    .object({
+    /** See `version.ts`: this is a public response shape. */
+    schemaVersion: zod_1.z.literal(1),
+    modelId: identifiers_1.modelIdSchema,
+    revision: identifiers_1.modelRevisionLabelSchema,
+    /** The exact string a customer pins. */
+    reference: identifiers_1.modelReferenceSchema,
+    /** Whether a bare `<publisher>/<model>` resolves to this revision today. */
+    isCurrentRevision: zod_1.z.boolean(),
+    releasedAt: identifiers_1.inferenceTimestampSchema,
+    retiredAt: identifiers_1.inferenceTimestampSchema.optional(),
+    modelCardUrl: identifiers_1.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: identifiers_1.sha256DigestSchema.optional(),
+    license: catalogue_1.modelLicenseSchema,
+    provenance: catalogue_1.modelProvenanceSchema,
+    evaluations: zod_1.z.array(catalogue_1.modelEvaluationResultSchema).default([]),
+    safety: catalogue_1.modelSafetyMetadataSchema.optional(),
+    /** Absent for a revision with no documentation record — i.e. every one Oxy did not release. */
+    gpai: exports.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: zod_1.z.ZodIssueCode.custom,
+            path: ['reference'],
+            message: 'reference must be exactly <modelId>@<revision>',
+        });
+    }
+});