@oxyhq/contracts 0.29.0 → 0.31.0

package/dist/esm/accountGraph.js

@@ -349,4 +349,45 @@ export const createAccountRequestSchema = z.object({
     description: z.string().trim().max(1000).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/identity.js

@@ -204,6 +204,37 @@ export const exportAttestationSchema = z.object({
     signature: z.string(),
     signedAt: z.number(),
 });
+export const exportUsageReceiptSchema = z.object({
+    receiptId: z.string(),
+    requestId: z.string(),
+    settledAt: z.string(),
+    billedAmount: z.string(),
+    currency: z.string(),
+    outcome: z.string(),
+    resolvedModelReference: z.string(),
+    servingProvider: z.string(),
+    platformFeeOnly: z.boolean(),
+});
+export const exportLedgerEntrySchema = z.object({
+    entryId: z.string(),
+    kind: z.string(),
+    currency: z.string(),
+    createdAt: z.string(),
+});
+export const exportUsageReservationSchema = z.object({
+    reservationId: z.string(),
+    requestId: z.string(),
+    status: z.string(),
+    reservedAmount: z.string(),
+    currency: z.string(),
+    createdAt: z.string(),
+    expiresAt: z.string(),
+});
+export const exportFinancialSectionSchema = z.object({
+    receipts: z.array(exportUsageReceiptSchema),
+    ledgerEntries: z.array(exportLedgerEntrySchema),
+    reservations: z.array(exportUsageReservationSchema),
+});
 export const exportBundleSchema = z.object({
     '$schema': z.string(),
     exportedAt: z.string(),
@@ -218,6 +249,7 @@ export const exportBundleSchema = z.object({
         following: z.array(z.string()),
         followers: z.array(z.string()),
     }),
+    financial: exportFinancialSectionSchema,
     attestation: exportAttestationSchema.nullable(),
     proof: exportAttestationSchema.optional(),
 });

package/dist/esm/index.js

@@ -30,7 +30,7 @@ export {
 recommendationExcludeTypeSchema, recommendationBoostSchema, recommendationSignalWeightsSchema, recommendationRequestSchema, recommendationCountSchema, recommendationItemSchema, recommendationResponseSchema, appEndorsementInputSchema, appInterestInputSchema, appUserSignalIngestSchema, appAffinityEventTypeSchema, appAffinityEventSchema, appAffinityEventsIngestSchema, } from './recommendations.js';
 export { 
 // Schemas
-verificationMethodSchema, didServiceSchema, didDocumentSchema, signedRecordEnvelopeSchema, verifiedDomainSchema, domainVerificationRequestSchema, domainVerificationInstructionsSchema, authMethodEntrySchema, authMethodsResponseSchema, exportAttestationSchema, exportBundleSchema, } from './identity.js';
+verificationMethodSchema, didServiceSchema, didDocumentSchema, signedRecordEnvelopeSchema, verifiedDomainSchema, domainVerificationRequestSchema, domainVerificationInstructionsSchema, authMethodEntrySchema, authMethodsResponseSchema, exportAttestationSchema, exportUsageReceiptSchema, exportLedgerEntrySchema, exportUsageReservationSchema, exportFinancialSectionSchema, exportBundleSchema, } from './identity.js';
 export { 
 // Schemas
 oxySignedRecordTypeSchema, } from './oxyRecordTypes.js';
@@ -113,7 +113,7 @@ export {
 // are branded apart so a delegated end user can never become the payer.
 oxyAccountIdSchema, delegatedUserIdSchema, oxyApplicationIdSchema, oxyCredentialIdSchema, requestIdSchema, generationIdSchema, idempotencyKeySchema, inferenceEnvironmentSchema, 
 // Wire primitives
-inferenceTimestampSchema, inferenceDateSchema, inferenceHttpsUrlSchema, 
+inferenceTimestampSchema, inferenceDateSchema, inferenceHttpsUrlSchema, sha256DigestSchema, 
 // Catalogue references
 publisherSlugSchema, modelSlugSchema, modelIdSchema, modelRevisionLabelSchema, modelReferenceSchema, routingProfileSlugSchema, inferenceProviderSlugSchema, deploymentIdSchema, inferenceRegionSchema, RESERVED_ALIA_PUBLISHER, } from './inference/identifiers.js';
 export { 
@@ -134,7 +134,17 @@ inferenceModalitySchema, modelCapabilitiesSchema, modelLicenseSchema, modelProve
 export { 
 // Routing policy: every control, plus the refinement that rejects a policy
 // no route could ever satisfy.
-routingTargetSchema, routingPolicyScopeSchema, routingFallbackPolicySchema, routingPolicySchema, routingPolicyReferenceSchema, } from './inference/routingPolicy.js';
+routingTargetSchema, routingPolicyScopeSchema, routingFallbackPolicySchema, routingPolicySchema, routingPolicyReferenceSchema, 
+// What the data plane actually receives: the routes the policy authorized.
+authorizedRouteSchema, } from './inference/routingPolicy.js';
+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';
@@ -146,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

@@ -0,0 +1,259 @@
+/**
+ * The signed Alia model release manifest — the ingestion contract for a
+ * first-party model release.
+ *
+ * The catalogue already STORES everything such a manifest carries: the model
+ * card, the licence block, the provenance and base model, the evaluation table,
+ * the safety metadata, and an artifact digest with a `sha256:<64 hex>` CHECK.
+ * What did not exist was the manifest itself — a single document Alia SIGNS,
+ * asserting all of it at once — and that is the gap this shape closes. Nothing
+ * here re-declares a catalogue field; the manifest COMPOSES the published shapes
+ * so a manifest and the catalogue row it produces cannot describe a release
+ * differently.
+ *
+ * ## The manifest tightens the revision it carries
+ *
+ * `modelRevisionSchema` makes `modelCardUrl`, `artifactDigest`, `evaluations`
+ * and `safety` optional, because a third-party route legitimately has none of
+ * them — Oxy did not train those weights and cannot publish a card for them. A
+ * FIRST-PARTY release has no such excuse: the documentation trail is the reason
+ * a release manifest exists at all, and a model Alia ships without one is not a
+ * release, it is a deployment. So the refinement below requires all four,
+ * without changing the catalogue shape that a third-party entry still parses
+ * through.
+ *
+ * ## `.strict()` at the top level, and here that is forced rather than chosen
+ *
+ * The shapes exchanged with the data plane tolerate an unknown field, because
+ * refusing a producer one minor version ahead is a worse failure than ignoring
+ * its addition (`version.ts`). A SIGNED document inverts that: the signature is
+ * over the canonical bytes of the manifest, so a field silently stripped at this
+ * parse is a field missing from the bytes Oxy re-canonicalizes, and verification
+ * fails. A tolerant parse would therefore report "the signature is invalid" for
+ * what is really "this build does not understand this manifest" — the wrong
+ * diagnosis of the right problem. Strict says the true thing, and the cost is
+ * bounded: ingestion is a release-time operation an operator retries once Oxy
+ * takes the newer contract, not a served request that becomes unsettleable.
+ *
+ * ## 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.
+ *
+ * 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
+ * recomputes it. Storing the digest beside the document it digests would be a
+ * second source of truth for one fact, and a verifier that compared the
+ * signature against the DECLARED digest rather than the recomputed one would
+ * verify nothing at all.
+ *
+ * **No verification RESULT.** Whether a signature checked out is Oxy's finding
+ * about the document, not a claim the document makes about itself; a `verified`
+ * field inside a signed manifest is the signer asserting its own signature.
+ *
+ * ## The open owner decision this shape does not take
+ *
+ * **What signs, and what verifies, is not decided.** Oxy holds no Alia signing
+ * key, and whether to resolve `keyId` through the existing attestation machinery
+ * (`services/oxyVerificationResolver.ts`, the civic attestation code) or to
+ * introduce a dedicated Alia release key is a real choice with different
+ * 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, 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.
+ */
+import { z } from 'zod';
+import { modelLicenseSchema, modelProvenanceSchema, modelRevisionSchema, } from './catalogue.js';
+import { inferenceTimestampSchema, RESERVED_ALIA_PUBLISHER, sha256DigestSchema, } from './identifiers.js';
+/**
+ * One artifact of a release, by path and digest.
+ *
+ * `sizeBytes` is required beside the digest so a verifier can refuse a stream
+ * that is the wrong length before reading it to the end, rather than only after.
+ */
+export const aliaReleaseArtifactSchema = z
+    .object({
+    /** Path within the release, e.g. `model-00001-of-00004.safetensors`. */
+    path: z.string().min(1).max(512),
+    digest: sha256DigestSchema,
+    sizeBytes: z.number().int().positive().safe(),
+    mediaType: z.string().min(1).max(255).optional(),
+})
+    .strict();
+/**
+ * One detached signature over the manifest.
+ *
+ * `algorithm` is a CLOSED enum with one member, and both halves of that are
+ * deliberate. Closed, because a verifier that trusts a document's own algorithm
+ * name accepts whatever that document nominates, `none` included. One member,
+ * because Ed25519 is the scheme ADR 0012 already chose for asymmetric
+ * verification on this platform, and naming a scheme nothing here can check
+ * would be advertising a capability that does not exist. A second member lands
+ * when a verifier for it does — which is a closed enum gaining a member, and
+ * therefore a MINOR contract-set change the handshake surfaces (`version.ts`).
+ *
+ * `keyId` is opaque on purpose: see the header. It identifies the public key
+ * without saying what resolves it.
+ *
+ * The signature covers the canonical serialization (RFC 8785 JCS) of the
+ * manifest with `signatures` removed. The canonicalization is NAMED rather than
+ * left implicit because a digest over "the manifest" is not verifiable by two
+ * implementations that serialize JSON differently; naming it is a mechanical
+ * necessity and is independent of the open question of which key signs.
+ */
+export const aliaReleaseSignatureSchema = z
+    .object({
+    algorithm: z.enum(['ed25519']),
+    canonicalization: z.enum(['jcs']),
+    /** Opaque identifier of the public key. Resolving it is undecided. */
+    keyId: z.string().min(1).max(256),
+    /**
+     * Unpadded base64url. Exactly 86 characters, which is a 64-byte Ed25519
+     * signature — the one algorithm above. A second algorithm moves this length
+     * into a refinement keyed on `algorithm`.
+     */
+    signature: z
+        .string()
+        .regex(/^[A-Za-z0-9_-]{86}$/, 'signature must be a 64-byte ed25519 signature in unpadded base64url'),
+    signedAt: inferenceTimestampSchema,
+})
+    .strict();
+/**
+ * A signed release of an `alia/*` model revision.
+ *
+ * `signatures` is a LIST rather than one signature, because "what signs" is
+ * undecided: a single field would presuppose one signer, while a list lets an
+ * Alia release key and an existing attestation co-sign the same document without
+ * either being retrofitted later.
+ */
+export const aliaModelReleaseManifestSchema = z
+    .object({
+    /** See `version.ts`: an ingestion payload is a whole message on the wire. */
+    schemaVersion: z.literal(1),
+    /** The release's own identity, so ingestion is idempotent on it. */
+    releaseId: z.string().min(1).max(128),
+    issuedAt: inferenceTimestampSchema,
+    /**
+     * The revision being released. Carries its OWN `schemaVersion`, like
+     * `billingProfileSchema` inside `accountBillingStateSchema`: the manifest's
+     * version governs the manifest and the revision's governs the revision,
+     * which is two versions of two things rather than two versions of one.
+     */
+    revision: modelRevisionSchema,
+    /** On the MODEL rather than the revision in the catalogue, so carried here. */
+    provenance: modelProvenanceSchema,
+    license: modelLicenseSchema,
+    artifacts: z.array(aliaReleaseArtifactSchema).min(1),
+    signatures: z.array(aliaReleaseSignatureSchema).min(1),
+})
+    .strict()
+    .superRefine((manifest, ctx) => {
+    // The same rule `catalogueModelSchema` enforces on a model, applied to the
+    // carrier that creates one: `alia/*` names models Alia actually owns or
+    // derived, and a manifest is the document that would launder somebody else's
+    // weights into the namespace.
+    const publisher = manifest.revision.modelId.slice(0, manifest.revision.modelId.indexOf('/'));
+    if (publisher !== RESERVED_ALIA_PUBLISHER) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['revision', 'modelId'],
+            message: `an Alia release manifest releases a ${RESERVED_ALIA_PUBLISHER}/* model`,
+        });
+    }
+    if (manifest.provenance.releaseKind !== 'first_party_original' &&
+        manifest.provenance.releaseKind !== 'first_party_derived') {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['provenance', 'releaseKind'],
+            message: 'an Alia release manifest describes a first-party release',
+        });
+    }
+    // A derived model's base is the licence-attribution trail. Recording the
+    // derivation without naming what it derives from loses exactly the fact
+    // attribution needs.
+    if (manifest.provenance.releaseKind === 'first_party_derived' &&
+        manifest.provenance.baseModelId === undefined) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['provenance', 'baseModelId'],
+            message: 'a derived release names the model it derives from',
+        });
+    }
+    // The four fields a third-party catalogue entry may omit and a first-party
+    // release may not. See the header.
+    if (manifest.revision.modelCardUrl === undefined) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['revision', 'modelCardUrl'],
+            message: 'a first-party release publishes a model card',
+        });
+    }
+    if (manifest.revision.safety === undefined) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['revision', 'safety'],
+            message: 'a first-party release publishes its safety metadata',
+        });
+    }
+    if (manifest.revision.evaluations.length === 0) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['revision', 'evaluations'],
+            message: 'a first-party release publishes at least one evaluation result',
+        });
+    }
+    // The digest the catalogue will serve has to be one of the digests this
+    // manifest signed. Otherwise the signature covers a set of artifacts that
+    // does not include the weights anybody runs.
+    if (manifest.revision.artifactDigest === undefined) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['revision', 'artifactDigest'],
+            message: 'a first-party release names the digest of the artifact it serves',
+        });
+    }
+    else if (!manifest.artifacts.some((artifact) => artifact.digest === manifest.revision.artifactDigest)) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['revision', 'artifactDigest'],
+            message: 'the served artifact digest must appear among the signed artifacts',
+        });
+    }
+    const paths = manifest.artifacts.map((artifact) => artifact.path);
+    if (new Set(paths).size !== paths.length) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['artifacts'],
+            message: 'each artifact path appears once in a release',
+        });
+    }
+    // Two signatures from one key are one signature written twice, and a
+    // duplicate would make a "two independent signers" check pass on one signer.
+    const keyIds = manifest.signatures.map((signature) => signature.keyId);
+    if (new Set(keyIds).size !== keyIds.length) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['signatures'],
+            message: 'each signing key signs a manifest once',
+        });
+    }
+});

package/dist/esm/inference/catalogue.js

@@ -27,7 +27,7 @@
  * Decided in: docs/adr/0008-catalogue-concept-separation.md.
  */
 import { z } from 'zod';
-import { deploymentIdSchema, inferenceDateSchema, inferenceHttpsUrlSchema, inferenceProviderSlugSchema, inferenceRegionSchema, inferenceTimestampSchema, modelIdSchema, modelReferenceSchema, modelRevisionLabelSchema, modelSlugSchema, publisherSlugSchema, RESERVED_ALIA_PUBLISHER, routingProfileSlugSchema, } from './identifiers.js';
+import { deploymentIdSchema, inferenceDateSchema, inferenceHttpsUrlSchema, inferenceProviderSlugSchema, inferenceRegionSchema, inferenceTimestampSchema, modelIdSchema, modelReferenceSchema, modelRevisionLabelSchema, modelSlugSchema, publisherSlugSchema, RESERVED_ALIA_PUBLISHER, routingProfileSlugSchema, sha256DigestSchema, } from './identifiers.js';
 import { priceSnapshotSchema } from './priceVersion.js';
 /* -------------------------------------------------------------------------- */
 /*  Shared catalogue vocabulary                                               */
@@ -279,10 +279,7 @@ export const modelRevisionSchema = z
     releasedAt: inferenceTimestampSchema,
     retiredAt: inferenceTimestampSchema.optional(),
     /** Digest of the served artifact, where Oxy hosts the weights itself. */
-    artifactDigest: z
-        .string()
-        .regex(/^sha256:[a-f0-9]{64}$/, 'artifact digest must be sha256:<64 lowercase hex>')
-        .optional(),
+    artifactDigest: sha256DigestSchema.optional(),
     modelCardUrl: inferenceHttpsUrlSchema.optional(),
     evaluations: z.array(modelEvaluationResultSchema).default([]),
     safety: modelSafetyMetadataSchema.optional(),

package/dist/esm/inference/identifiers.js

@@ -59,8 +59,16 @@ export const oxyCredentialIdSchema = z.string().min(1).max(64);
  * 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 and on anything it can be asked
- * about later.
+ * 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
@@ -106,6 +114,18 @@ 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                                                      */
 /* -------------------------------------------------------------------------- */