@fnndsc/stratus 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 FNNDSC / BCH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,34 @@
-# Temporary Holding Version
+# @fnndsc/stratus
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A mise session over the cloud substrate a Trusted Domain runs on. One backend, clouds as drivers; Oracle Cloud Infrastructure is the first driver. The design is [`docs/stratus.adoc`](../../docs/stratus.adoc).
+
+A stratus session is outside any ChRIS. It mounts a cloud tenancy under `/net/<cloud>/<tenancy>/` and lets the mise shell walk it: compartments nest as the cloud nests them, `regions/<region>/` holds each region's zones, limits, shapes and prices as folders of field files, and `domains/` is where Trusted Domains are built. Every row is a folder or a file to the shell; `ls -l` draws a compartment as a compartment and colours it by state.
+
+## Running
+
+The `stratus` command hosts the session as a calypso daemon on the bastion, the host that holds the cloud credential:
+
+```
+stratus                          # the DEFAULT profile of ~/.oci/config, its home region
+stratus --profile BCH --region us-phoenix-1
+stratus --fake                   # a session over the fake cloud, for tests
+```
+
+Attach with `chell --remote`, or open the ARGUS address the daemon prints. A credential that does not work still starts the daemon, disconnected, with `/net/oci` empty.
+
+## Shape
+
+- `src/cloud/driver.ts` is the `CloudDriver` interface: identity, containers, regions, zones, limits, shapes, prices, each answered for the region given.
+- `src/cloud/oci/` is the OCI driver over Oracle's TypeScript SDK (`api.ts` wraps the few calls made, `prices.ts` reads Oracle's public price list). Only this folder may import an `oci-*` package: `npm run lint:stratus-deps` at the repository root keeps it so.
+- `src/cloud/fake/` is an in-memory cloud. It runs the same driver contract (`tests/support/driverContract.ts`) the OCI driver runs over recorded answers, and it is what the boot proof hosts.
+- `src/vfs/tenancy.ts` is the tree, a fond provider over the driver; `src/vfs/look.ts` is how its rows show.
+- `src/session.ts` is who the session is (`user@tenancy`), where it starts (`domains/`) and where it left off; `src/backend.ts` is the descriptor `engine_create` takes.
+
+## Proving it
+
+```
+npm test                         # the unit suites
+npm run test:boot                # boots over the fake cloud with no ChRIS package loaded
+```
+
+The boot proof walks the tree through the engine (`ls`, `cd`, `cat`, a pipe) and fails if cumin, salsa or chili is ever asked for.

package/dist/args.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @file The `stratus` command line: what it takes, and the refusal of
+ * anything else by name.
+ *
+ * @module
+ */
+/** What the command line asked for. */
+export interface StratusArgs {
+    readonly profile?: string;
+    readonly configFile?: string;
+    readonly region?: string;
+    readonly fake: boolean;
+    readonly help: boolean;
+}
+/**
+ * Parses the command line; unknown words are refused by name, as the house
+ * rule says.
+ *
+ * @param argv - The arguments after the command.
+ * @returns The arguments, or the refusal.
+ */
+export declare function stratusArgs_parse(argv: ReadonlyArray<string>): {
+    args: StratusArgs;
+} | {
+    error: string;
+};

package/dist/args.js

@@ -0,0 +1,43 @@
+/**
+ * @file The `stratus` command line: what it takes, and the refusal of
+ * anything else by name.
+ *
+ * @module
+ */
+/** The value after a `--flag VALUE` or `--flag=VALUE`, or undefined. */
+function flagValue_get(argv, flag) {
+    const at = argv.indexOf(flag);
+    if (at !== -1)
+        return argv[at + 1];
+    const joined = argv.find((arg) => arg.startsWith(`${flag}=`));
+    return joined?.slice(flag.length + 1);
+}
+/**
+ * Parses the command line; unknown words are refused by name, as the house
+ * rule says.
+ *
+ * @param argv - The arguments after the command.
+ * @returns The arguments, or the refusal.
+ */
+export function stratusArgs_parse(argv) {
+    const known = ['--profile', '--config', '--region', '--fake', '--help', '-h', '--host-control', '--expose-host-control'];
+    const valued = ['--profile', '--config', '--region', '--host-control'];
+    for (let i = 0; i < argv.length; i++) {
+        const word = argv[i];
+        const name = word.includes('=') ? word.slice(0, word.indexOf('=')) : word;
+        if (!known.includes(name))
+            return { error: `unknown option '${word}' (stratus --help)` };
+        if (valued.includes(name) && !word.includes('=') && name !== '--host-control')
+            i++;
+    }
+    return {
+        args: {
+            profile: flagValue_get(argv, '--profile'),
+            configFile: flagValue_get(argv, '--config'),
+            region: flagValue_get(argv, '--region'),
+            fake: argv.includes('--fake'),
+            help: argv.includes('--help') || argv.includes('-h'),
+        },
+    };
+}
+//# sourceMappingURL=args.js.map

package/dist/args.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"args.js","sourceRoot":"","sources":["../src/args.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAWH,wEAAwE;AACxE,SAAS,aAAa,CAAC,IAA2B,EAAE,IAAY;IAC9D,MAAM,EAAE,GAAW,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,IAAI,EAAE,KAAK,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;IACnC,MAAM,MAAM,GAAuB,IAAI,CAAC,IAAI,CAAC,CAAC,GAAW,EAAW,EAAE,CAAC,GAAG,CAAC,UAAU,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC;IACnG,OAAO,MAAM,EAAE,KAAK,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AACxC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAA2B;IAC3D,MAAM,KAAK,GAA0B,CAAC,WAAW,EAAE,UAAU,EAAE,UAAU,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,gBAAgB,EAAE,uBAAuB,CAAC,CAAC;IAChJ,MAAM,MAAM,GAA0B,CAAC,WAAW,EAAE,UAAU,EAAE,UAAU,EAAE,gBAAgB,CAAC,CAAC;IAC9F,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,MAAM,IAAI,GAAW,IAAI,CAAC,CAAC,CAAC,CAAC;QAC7B,MAAM,IAAI,GAAW,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QAClF,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC;YAAE,OAAO,EAAE,KAAK,EAAE,mBAAmB,IAAI,oBAAoB,EAAE,CAAC;QACzF,IAAI,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,IAAI,KAAK,gBAAgB;YAAE,CAAC,EAAE,CAAC;IACrF,CAAC;IACD,OAAO;QACL,IAAI,EAAE;YACJ,OAAO,EAAE,aAAa,CAAC,IAAI,EAAE,WAAW,CAAC;YACzC,UAAU,EAAE,aAAa,CAAC,IAAI,EAAE,UAAU,CAAC;YAC3C,MAAM,EAAE,aAAa,CAAC,IAAI,EAAE,UAAU,CAAC;YACvC,IAAI,EAAE,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC;YAC7B,IAAI,EAAE,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;SACrD;KACF,CAAC;AACJ,CAAC"}

package/dist/backend.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @file The stratus backend: the descriptor a session over a cloud runs with.
+ *
+ * One backend for every cloud (docs/stratus.adoc, D1): its id is `stratus`,
+ * its filesystem is the tenancy tree over whichever driver it was given, its
+ * identity the cloud user at the tenancy. It registers no commands yet and
+ * no answer kinds (every row is a folder or a file, D5); the prompt is the
+ * wire's ChRIS-shaped context filled with what a substrate session has,
+ * until the segments of D9 land.
+ *
+ * @module
+ */
+import type { Backend } from '@fnndsc/brasa/core';
+import type { CloudDriver } from './cloud/driver.js';
+import { StratusSession } from './session.js';
+import { TenancyProvider } from './vfs/tenancy.js';
+/** How the backend is made. */
+export interface StratusBackendOptions {
+    /** The cloud. */
+    readonly driver: CloudDriver;
+    /** The region the session works in; the credential's home region when absent. */
+    readonly region?: string;
+    /** Where the working directory is kept. */
+    readonly configDir?: string;
+    /** How long the tree keeps a cloud answer, in milliseconds. */
+    readonly cacheLifeMs?: number;
+}
+/** The backend and the pieces a host may reach into. */
+export interface StratusBackend {
+    readonly backend: Backend;
+    readonly session: StratusSession;
+    readonly tenancy: TenancyProvider;
+}
+/**
+ * Makes the stratus backend over a driver.
+ *
+ * @param options - The driver and the session's settings.
+ * @returns The backend, ready for `engine_create`, with its session and tree.
+ */
+export declare function stratusBackend_make(options: StratusBackendOptions): StratusBackend;

package/dist/backend.js

@@ -0,0 +1,38 @@
+import { VFSDispatcher } from '@fnndsc/fond';
+import { AnswerCache } from './cache.js';
+import { StratusSession } from './session.js';
+import { TenancyProvider } from './vfs/tenancy.js';
+import { stratusListingLook } from './vfs/look.js';
+/**
+ * Makes the stratus backend over a driver.
+ *
+ * @param options - The driver and the session's settings.
+ * @returns The backend, ready for `engine_create`, with its session and tree.
+ */
+export function stratusBackend_make(options) {
+    const session = new StratusSession({ driver: options.driver, region: options.region, configDir: options.configDir });
+    const tenancy = new TenancyProvider({ driver: options.driver, cache: new AnswerCache(options.cacheLifeMs) });
+    const dispatcher = new VFSDispatcher();
+    dispatcher.provider_register(tenancy);
+    const backend = {
+        id: 'stratus',
+        session,
+        vfs: {
+            dispatcher,
+            structural: ['/', '/net', session.mount],
+        },
+        completion: { rootWords: ['net'] },
+        listingLook: stratusListingLook,
+        prompt: async (last) => ({
+            user: (await session.user_get()) ?? 'disconnected',
+            uri: session.identity?.tenancy ?? '',
+            cwd: session.cwd_get() ?? (await session.home_get()),
+            pacsserver: null,
+            physicalMode: false,
+            lastExitCode: last?.lastExitCode ?? 0,
+            lastCommandDurationMs: last?.lastCommandDurationMs ?? 0,
+        }),
+    };
+    return { backend, session, tenancy };
+}
+//# sourceMappingURL=backend.js.map

package/dist/backend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend.js","sourceRoot":"","sources":["../src/backend.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAG7C,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAqBnD;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,OAA8B;IAChE,MAAM,OAAO,GAAmB,IAAI,cAAc,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC;IACrI,MAAM,OAAO,GAAoB,IAAI,eAAe,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,KAAK,EAAE,IAAI,WAAW,CAAC,OAAO,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC;IAC9H,MAAM,UAAU,GAAkB,IAAI,aAAa,EAAE,CAAC;IACtD,UAAU,CAAC,iBAAiB,CAAC,OAAO,CAAC,CAAC;IACtC,MAAM,OAAO,GAAY;QACvB,EAAE,EAAE,SAAS;QACb,OAAO;QACP,GAAG,EAAE;YACH,UAAU;YACV,UAAU,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,KAAK,CAAC;SACzC;QACD,UAAU,EAAE,EAAE,SAAS,EAAE,CAAC,KAAK,CAAC,EAAE;QAClC,WAAW,EAAE,kBAAkB;QAC/B,MAAM,EAAE,KAAK,EAAE,IAAwB,EAA0B,EAAE,CAAC,CAAC;YACnE,IAAI,EAAE,CAAC,MAAM,OAAO,CAAC,QAAQ,EAAE,CAAC,IAAI,cAAc;YAClD,GAAG,EAAE,OAAO,CAAC,QAAQ,EAAE,OAAO,IAAI,EAAE;YACpC,GAAG,EAAE,OAAO,CAAC,OAAO,EAAE,IAAI,CAAC,MAAM,OAAO,CAAC,QAAQ,EAAE,CAAC;YACpD,UAAU,EAAE,IAAI;YAChB,YAAY,EAAE,KAAK;YACnB,YAAY,EAAE,IAAI,EAAE,YAAY,IAAI,CAAC;YACrC,qBAAqB,EAAE,IAAI,EAAE,qBAAqB,IAAI,CAAC;SACxD,CAAC;KACH,CAAC;IACF,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;AACvC,CAAC"}

package/dist/cache.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @file A short-lived cache of what the cloud answered.
+ *
+ * Resource Search and the Limits API throttle, and a listing a second ago is
+ * a listing now; the tree keeps each answer for a short life and asks again
+ * when it has aged out (docs/stratus.adoc, D4). The clock is injected so a
+ * test can age an entry without waiting.
+ *
+ * @module
+ */
+/** Answers kept by key, each for a fixed life. */
+export declare class AnswerCache {
+    private readonly kept;
+    private readonly lifeMs;
+    private readonly now;
+    /**
+     * @param lifeMs - How long an answer stays current.
+     * @param now - The clock, in milliseconds.
+     */
+    constructor(lifeMs?: number, now?: () => number);
+    /**
+     * The kept answer for a key, or the one `ask` gives, kept from now.
+     *
+     * @param key - What the answer is of.
+     * @param ask - How to get it when nothing current is kept.
+     * @returns The answer.
+     */
+    answer_get<T>(key: string, ask: () => Promise<T>): Promise<T>;
+    /** Forgets one answer, or every answer under a key prefix. */
+    forget(prefix: string): void;
+    /** Forgets everything. */
+    clear(): void;
+}

package/dist/cache.js

@@ -0,0 +1,50 @@
+/**
+ * @file A short-lived cache of what the cloud answered.
+ *
+ * Resource Search and the Limits API throttle, and a listing a second ago is
+ * a listing now; the tree keeps each answer for a short life and asks again
+ * when it has aged out (docs/stratus.adoc, D4). The clock is injected so a
+ * test can age an entry without waiting.
+ *
+ * @module
+ */
+/** Answers kept by key, each for a fixed life. */
+export class AnswerCache {
+    kept = new Map();
+    lifeMs;
+    now;
+    /**
+     * @param lifeMs - How long an answer stays current.
+     * @param now - The clock, in milliseconds.
+     */
+    constructor(lifeMs = 60_000, now = () => Date.now()) {
+        this.lifeMs = lifeMs;
+        this.now = now;
+    }
+    /**
+     * The kept answer for a key, or the one `ask` gives, kept from now.
+     *
+     * @param key - What the answer is of.
+     * @param ask - How to get it when nothing current is kept.
+     * @returns The answer.
+     */
+    async answer_get(key, ask) {
+        const found = this.kept.get(key);
+        if (found !== undefined && this.now() - found.at < this.lifeMs)
+            return found.value;
+        const value = await ask();
+        this.kept.set(key, { value, at: this.now() });
+        return value;
+    }
+    /** Forgets one answer, or every answer under a key prefix. */
+    forget(prefix) {
+        for (const key of [...this.kept.keys()])
+            if (key === prefix || key.startsWith(`${prefix}/`))
+                this.kept.delete(key);
+    }
+    /** Forgets everything. */
+    clear() {
+        this.kept.clear();
+    }
+}
+//# sourceMappingURL=cache.js.map

package/dist/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAQH,kDAAkD;AAClD,MAAM,OAAO,WAAW;IACL,IAAI,GAA+B,IAAI,GAAG,EAAE,CAAC;IAC7C,MAAM,CAAS;IACf,GAAG,CAAe;IAEnC;;;OAGG;IACH,YAAY,SAAiB,MAAM,EAAE,MAAoB,GAAW,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE;QAC/E,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;IACjB,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,UAAU,CAAI,GAAW,EAAE,GAAqB;QACpD,MAAM,KAAK,GAA8B,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC5D,IAAI,KAAK,KAAK,SAAS,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,EAAE,GAAG,IAAI,CAAC,MAAM;YAAE,OAAO,KAAK,CAAC,KAAU,CAAC;QACxF,MAAM,KAAK,GAAM,MAAM,GAAG,EAAE,CAAC;QAC7B,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;QAC9C,OAAO,KAAK,CAAC;IACf,CAAC;IAED,8DAA8D;IAC9D,MAAM,CAAC,MAAc;QACnB,KAAK,MAAM,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;YAAE,IAAI,GAAG,KAAK,MAAM,IAAI,GAAG,CAAC,UAAU,CAAC,GAAG,MAAM,GAAG,CAAC;gBAAE,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACrH,CAAC;IAED,0BAA0B;IAC1B,KAAK;QACH,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC;IACpB,CAAC;CACF"}

package/dist/cloud/driver.d.ts

@@ -0,0 +1,140 @@
+/**
+ * @file The cloud driver: what stratus asks of a cloud, and nothing a cloud
+ * asks of stratus.
+ *
+ * One substrate backend, clouds as drivers (docs/stratus.adoc, D1). The tree,
+ * the verbs and the composition are written once against this interface; a
+ * cloud implements it (`oci/`), and the fake implements it for tests and the
+ * boot proof. Every driver passes the same contract suite
+ * (`tests/support/driverContract.ts`).
+ *
+ * Names are the cloud's own words where the cloud has them (a shape, a
+ * limit's service) and neutral where every cloud has the thing (a container,
+ * a zone, a region).
+ *
+ * @module
+ */
+/** Who the session is, as the cloud knows it. */
+export interface CloudIdentity {
+    /** The user's name, as the cloud shows it (an IAM user's name). */
+    readonly user: string;
+    /** The root container's display name: the tenancy, the account, the organization. */
+    readonly tenancy: string;
+    /** The root container's id. */
+    readonly tenancyId: string;
+    /** The region the credential names as home. */
+    readonly homeRegion: string;
+}
+/** A container of resources: a compartment, an account, a project, a resource group. */
+export interface CloudContainer {
+    /** Its display name; the path segment. */
+    readonly name: string;
+    /** Its id (an OCID). */
+    readonly id: string;
+    /** The container holding it, or null for the root. */
+    readonly parentId: string | null;
+    /** Its lifecycle state, lower case (`active`, `deleting`). */
+    readonly state: string;
+    /** When it was made, ISO 8601. */
+    readonly created: string;
+    /** What the cloud says it is for. */
+    readonly description: string;
+    /** Its tags, flattened: freeform as `key`, defined as `namespace.key`. */
+    readonly tags: Readonly<Record<string, string>>;
+    /** What the cloud calls this kind of container: `compartment`, `project`, `account`. */
+    readonly noun: string;
+    /** The whole record, for `info.json`. */
+    readonly raw: unknown;
+}
+/** A zone inside a region: an availability domain, an availability zone. */
+export interface CloudZone {
+    /** Its name, as the cloud's API wants it back (`Uocm:US-ASHBURN-AD-1`). */
+    readonly name: string;
+}
+/** One service limit, at the scope the cloud keeps it. */
+export interface CloudLimit {
+    /** The service it belongs to (`compute`). */
+    readonly service: string;
+    /** The limit's name (`standard-e5-core-count`). */
+    readonly name: string;
+    /** Where it applies. */
+    readonly scope: 'global' | 'region' | 'zone';
+    /** The zone, when the scope is a zone. */
+    readonly zone?: string;
+    /** The permitted amount. */
+    readonly value: number;
+}
+/** How much of a limit is spent and left. */
+export interface CloudAvailability {
+    readonly used: number;
+    readonly available: number;
+}
+/** A machine shape the region offers. */
+export interface CloudShape {
+    /** The cloud's name for it (`VM.Standard.E5.Flex`). */
+    readonly name: string;
+    /** A neutral family name (`E5`). */
+    readonly family: string;
+    /** Whether cores and memory are chosen per instance. */
+    readonly flexible: boolean;
+    /** vCPU per core unit the cloud bills (OCI: per OCPU). */
+    readonly vcpuPerCore: number;
+    /** Cores a fixed shape has, or the range a flexible one allows. */
+    readonly cores: {
+        readonly min: number;
+        readonly max: number;
+    };
+    /** Memory in GiB a fixed shape has, or the range a flexible one allows. */
+    readonly memoryGib: {
+        readonly min: number;
+        readonly max: number;
+    };
+    /** The processor, in the cloud's words. */
+    readonly processor: string;
+    /** GPUs, when the shape has them. */
+    readonly gpus: number;
+    /** The limit names the shape draws on. */
+    readonly quotaNames: ReadonlyArray<string>;
+    /** The whole record, for `info.json`. */
+    readonly raw: unknown;
+}
+/** What a shape's family costs, per hour, at list price. */
+export interface CloudPrice {
+    /** The shape it prices. */
+    readonly shape: string;
+    /** Per vCPU-hour. */
+    readonly vcpuHour: number;
+    /** Per GiB-hour of memory. */
+    readonly gibHour: number;
+    /** The currency code. */
+    readonly currency: string;
+}
+/**
+ * A cloud, as stratus sees it. Every method answers for the region it is
+ * given: the region is the session's, not the driver's (docs/stratus.adoc,
+ * D4), so a driver holds no current region.
+ */
+export interface CloudDriver {
+    /** The cloud's short name; the mount under `/net` (`oci`). */
+    readonly cloud: string;
+    /** Who the credential is, and its home region. Throws when the credential does not work. */
+    identity_get(): Promise<CloudIdentity>;
+    /** The root container. */
+    root_get(): Promise<CloudContainer>;
+    /** The containers directly inside one. */
+    containers_list(parentId: string): Promise<CloudContainer[]>;
+    /** The regions the tenancy is subscribed to. */
+    regions_list(): Promise<string[]>;
+    /** The zones of a region. */
+    zones_list(region: string): Promise<CloudZone[]>;
+    /** The services that have limits. */
+    limitServices_list(region: string): Promise<string[]>;
+    /** One service's limits in a region, at every scope. */
+    limits_list(region: string, service: string): Promise<CloudLimit[]>;
+    /** How much of one limit is spent and left; null when the cloud does not say. */
+    limitAvailability_get(region: string, service: string, name: string, zone?: string): Promise<CloudAvailability | null>;
+    /** The shapes a region offers. */
+    shapes_list(region: string): Promise<CloudShape[]>;
+    /** List prices for the shapes, per hour. */
+    prices_list(): Promise<CloudPrice[]>;
+}

package/dist/cloud/driver.js

@@ -0,0 +1,18 @@
+/**
+ * @file The cloud driver: what stratus asks of a cloud, and nothing a cloud
+ * asks of stratus.
+ *
+ * One substrate backend, clouds as drivers (docs/stratus.adoc, D1). The tree,
+ * the verbs and the composition are written once against this interface; a
+ * cloud implements it (`oci/`), and the fake implements it for tests and the
+ * boot proof. Every driver passes the same contract suite
+ * (`tests/support/driverContract.ts`).
+ *
+ * Names are the cloud's own words where the cloud has them (a shape, a
+ * limit's service) and neutral where every cloud has the thing (a container,
+ * a zone, a region).
+ *
+ * @module
+ */
+export {};
+//# sourceMappingURL=driver.js.map

package/dist/cloud/driver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"driver.js","sourceRoot":"","sources":["../../src/cloud/driver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG"}

package/dist/cloud/fake/driver.d.ts

@@ -0,0 +1,55 @@
+/**
+ * @file The fake cloud: a driver over a fixture in memory.
+ *
+ * It runs the same contract suite the OCI driver runs, so the driver
+ * interface stays honest with one real cloud (docs/stratus.adoc, D1), and it
+ * is what the boot proof and the unit tests host a session over.
+ *
+ * @module
+ */
+import type { CloudAvailability, CloudContainer, CloudDriver, CloudIdentity, CloudLimit, CloudPrice, CloudShape, CloudZone } from '../driver.js';
+/** What a fake cloud holds. */
+export interface FakeCloud {
+    readonly identity: CloudIdentity;
+    /** Every container, the root among them (its `parentId` null). */
+    readonly containers: ReadonlyArray<CloudContainer>;
+    readonly regions: ReadonlyArray<string>;
+    /** Zones by region. */
+    readonly zones: Readonly<Record<string, ReadonlyArray<CloudZone>>>;
+    /** Limits by region. */
+    readonly limits: Readonly<Record<string, ReadonlyArray<CloudLimit>>>;
+    /** Availability by `region/service/name[/zone]`. */
+    readonly availability: Readonly<Record<string, CloudAvailability>>;
+    /** Shapes by region. */
+    readonly shapes: Readonly<Record<string, ReadonlyArray<CloudShape>>>;
+    readonly prices: ReadonlyArray<CloudPrice>;
+}
+/** The key an availability is kept under. */
+export declare function availabilityKey_make(region: string, service: string, name: string, zone?: string): string;
+/** A driver over a fixture. */
+export declare class FakeDriver implements CloudDriver {
+    readonly cloud: string;
+    private readonly cloudData;
+    /** How often each method was asked; the tests read it to prove caching. */
+    readonly calls: Record<string, number>;
+    constructor(cloudData: FakeCloud, cloud?: string);
+    private call_count;
+    identity_get(): Promise<CloudIdentity>;
+    root_get(): Promise<CloudContainer>;
+    containers_list(parentId: string): Promise<CloudContainer[]>;
+    regions_list(): Promise<string[]>;
+    zones_list(region: string): Promise<CloudZone[]>;
+    limitServices_list(region: string): Promise<string[]>;
+    limits_list(region: string, service: string): Promise<CloudLimit[]>;
+    limitAvailability_get(region: string, service: string, name: string, zone?: string): Promise<CloudAvailability | null>;
+    shapes_list(region: string): Promise<CloudShape[]>;
+    prices_list(): Promise<CloudPrice[]>;
+}
+/**
+ * A small cloud with the shape of the real one: a tenancy, two compartments
+ * (one nested), one region with three zones, a few limits and shapes.
+ *
+ * @param tenancy - The tenancy's name.
+ * @returns The fixture.
+ */
+export declare function fakeCloud_sample(tenancy?: string): FakeCloud;

package/dist/cloud/fake/driver.js

@@ -0,0 +1,115 @@
+/** The key an availability is kept under. */
+export function availabilityKey_make(region, service, name, zone) {
+    return zone === undefined ? `${region}/${service}/${name}` : `${region}/${service}/${name}/${zone}`;
+}
+/** A driver over a fixture. */
+export class FakeDriver {
+    cloud;
+    cloudData;
+    /** How often each method was asked; the tests read it to prove caching. */
+    calls = {};
+    constructor(cloudData, cloud = 'oci') {
+        this.cloudData = cloudData;
+        this.cloud = cloud;
+    }
+    call_count(method) {
+        this.calls[method] = (this.calls[method] ?? 0) + 1;
+    }
+    async identity_get() {
+        this.call_count('identity_get');
+        return this.cloudData.identity;
+    }
+    async root_get() {
+        this.call_count('root_get');
+        const root = this.cloudData.containers.find((container) => container.parentId === null);
+        if (root === undefined)
+            throw new Error('fake cloud: no root container');
+        return root;
+    }
+    async containers_list(parentId) {
+        this.call_count('containers_list');
+        return this.cloudData.containers
+            .filter((container) => container.parentId === parentId)
+            .sort((a, b) => a.name.localeCompare(b.name));
+    }
+    async regions_list() {
+        this.call_count('regions_list');
+        return [...this.cloudData.regions];
+    }
+    async zones_list(region) {
+        this.call_count('zones_list');
+        return [...(this.cloudData.zones[region] ?? [])];
+    }
+    async limitServices_list(region) {
+        this.call_count('limitServices_list');
+        const services = new Set((this.cloudData.limits[region] ?? []).map((limit) => limit.service));
+        return [...services].sort();
+    }
+    async limits_list(region, service) {
+        this.call_count('limits_list');
+        return (this.cloudData.limits[region] ?? []).filter((limit) => limit.service === service);
+    }
+    async limitAvailability_get(region, service, name, zone) {
+        this.call_count('limitAvailability_get');
+        return this.cloudData.availability[availabilityKey_make(region, service, name, zone)] ?? null;
+    }
+    async shapes_list(region) {
+        this.call_count('shapes_list');
+        return [...(this.cloudData.shapes[region] ?? [])].sort((a, b) => a.name.localeCompare(b.name));
+    }
+    async prices_list() {
+        this.call_count('prices_list');
+        return [...this.cloudData.prices];
+    }
+}
+/**
+ * A small cloud with the shape of the real one: a tenancy, two compartments
+ * (one nested), one region with three zones, a few limits and shapes.
+ *
+ * @param tenancy - The tenancy's name.
+ * @returns The fixture.
+ */
+export function fakeCloud_sample(tenancy = 'fnndsc') {
+    const region = 'us-ashburn-1';
+    const zones = [1, 2, 3].map((n) => ({ name: `Uocm:US-ASHBURN-AD-${n}` }));
+    const container = (name, id, parentId, description, tags = {}) => ({
+        name, id, parentId, state: 'active', created: '2026-08-27T12:00:00.000Z', description, tags, noun: 'compartment',
+        raw: { id, name, description, compartmentId: parentId, lifecycleState: 'ACTIVE', timeCreated: '2026-08-27T12:00:00.000Z' },
+    });
+    const limit = (service, name, value, zone) => zone === undefined ? { service, name, scope: 'region', value } : { service, name, scope: 'zone', zone, value };
+    const shape = (name, family, processor) => ({
+        name, family, flexible: true, vcpuPerCore: 2, cores: { min: 1, max: 94 }, memoryGib: { min: 1, max: 1049 }, processor, gpus: 0,
+        quotaNames: [`standard-${family.toLowerCase()}-core-count`, `standard-${family.toLowerCase()}-memory-count`],
+        raw: { shape: name, processorDescription: processor, isFlexible: true },
+    });
+    return {
+        identity: { user: 'rudolph', tenancy, tenancyId: 'ocid1.tenancy.oc1..root', homeRegion: region },
+        containers: [
+            container(tenancy, 'ocid1.tenancy.oc1..root', null, 'the root compartment'),
+            container('harbor-oci', 'ocid1.compartment.oc1..harbor', 'ocid1.tenancy.oc1..root', 'Trusted Domain builds', { 'openshift-tags.openshift-resource': 'harbor' }),
+            container('sandbox', 'ocid1.compartment.oc1..sandbox', 'ocid1.tenancy.oc1..root', 'scratch'),
+            container('scratch-a', 'ocid1.compartment.oc1..scratcha', 'ocid1.compartment.oc1..sandbox', 'a nested scratch compartment'),
+        ],
+        regions: [region],
+        zones: { [region]: zones },
+        limits: {
+            [region]: [
+                ...zones.map((zone) => limit('compute', 'standard-e5-core-count', 9250, zone.name)),
+                ...zones.map((zone) => limit('compute', 'standard-e5-memory-count', 9250 * 8, zone.name)),
+                limit('load-balancer', 'lb-flexible-count', 50),
+                { service: 'vcn', name: 'vcn-count', scope: 'global', value: 50 },
+            ],
+        },
+        availability: {
+            [availabilityKey_make(region, 'compute', 'standard-e5-core-count', zones[0].name)]: { used: 12, available: 9238 },
+            [availabilityKey_make(region, 'load-balancer', 'lb-flexible-count')]: { used: 3, available: 47 },
+            [availabilityKey_make(region, 'vcn', 'vcn-count')]: { used: 1, available: 49 },
+        },
+        shapes: { [region]: [shape('VM.Standard.E5.Flex', 'E5', 'AMD EPYC 9J14'), shape('VM.Standard.A2.Flex', 'A2', 'Ampere AmpereOne')] },
+        prices: [
+            { shape: 'VM.Standard.E5.Flex', vcpuHour: 0.015, gibHour: 0.002, currency: 'USD' },
+            { shape: 'VM.Standard.A2.Flex', vcpuHour: 0.007, gibHour: 0.002, currency: 'USD' },
+        ],
+    };
+}
+//# sourceMappingURL=driver.js.map