@datalayer/agent-runtimes 1.0.29 → 1.3.10

package/lib/models/Environment.d.ts

@@ -1,5 +1,16 @@
 import { IContent } from './Content';
 import { IItem } from './Item';
+import type { Environment as EnvironmentDocument } from './environments.generated';
+import type { IRuntimeEnvironment } from './Runtime';
+import type { CreateRuntimeResponse } from './RuntimeDTO';
+/**
+ * The Environment specification, `environments.datalayer.io/v1alpha1`,
+ * generated from the JSON Schema `code-sandboxes` exports from its pydantic
+ * models (PLAN_ENV.md, D-14). Regenerated by `npm run generate:environments`.
+ */
+export * as EnvironmentSchema from './environments.generated';
+/** An Environment document: `apiVersion`, `kind`, `metadata` and `spec`. */
+export type { EnvironmentDocument };
 export type IEnvironment = IItem & {
     type: 'environment';
 };
@@ -25,6 +36,28 @@ export interface ISnippet {
      */
     code: string;
 }
+/** Where an environment comes from: the platform's catalogue, or a user's registry. */
+export type EnvironmentOrigin = 'platform' | 'user';
+/** Whose a user environment is: a person's account, or an organization's. */
+export type EnvironmentOwnerType = 'user' | 'organization';
+/**
+ * Who a user environment is shown to (D-19). An environment becomes `public`
+ * only by publishing a version to the Library (D-12).
+ */
+export type EnvironmentVisibility = 'private' | 'organization' | 'public';
+/**
+ * Where a version stands (section 4.2), as `VersionState` of
+ * `code_sandboxes.environments.lifecycle` names it.
+ */
+export type EnvironmentVersionStatus = 'draft' | 'resolving' | 'resolved' | 'building' | 'validating' | 'ready' | 'partially_ready' | 'failed' | 'deprecated';
+/** The build statuses nothing more happens to. Any other status is still to run or running. */
+export declare const TERMINAL_ENVIRONMENT_BUILD_STATUSES: readonly ["succeeded", "failed", "cancelled"];
+/** The version a user environment's launches resolve to, as `GET /environments` names it. */
+export interface IPromotedEnvironmentVersion {
+    uid: string;
+    version: number;
+    status: EnvironmentVersionStatus;
+}
 /**
  * Datalayer environment
  */
@@ -50,9 +83,13 @@ export interface IDatalayerEnvironment {
      */
     language: string;
     /**
-     * Docker image
+     * Docker image.
+     *
+     * A platform entry names one. A user environment does not: what it runs is
+     * an artifact of its promoted version, pinned by digest and resolved by the
+     * platform at launch, and never shown to a client (PLAN_ENV.md, E1-11).
      */
-    dockerImage: string;
+    dockerImage?: string;
     /**
      * Example notebook URL
      */
@@ -71,16 +108,535 @@ export interface IDatalayerEnvironment {
         givenNameTemplate?: string;
     };
     /**
-     * Environment credits burning rate
+     * Environment credits burning rate, per second.
+     *
+     * A platform entry carries its pool's. A user environment carries the rate
+     * of the size class its promoted version names (D-4), and carries none while
+     * no version is promoted or while its class is unpriced — absent means
+     * UNKNOWN, not free, and a launch that cannot be priced is refused rather
+     * than reserved at zero (E1-19).
      */
-    burning_rate: number;
+    burning_rate?: number;
+    /**
+     * The size class a user environment's promoted version names, which is what
+     * prices it (D-4). Absent on a platform entry, which carries its own rate.
+     */
+    sizeClass?: string;
     /**
      * Environment server resources
      */
     resources?: IResources;
     /**
-     * Environment contents.
+     * The contents the Environment selects, as `{uid, name, mount, permissions}`.
+     *
+     * Absent when the Environment selects none.
      */
     contents?: IContent[];
+    /**
+     * The registry uid of a user environment. Absent on a platform entry.
+     */
+    uid?: string;
+    /**
+     * `user` for an environment of the registry. Absent on a platform entry.
+     */
+    origin?: EnvironmentOrigin;
+    /**
+     * A user environment's owner uid, or a platform entry's owner, such as
+     * `datalayer` or the provider of an external catalogue entry.
+     */
+    owner?: string;
+    /**
+     * The version launches of a user environment resolve to, `null` while none
+     * is promoted. Absent on a platform entry.
+     */
+    promotedVersion?: IPromotedEnvironmentVersion | null;
+    /**
+     * The variants the promoted version builds for, empty while none is
+     * promoted. Absent on a platform entry.
+     */
+    variants?: string[];
+    /**
+     * The variants of `variants` a sandbox can actually start on: those whose
+     * artifact is built. A variant missing from this list has nothing to launch,
+     * and is offered with a build instead (E1-19). Absent on a platform entry,
+     * and from a Runtimes older than E1-19.
+     */
+    availableVariants?: string[];
+    /**
+     * Set when this entry reached the picker through the public Library rather
+     * than the caller's own accounts (D-12, E2-16): a published environment
+     * someone can launch or fork without owning it. It is listed under its own
+     * *Library* heading, so a published environment is where a reader who came
+     * from its public page expects to find it.
+     */
+    fromLibrary?: boolean;
+}
+/**
+ * A refusal, as every registry route answers one (section 10): a code, a
+ * message and the correlation id; the field at fault, the detail, and for a
+ * code of the taxonomy whether a retry can succeed and what the user does.
+ */
+export interface IEnvironmentsError {
+    code: string;
+    message: string;
+    correlationId: string;
+    field?: string;
+    detail?: Record<string, unknown>;
+    retryable?: boolean;
+    userAction?: string;
+}
+/** A user environment, as the registry answers it. */
+export interface IEnvironmentRecord {
+    uid: string;
+    /** Unique per owner: a DNS-1123 label. */
+    name: string;
+    title: string;
+    description: string;
+    origin: EnvironmentOrigin;
+    ownerType: EnvironmentOwnerType;
+    ownerUid: string;
+    visibility: EnvironmentVisibility;
+    promotedVersionUid: string | null;
+    createdBy: string;
+    createdAt: string;
+    updatedAt: string;
+    archivedAt: string | null;
+    deletedAt: string | null;
+    /** What a conditional write names in `If-Match`. */
+    etag: string;
+}
+/** A version of an environment: its specification, and where it stands. */
+export interface IEnvironmentVersionRecord {
+    uid: string;
+    environmentUid: string;
+    ownerUid: string;
+    /** Monotonic per environment, from 1. */
+    version: number;
+    label: string;
+    /** The specification, with its defaults written out. */
+    spec: EnvironmentDocument;
+    specSchemaVersion: string;
+    /** `sha256:<hex>` of the canonical spec. */
+    specDigest: string;
+    contractVersion: string;
+    sourceType: string;
+    sourceFormat: string;
+    sourceArchiveRef: string;
+    sourceArchiveDigest: string;
+    /** Empty until the version is resolved. */
+    lockDigest: string;
+    /** Variant to base digest, once resolved. */
+    resolvedBases: Record<string, string>;
+    status: EnvironmentVersionStatus;
+    requiredVariants: string[];
+    optionalVariants: string[];
+    validationSummary: Record<string, unknown>;
+    /**
+     * Every variant's Appendix B check 5 (its installed package versions), as
+     * `{ variant: { package: version } }`, once a variant's smoke test has
+     * reported it (PLAN_ENV E2-08). Absent from a Runtimes before E1-29 and
+     * `{}` until the first variant reports.
+     */
+    packageReport?: Record<string, Record<string, string>>;
+    failureCode: string;
+    createdBy: string;
+    createdAt: string;
+    updatedAt: string;
+    promotedAt: string | null;
+    deprecatedAt: string | null;
+    /**
+     * The promotion that last made this version the promoted one, kept after a
+     * later one is promoted; `null` for a version never promoted, and absent
+     * from a Runtimes before E1-15.
+     */
+    promotion?: IEnvironmentPromotionRecord | null;
+    /** What a conditional write names in `If-Match`. */
+    etag: string;
+}
+/** One artifact a promotion put in service, with the policy decision it carried (E1-08). */
+export interface IEnvironmentPromotionPolicyDecision {
+    artifactUid: string;
+    variant: string;
+    region: string;
+    immutableReference: string;
+    /** The artifact's scan summary, as E1-08 decides it; `null` when no decision was made. */
+    policyDecision: Record<string, unknown> | null;
+}
+/** The promotion that last made a version its environment's promoted one (E1-15, D-11). */
+export interface IEnvironmentPromotionRecord {
+    promotedAt: string;
+    /** The uid of who promoted it. */
+    promotedBy: string;
+    /** The version's optional variants with no artifact a sandbox starts from; empty for a ready version. */
+    unavailableVariants: string[];
+    /** What the promotion acknowledged: exactly `unavailableVariants`. */
+    acknowledgedUnavailableVariants: string[];
+    /** Whether any artifact carried a policy decision; false until E1-08 makes them. */
+    policyDecisionMade: boolean;
+    policyDecisions: IEnvironmentPromotionPolicyDecision[];
+}
+/** A runtime still running one of an environment's artifacts, as a refused deletion names it (E1-15). */
+export interface IEnvironmentLiveRuntime {
+    runtimeUid: string;
+    versionUid: string;
+    /** The digest of the artifact it runs. */
+    digest: string;
+}
+/**
+ * The `detail` of a refused deletion, 409 `DL_ENV_CONFLICT`: what still refers
+ * to the environment, checked in this order.
+ */
+export interface IEnvironmentDeletionConflict {
+    /** A version is promoted: promote none first. */
+    promotedVersionUid?: string;
+    /** How many of its artifacts are referenced. */
+    referencedArtifacts?: number;
+    /** The runtimes still running one of its artifacts, whoever launched them. */
+    runtimes?: IEnvironmentLiveRuntime[];
+}
+/** The `detail` of a refused promotion, 409 `DL_ENV_CONFLICT`. */
+export interface IEnvironmentPromotionConflict {
+    status: EnvironmentVersionStatus;
+    /** A partially ready version's: what the acknowledgement must name, exactly. */
+    unavailableVariants?: string[];
+    /** What the refused acknowledgement named. */
+    acknowledgedUnavailableVariants?: string[];
+}
+/** The artifact a runtime was started from, as its answer names it (section 7.6, E1-11). */
+export interface ILaunchedEnvironmentArtifact {
+    uid: string;
+    variant: string;
+    region: string;
+    /** What the sandbox started from: an OCI reference pinned by its digest. */
+    immutable_reference: string;
+    digest: string;
+    contract_version: string;
+    size_class: string;
+}
+/**
+ * A runtime's user environment, as its answer names it (E1-11): beside the
+ * name and title every runtime's environment carries, the version launched and
+ * its artifact. Snake_case, as the rest of the runtime.
+ */
+export interface ILaunchedEnvironment extends IRuntimeEnvironment {
+    uid: string;
+    version_uid: string;
+    version: number;
+    contract_version: string;
+    artifact: ILaunchedEnvironmentArtifact;
+}
+/**
+ * What trying a version answers (E1-14): `POST /runtimes`' answer, its
+ * runtime's environment naming the version tried and the artifact it started
+ * from. `success` is false, and the runtime carries a `reason`, when the
+ * Operator started none.
+ */
+export interface IEnvironmentTrial extends CreateRuntimeResponse {
+    runtime: CreateRuntimeResponse['runtime'] & {
+        environment: ILaunchedEnvironment;
+    };
+}
+/** One build of one version, on one variant and region. */
+/** One conformance check of a build's smoke test, redacted for the record (E1-29). */
+export interface IEnvironmentConformanceCheck {
+    /** `conformance:<n>`, or the doctor's own id. */
+    id: string;
+    name: string;
+    passed: boolean;
+    /** Whether its failure blocks the version; the extended tier records without gating. */
+    gating: boolean;
+    /** The one-line reason a check gives, above all for a failure; `null` when it passed silently. */
+    detail: string | null;
+}
+/**
+ * The smoke test's per-check report, as the build records it (E1-29): the
+ * gating tier's checks with their pass/fail and reason, without each check's
+ * raw probe output, which the build log keeps and the record does not.
+ */
+export interface IEnvironmentConformanceReport {
+    contractVersion: string;
+    passed: boolean;
+    checks: IEnvironmentConformanceCheck[];
+}
+export interface IEnvironmentBuildRecord {
+    uid: string;
+    environmentUid: string;
+    versionUid: string;
+    ownerUid: string;
+    variant: string;
+    region: string;
+    /** Counted from 1; a retry is the next attempt. */
+    attempt: number;
+    /** The request's key, suffixed with the variant and region. */
+    idempotencyKey: string;
+    /** `queued` when created; see `TERMINAL_ENVIRONMENT_BUILD_STATUSES`. */
+    status: string;
+    errorCode: string;
+    errorDetail: string;
+    /**
+     * The smoke test's per-check conformance report (PLAN_ENV E1-29). Absent
+     * from a Runtimes before E1-29 and `{}` until the build's smoke test ran; a
+     * report with `passed: false` names the checks that failed and why.
+     */
+    conformanceReport?: IEnvironmentConformanceReport | Record<string, never>;
+    cacheHit: boolean;
+    correlationId: string;
+    requestedBy: string;
+    cancelledBy: string;
+    createdAt: string;
+    startedAt: string | null;
+    finishedAt: string | null;
+    updatedAt: string;
+    /** What a conditional write names in `If-Match`. */
+    etag: string;
+}
+/** The artifact of one version, on one variant and region. */
+export interface IEnvironmentArtifactRecord {
+    uid: string;
+    environmentUid: string;
+    versionUid: string;
+    ownerUid: string;
+    variant: string;
+    region: string;
+    specDigest: string;
+    lockDigest: string;
+    baseDigest: string;
+    providerAccount: string;
+    providerNamespace: string;
+    providerArtifactId: string;
+    /** What a launch uses: an OCI digest, a template build, a snapshot id, an image id. */
+    immutableReference: string;
+    /** For operators; never launched. */
+    mutableAlias: string;
+    status: string;
+    architecture: string;
+    contractVersion: string;
+    runtimeMetadata: Record<string, unknown>;
+    sizeBytes: number;
+    sbomRef: string;
+    scanSummary: Record<string, unknown>;
+    provenanceRef: string;
+    signatureRef: string;
+    referenceCount: number;
+    lastUsedAt: string | null;
+    retentionState: string;
+    providerVerifiedAt: string | null;
+    buildStartedAt: string | null;
+    buildFinishedAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+    /** What a conditional write names in `If-Match`. */
+    etag: string;
+}
+/** How one variant of a published version is launched, and its provenance (E2-15). */
+export interface IEnvironmentPublicationVariant {
+    immutableReference: string;
+    region: string;
+    sbomRef: string;
+    signatureRef: string;
+}
+/** The lock a published version resolved to, as its immutable snapshot carries it. */
+export interface IEnvironmentPublicationLock {
+    digest: string;
+    format: string;
+    content: string;
+    packageCount?: number;
+}
+/**
+ * The immutable snapshot a publication freezes (D-12, E2-15): everything a
+ * public page shows, taken once from a version that is itself immutable, and
+ * never re-read — the spec, the lock, the SBOM and scan summary, the licenses
+ * the SBOM names, the size class, the variants with their artifact references,
+ * and the README.
+ */
+export interface IEnvironmentPublicationSnapshot {
+    environmentUid: string;
+    environmentName: string;
+    title: string;
+    ownerUid: string;
+    versionUid: string;
+    versionNumber: number | null;
+    spec: EnvironmentDocument | Record<string, unknown>;
+    lock: IEnvironmentPublicationLock;
+    sbomRef: string;
+    scanSummary: Record<string, unknown>;
+    licenses: string[];
+    sizeClass: string;
+    variants: Record<string, IEnvironmentPublicationVariant>;
+    readme: string;
+}
+/**
+ * A version's publication in the public Library (D-12, E2-15): its terms and
+ * its immutable `snapshot`. A withdrawn version keeps its snapshot — `status`
+ * is `unpublished` rather than the record being gone — and the world-visible
+ * `GET /environment-versions/{uid}/publication` answers only a `published`
+ * one.
+ */
+export interface IEnvironmentPublicationRecord {
+    versionUid: string;
+    environmentUid: string;
+    ownerUid: string;
+    status: 'published' | 'unpublished';
+    publishedBy: string;
+    publishedAt: string;
+    updatedAt: string;
+    snapshot: IEnvironmentPublicationSnapshot;
+    /** What a conditional write names in `If-Match`. */
+    etag: string;
+}
+/**
+ * What forking a published version answers (D-12, E2-15): the caller's own
+ * private environment the fork made, its version, and the Datalayer artifacts
+ * reused — the same immutable references, built once — so a fork of an
+ * unchanged public environment launches without a rebuild.
+ */
+export interface IEnvironmentFork {
+    environment: IEnvironmentRecord;
+    version: IEnvironmentVersionRecord;
+    reusedArtifacts: IEnvironmentArtifactRecord[];
+}
+/** `POST /environment-versions/{uid}/fork`. */
+export interface IForkEnvironmentVersionRequest {
+    /**
+     * A name for the fork; the source environment's name by default. A fork
+     * under a new name re-specialises the spec and builds fresh, rather than
+     * reusing the published artifact.
+     */
+    name?: string;
+}
+/** One chunk of a build's log, redacted before it was written (D-15). */
+export interface IEnvironmentBuildLogChunk {
+    /** Dense from 0. */
+    sequence: number;
+    text: string;
+    /** In bytes. */
+    size: number;
+    createdAt: string;
+}
+/** One problem a variant has with a specification. */
+export interface IEnvironmentCapabilityFinding {
+    code: string;
+    message: string;
+    field?: string;
+}
+/** Whether one variant can build a specification, and why not. */
+export interface IEnvironmentCapabilityReport {
+    variant: string;
+    supported: boolean;
+    findings: IEnvironmentCapabilityFinding[];
+}
+/** What validating a version answers: a capability report per variant. */
+export interface IEnvironmentValidationReport {
+    versionUid: string;
+    specDigest: string;
+    supported: boolean;
+    reports: IEnvironmentCapabilityReport[];
+}
+/** The filters and cursor of `GET /environments`. */
+export interface IListEnvironmentsQuery {
+    /** Only one owner's: an account uid, or a platform entry's owner such as `datalayer`. */
+    owner?: string;
+    /** Only the platform's, or only user environments. */
+    origin?: EnvironmentOrigin;
+    /** Only the environments offered on this variant. */
+    variant?: string;
+    /** Only the environments whose name or title holds this. */
+    q?: string;
+    /** The previous page's `nextCursor`. */
+    cursor?: string;
+    /** How many user environments a page holds, 1 to 200. */
+    limit?: number;
+}
+/** The cursor and size of a page of a registry listing. */
+export interface IEnvironmentsPageQuery {
+    /** The previous page's `nextCursor`. */
+    cursor?: string;
+    /** How many items a page holds, 1 to 200. */
+    limit?: number;
+}
+/** `POST /environments`. */
+export interface ICreateEnvironmentRequest {
+    name: string;
+    title?: string;
+    description?: string;
+    visibility?: EnvironmentVisibility;
+    /** `user` by default. */
+    ownerType?: EnvironmentOwnerType;
+    /** The caller's own uid by default; an organization's uid for its environment. */
+    ownerUid?: string;
+}
+/** `PATCH /environments/{uid}`. */
+export interface IUpdateEnvironmentRequest {
+    title?: string;
+    description?: string;
+    visibility?: EnvironmentVisibility;
+}
+/** `PUT /environments/{uid}/promoted-version`. */
+export interface IPromoteEnvironmentVersionRequest {
+    /** The version to promote, or `null` to promote none. */
+    versionUid: string | null;
+    /** The unavailable variants of a partially ready version. */
+    acknowledgeUnavailableVariants?: string[];
+}
+/** `POST /environment-versions/{uid}/trial`. */
+export interface ITrialEnvironmentVersionRequest {
+    /**
+     * The most credits the trial spends. The service keeps a lower limit, and
+     * lowers a higher one to its cap, `DATALAYER_RUNTIMES_TRIAL_CREDITS_LIMIT`
+     * (5 by default), which is also the limit when none is given.
+     */
+    creditsLimit?: number;
+}
+/** `POST /environments/{uid}/versions`. */
+export interface ICreateEnvironmentVersionRequest {
+    spec: EnvironmentDocument;
+    label?: string;
+}
+/** `PATCH /environment-versions/{uid}`. */
+export interface IUpdateEnvironmentVersionRequest {
+    spec?: EnvironmentDocument;
+    label?: string;
+}
+/** `POST /environment-versions/{uid}/validate`. */
+export interface IValidateEnvironmentVersionRequest {
+    /** The version's own variants when absent. */
+    variants?: string[];
+}
+/** `POST /environment-versions/{uid}/builds`. */
+export interface ICreateEnvironmentBuildsRequest {
+    /** The version's own variants when absent. */
+    variants?: string[];
+    /** A subset of `variants`. */
+    requiredVariants?: string[];
+    /** The spec's regions when absent, else `r1`. */
+    regions?: string[];
+    force?: boolean;
+}
+/** A page of an environment's versions. */
+export interface IEnvironmentVersionsPage {
+    versions: IEnvironmentVersionRecord[];
+    nextCursor: string | null;
+}
+/** The builds one request queued. */
+export interface IEnvironmentBuildsCreated {
+    builds: IEnvironmentBuildRecord[];
+}
+/** A page of a version's builds. */
+export interface IEnvironmentBuildsPage {
+    builds: IEnvironmentBuildRecord[];
+    nextCursor: string | null;
+}
+/** A page of a version's artifacts. */
+export interface IEnvironmentArtifactsPage {
+    artifacts: IEnvironmentArtifactRecord[];
+    nextCursor: string | null;
+}
+/** A build's log chunks after a cursor. */
+export interface IEnvironmentBuildLogPage {
+    chunks: IEnvironmentBuildLogChunk[];
+    /** The sequence of the last chunk read, or the cursor given when nothing new was written. */
+    nextCursor: string | null;
+    /** The build has ended and every chunk has been read. */
+    complete: boolean;
 }
 export default IEnvironment;

package/lib/models/Environment.js

@@ -2,4 +2,15 @@
  * Copyright (c) 2025-2026 Datalayer, Inc.
  * Distributed under the terms of the Modified BSD License.
  */
-export {};
+/**
+ * The Environment specification, `environments.datalayer.io/v1alpha1`,
+ * generated from the JSON Schema `code-sandboxes` exports from its pydantic
+ * models (PLAN_ENV.md, D-14). Regenerated by `npm run generate:environments`.
+ */
+export * as EnvironmentSchema from './environments.generated';
+/** The build statuses nothing more happens to. Any other status is still to run or running. */
+export const TERMINAL_ENVIRONMENT_BUILD_STATUSES = [
+    'succeeded',
+    'failed',
+    'cancelled',
+];

package/lib/models/EnvironmentDTO.d.ts

@@ -13,8 +13,11 @@ export interface EnvironmentData {
     title: string;
     /** Detailed description of the environment */
     description: string;
-    /** Docker image used for this environment */
-    dockerImage: string;
+    /**
+     * Docker image used for this environment. A platform entry names one; a user
+     * environment runs an artifact the platform resolves at launch (E1-11).
+     */
+    dockerImage?: string;
     /** Example usage or description */
     example?: string;
     /** Code snippets for this environment */
@@ -30,8 +33,14 @@ export interface EnvironmentData {
     language: string;
     /** Resource ranges configuration */
     resourcesRanges?: any;
-    /** Credits consumed per hour when running */
-    burning_rate: number;
+    /**
+     * Credits consumed per second when running. A user environment's is the rate
+     * of the size class its promoted version names (D-4); absent means unknown,
+     * not free (E1-19).
+     */
+    burning_rate?: number;
+    /** The size class that prices a user environment (D-4). */
+    sizeClass?: string;
     /** Simple resource specification */
     resources?: any;
     /** Name identifier for the environment */
@@ -55,7 +64,7 @@ export interface EnvironmentJSON {
     title: string;
     /** Unique name identifier for the environment */
     name: string;
-    /** Credits consumed per hour for this environment */
+    /** Credits consumed per second for this environment */
     burningRate: number;
     /** Description of the environment (contains HTML markup) */
     description: string;
@@ -99,8 +108,17 @@ export declare class EnvironmentDTO {
     get title(): string;
     /** Unique name identifier for the environment (e.g., 'ai-env', 'ai-agents-env'). */
     get name(): string;
-    /** Credits consumed per hour for this environment. */
+    /**
+     * Credits consumed per second for this environment.
+     *
+     * Zero when the listing carries no rate, which for a user environment means
+     * its size class is unpriced rather than that it is free: `sizeClass` beside
+     * this tells the two apart, and the callers that reserve credits refuse the
+     * launch rather than reserving nothing (E1-19).
+     */
     get burningRate(): number;
+    /** The size class that prices a user environment (D-4); absent on a platform entry. */
+    get sizeClass(): string | undefined;
     /** Rich description of the environment (contains HTML markup). */
     get richDescription(): string;
     /** Clean description without HTML tags. */

package/lib/models/EnvironmentDTO.js

@@ -38,9 +38,20 @@ export class EnvironmentDTO {
     get name() {
         return this._data.name;
     }
-    /** Credits consumed per hour for this environment. */
+    /**
+     * Credits consumed per second for this environment.
+     *
+     * Zero when the listing carries no rate, which for a user environment means
+     * its size class is unpriced rather than that it is free: `sizeClass` beside
+     * this tells the two apart, and the callers that reserve credits refuse the
+     * launch rather than reserving nothing (E1-19).
+     */
     get burningRate() {
-        return this._data.burning_rate;
+        return this._data.burning_rate ?? 0;
+    }
+    /** The size class that prices a user environment (D-4); absent on a platform entry. */
+    get sizeClass() {
+        return this._data.sizeClass || undefined;
     }
     /** Rich description of the environment (contains HTML markup). */
     get richDescription() {