@zocomputer/system-api 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,52 @@
-# Temporary Holding Version
+# Zo System API SDK
 
-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.
+The TypeScript SDK provides typed System API calls, exact JSON invocation,
+catalog parsing and schema validation. Node and browser clients share the same
+HTTP transport.
+
+## Install
+
+Version 0.1.0 is a release candidate. After publication:
+
+```sh
+npm install @zocomputer/system-api@0.1.0
+```
+
+For an unpublished release archive:
+
+```sh
+npm install ./zocomputer-system-api-0.1.0.tgz
+```
+
+The package exports compiled JavaScript and declarations. Import the client
+from `@zocomputer/system-api` or `@zocomputer/system-api/core`; use `@zocomputer/system-api/builtin` for
+the built-in action catalog. Catalog parsing, exact JSON, schema validation
+and code generation have separate `/catalog`, `/json`, `/validation` and
+`/generate` entry points.
+
+## Develop locally
+
+From the repository root:
+
+```sh
+cd clients
+nvm use
+npm ci
+npm run build --workspace=@zocomputer/system-api
+npm run typecheck --workspace=@zocomputer/system-api
+```
+
+Build before running a consumer. npm links the SDK and CLI inside their own
+workspace, so rebuilt exports are immediately available. Source tests resolve the
+package's own imports to source through its TypeScript configuration; packed
+consumers resolve only compiled files.
+
+The public CLI package checks both release artifacts together:
+
+```sh
+npm --prefix clients run test:packed
+npm --prefix clients run pack:release -- --out /tmp/zo-cli-release
+```
+
+Neither command publishes a package. The SDK must be published before the CLI,
+whose release pins its tested SDK version.

package/dist/catalog/index.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Parse the normalized System API catalog export into the internal model the
+ * generator and runtime consumers use.
+ *
+ * The same shape is emitted by `dev_etc/tools/system_api_codegen.py`
+ * (`export_builtin_catalog`: `format_version`/`actions`/`resource_types`/
+ * `default_versions`) and by an authorized principal-scoped `CatalogBundle`
+ * export (which adds `protocol_version`, `view_revision`, `selection`,
+ * `availability`, `catalog_digest`, …). Only the fields the generator needs are
+ * read; every other top-level or per-action field is ignored and never treated
+ * as type input, so authorization metadata cannot influence generated types. A
+ * missing or malformed required field fails loudly with {@link CatalogFormatError}
+ * — the generator never guesses a default or a schema.
+ *
+ * Schemas are carried as the lossless {@link JsonValue} tree, not `JSON.parse`
+ * output: supported schema numbers are exact decimals up to 100 digits, and
+ * `JSON.parse` would silently round a bound/default/enum/const, changing the
+ * contract on offline regeneration. The exact bytes drive `schema.json` and
+ * digest identity; a lossy plain projection ({@link toPlainJson}) feeds the
+ * TypeScript renderer only after admission and is never persisted.
+ */
+import { type JsonValue } from "../json/index.ts";
+/** The only normalized-export format this generator supports (codegen emits `1`). */
+export declare const SUPPORTED_FORMAT_VERSION = 1;
+/** Thrown when the catalog export handed to the generator is malformed. */
+export declare class CatalogFormatError extends Error {
+    constructor(message: string);
+}
+/** A single published version of one action: its digest and I/O schemas. */
+export interface OperationVersion {
+    readonly version: number;
+    readonly digest: string;
+    /** Lossless schema tree — exact decimals preserved for the contract/digest. */
+    readonly input: JsonValue;
+    readonly output: JsonValue;
+    /**
+     * The version's list query schema (`options.query`), when it declares query
+     * options. Outside the contract and its digest.
+     */
+    readonly query?: JsonValue;
+    readonly description?: string;
+    readonly availability?: "eligible" | "conditional" | "definition";
+}
+/**
+ * One action with its declared versions (ascending) and, when the export pins an
+ * eligible one, its default-version. `defaultVersion` is optional: the service
+ * can expose a visible action with no eligible default, in which case a typed
+ * call must pass an explicit version (the generator emits no pin for it).
+ */
+export interface OperationEntry {
+    readonly action: string;
+    readonly defaultVersion?: number;
+    readonly versions: readonly OperationVersion[];
+}
+/** One published resource type with its public properties schema. */
+export interface ResourceTypeEntry {
+    readonly type: string;
+    readonly version: number;
+    readonly propertiesSchema: JsonValue;
+    readonly description?: string;
+}
+/**
+ * The selection a live `CatalogBundle` was computed for, echoed by the service.
+ * Absent for the builtin export, which is intentionally not workspace-scoped.
+ */
+export interface CatalogSelectionEcho {
+    readonly workspace: string;
+    readonly catalog: string;
+}
+/** The normalized view of a catalog: sorted operations and resource types. */
+export interface NormalizedCatalog {
+    readonly operations: readonly OperationEntry[];
+    readonly resourceTypes: readonly ResourceTypeEntry[];
+    /**
+     * The service's own selection echo, when the export carried one (live scoped/
+     * all bundles). This is the authoritative provenance — it is never synthesized
+     * from CLI flags. Absent for the builtin export.
+     */
+    readonly selection?: CatalogSelectionEcho;
+    /** The service's canonical content digest (`catalog_digest`), when present. */
+    readonly catalogDigest?: string;
+}
+/** Parse and validate a normalized catalog export from a lossless JSON tree. */
+export declare function parseNormalizedCatalog(source: JsonValue): NormalizedCatalog;
+/**
+ * Load a normalized catalog export from raw bytes, losslessly. Returns both the
+ * parsed model and the exact original bytes: `schema.json` and the bundle digest
+ * are written from these bytes so offline regeneration reproduces the identical
+ * contract, byte for byte.
+ */
+export declare function loadNormalizedCatalog(bytes: Uint8Array | string): {
+    catalog: NormalizedCatalog;
+    bytes: Uint8Array;
+};
+/**
+ * Project a lossless {@link JsonValue} schema tree to a plain JSON value for the
+ * TypeScript renderer. `JsonNumber` collapses to a JS `number` (lossy for huge
+ * decimals) — acceptable because TypeScript describes only structural shape, and
+ * this projection is never persisted as the contract.
+ *
+ * Objects are materialized with a null prototype so a schema property or `$defs`
+ * key literally named `__proto__` is preserved as an own key instead of hitting
+ * the inherited setter (which would drop it and poison the projection's
+ * prototype) — the same trap the validator's schema normalization avoids.
+ */
+export declare function toPlainJson(value: JsonValue): unknown;

package/dist/catalog/index.js

@@ -0,0 +1,237 @@
+/**
+ * Parse the normalized System API catalog export into the internal model the
+ * generator and runtime consumers use.
+ *
+ * The same shape is emitted by `dev_etc/tools/system_api_codegen.py`
+ * (`export_builtin_catalog`: `format_version`/`actions`/`resource_types`/
+ * `default_versions`) and by an authorized principal-scoped `CatalogBundle`
+ * export (which adds `protocol_version`, `view_revision`, `selection`,
+ * `availability`, `catalog_digest`, …). Only the fields the generator needs are
+ * read; every other top-level or per-action field is ignored and never treated
+ * as type input, so authorization metadata cannot influence generated types. A
+ * missing or malformed required field fails loudly with {@link CatalogFormatError}
+ * — the generator never guesses a default or a schema.
+ *
+ * Schemas are carried as the lossless {@link JsonValue} tree, not `JSON.parse`
+ * output: supported schema numbers are exact decimals up to 100 digits, and
+ * `JSON.parse` would silently round a bound/default/enum/const, changing the
+ * contract on offline regeneration. The exact bytes drive `schema.json` and
+ * digest identity; a lossy plain projection ({@link toPlainJson}) feeds the
+ * TypeScript renderer only after admission and is never persisted.
+ */
+import { JsonNumber, MAX_JSON_DEPTH, loadsJson, } from "../json/index.js";
+/** The only normalized-export format this generator supports (codegen emits `1`). */
+export const SUPPORTED_FORMAT_VERSION = 1;
+/** Action/contract versions are positive 32-bit integers, matching the contract. */
+const MAX_CONTRACT_VERSION = 2_147_483_647;
+/** The export wraps each bounded schema, so it nests a few levels below a schema. */
+const MAX_EXPORT_DEPTH = MAX_JSON_DEPTH + 8;
+/** Thrown when the catalog export handed to the generator is malformed. */
+export class CatalogFormatError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "CatalogFormatError";
+    }
+}
+function isObject(value) {
+    return (value !== null &&
+        typeof value === "object" &&
+        !Array.isArray(value) &&
+        !(value instanceof JsonNumber));
+}
+function requireString(value, what) {
+    if (typeof value !== "string" || value.length === 0)
+        throw new CatalogFormatError(`${what} must be a non-empty string`);
+    return value;
+}
+function requireVersion(value, what) {
+    if (!(value instanceof JsonNumber) || !value.isInteger)
+        throw new CatalogFormatError(`${what} must be an integer`);
+    const n = Number(value.text);
+    if (n < 1 || n > MAX_CONTRACT_VERSION)
+        throw new CatalogFormatError(`${what} must be in [1, ${MAX_CONTRACT_VERSION}]`);
+    return n;
+}
+function requireSchema(value, what) {
+    if (!isObject(value))
+        throw new CatalogFormatError(`${what} must be a JSON object`);
+    return value;
+}
+function optionalDescription(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+/** Parse and validate a normalized catalog export from a lossless JSON tree. */
+export function parseNormalizedCatalog(source) {
+    if (!isObject(source))
+        throw new CatalogFormatError("catalog export must be a JSON object");
+    const formatVersion = source["format_version"];
+    if (!(formatVersion instanceof JsonNumber) ||
+        !formatVersion.isInteger ||
+        Number(formatVersion.text) !== SUPPORTED_FORMAT_VERSION)
+        throw new CatalogFormatError(`unsupported catalog format (expected format_version ${SUPPORTED_FORMAT_VERSION})`);
+    const rawActions = source["actions"];
+    if (!Array.isArray(rawActions))
+        throw new CatalogFormatError("catalog export is missing an 'actions' array");
+    const rawDefaults = source["default_versions"];
+    if (!isObject(rawDefaults))
+        throw new CatalogFormatError("catalog export is missing a 'default_versions' object");
+    // `queries` is additive: an export without it declares no query options.
+    const rawQueries = source["queries"] ?? {};
+    if (!isObject(rawQueries))
+        throw new CatalogFormatError("'queries' must be a JSON object");
+    const rawAvailability = source["availability"] ?? {};
+    if (!isObject(rawAvailability))
+        throw new CatalogFormatError("'availability' must be a JSON object");
+    // Callable actions are selected by the service and builtin release exporter.
+    // Group their versions without maintaining a second list of policy actions.
+    const byAction = new Map();
+    for (const raw of rawActions) {
+        if (!isObject(raw))
+            throw new CatalogFormatError("each catalog action must be a JSON object");
+        const name = requireString(raw["name"], "an action's 'name'");
+        const version = requireVersion(raw["version"], `action '${name}' version`);
+        const rawQuery = rawQueries[`${name}@${version}`];
+        const availability = rawAvailability[`${name}@${version}`];
+        if (availability !== undefined &&
+            availability !== "eligible" &&
+            availability !== "conditional" &&
+            availability !== "definition")
+            throw new CatalogFormatError(`action '${name}' has invalid availability`);
+        const entry = {
+            version,
+            digest: requireString(raw["digest"], `action '${name}' digest`),
+            input: requireSchema(raw["input_schema"], `action '${name}' input_schema`),
+            output: requireSchema(raw["output_schema"], `action '${name}' output_schema`),
+            ...(rawQuery !== undefined
+                ? {
+                    query: requireSchema(rawQuery, `queries['${name}@${version}']`),
+                }
+                : {}),
+            description: optionalDescription(raw["description"]),
+            ...(availability !== undefined ? { availability } : {}),
+        };
+        const versions = byAction.get(name);
+        if (versions === undefined) {
+            byAction.set(name, [entry]);
+        }
+        else {
+            if (versions.some((v) => v.version === version))
+                throw new CatalogFormatError(`catalog has a duplicate entry for action '${name}' version ${version}`);
+            versions.push(entry);
+        }
+    }
+    // A default pin is OPTIONAL: the service can expose a visible action with no
+    // eligible default (it filters an ineligible pin out of `default_versions`),
+    // and a present pin must be one of the action's declared versions. An unpinned
+    // action yields `defaultVersion: undefined` — a typed call against it requires
+    // an explicit version. Extra `default_versions` entries for actions not in
+    // this view are ignored, so an over-broad defaults map is tolerated.
+    const operations = [...byAction.entries()]
+        .map(([action, versions]) => {
+        const declared = versions.map((v) => v.version);
+        const rawDefault = rawDefaults[action];
+        let defaultVersion;
+        if (rawDefault !== undefined) {
+            defaultVersion = requireVersion(rawDefault, `default_versions['${action}']`);
+            if (!declared.includes(defaultVersion))
+                throw new CatalogFormatError(`default_versions['${action}'] pins version ${defaultVersion}, which is not a declared version`);
+        }
+        versions.sort((a, b) => a.version - b.version);
+        return { action, defaultVersion, versions };
+    })
+        .sort((a, b) => (a.action < b.action ? -1 : a.action > b.action ? 1 : 0));
+    const resourceTypes = parseResourceTypes(source["resource_types"]);
+    const selection = parseOptionalSelection(source["selection"]);
+    const rawDigest = source["catalog_digest"];
+    const catalogDigest = typeof rawDigest === "string" && rawDigest.length > 0
+        ? rawDigest
+        : undefined;
+    return {
+        operations,
+        resourceTypes,
+        ...(selection !== undefined ? { selection } : {}),
+        ...(catalogDigest !== undefined ? { catalogDigest } : {}),
+    };
+}
+/**
+ * Parse the export's `selection` echo when present. A malformed echo fails
+ * loudly rather than being silently dropped — a live bundle that claims a
+ * selection must name a workspace and catalog. Absent entirely (builtin export)
+ * is fine and yields `undefined`.
+ */
+function parseOptionalSelection(raw) {
+    if (raw === undefined)
+        return undefined;
+    if (!isObject(raw))
+        throw new CatalogFormatError("'selection' must be a JSON object");
+    return {
+        workspace: requireString(raw["workspace_id"], "selection.workspace_id"),
+        catalog: requireString(raw["catalog"], "selection.catalog"),
+    };
+}
+function parseResourceTypes(raw) {
+    if (raw === undefined)
+        return [];
+    if (!Array.isArray(raw))
+        throw new CatalogFormatError("'resource_types' must be an array");
+    const seen = new Set();
+    const entries = raw.map((item) => {
+        if (!isObject(item))
+            throw new CatalogFormatError("each resource type must be a JSON object");
+        const type = requireString(item["type"], "a resource type's 'type'");
+        const version = requireVersion(item["version"], `resource type '${type}' version`);
+        const key = `${type}\u0000${version}`;
+        if (seen.has(key))
+            throw new CatalogFormatError(`catalog has a duplicate resource type '${type}' version ${version}`);
+        seen.add(key);
+        return {
+            type,
+            version,
+            propertiesSchema: requireSchema(item["properties_schema"], `resource type '${type}' properties_schema`),
+            description: optionalDescription(item["description"]),
+        };
+    });
+    entries.sort((a, b) => a.type < b.type ? -1 : a.type > b.type ? 1 : a.version - b.version);
+    return entries;
+}
+/**
+ * Load a normalized catalog export from raw bytes, losslessly. Returns both the
+ * parsed model and the exact original bytes: `schema.json` and the bundle digest
+ * are written from these bytes so offline regeneration reproduces the identical
+ * contract, byte for byte.
+ */
+export function loadNormalizedCatalog(bytes) {
+    const raw = typeof bytes === "string" ? new TextEncoder().encode(bytes) : bytes;
+    let tree;
+    try {
+        tree = loadsJson(raw, { maxNodes: null, maxDepth: MAX_EXPORT_DEPTH });
+    }
+    catch (error) {
+        throw new CatalogFormatError(`catalog export is not valid JSON: ${error.message}`);
+    }
+    return { catalog: parseNormalizedCatalog(tree), bytes: raw };
+}
+/**
+ * Project a lossless {@link JsonValue} schema tree to a plain JSON value for the
+ * TypeScript renderer. `JsonNumber` collapses to a JS `number` (lossy for huge
+ * decimals) — acceptable because TypeScript describes only structural shape, and
+ * this projection is never persisted as the contract.
+ *
+ * Objects are materialized with a null prototype so a schema property or `$defs`
+ * key literally named `__proto__` is preserved as an own key instead of hitting
+ * the inherited setter (which would drop it and poison the projection's
+ * prototype) — the same trap the validator's schema normalization avoids.
+ */
+export function toPlainJson(value) {
+    if (value instanceof JsonNumber)
+        return Number(value.text);
+    if (Array.isArray(value))
+        return value.map(toPlainJson);
+    if (value !== null && typeof value === "object") {
+        const out = Object.create(null);
+        for (const [key, item] of Object.entries(value))
+            out[key] = toPlainJson(item);
+        return out;
+    }
+    return value;
+}

package/dist/core/catalog.d.ts

@@ -0,0 +1,155 @@
+/**
+ * The runtime catalog ABI: the one type + value shape the generator emits and
+ * this runtime consumes. The typed catalog carries default-version pins and
+ * per-version contract digests only — no per-action JSON schemas — so a typed
+ * consumer never pulls in a validator. Digests are identity metadata, not
+ * payload authentication.
+ */
+/**
+ * Shape every generated `Operations` map satisfies: action → version → I/O,
+ * and the list query (`options.query`) for a version that declares one.
+ */
+export type OperationsShape = {
+    readonly [action: string]: {
+        readonly [version: number]: {
+            readonly input: unknown;
+            readonly output: unknown;
+            readonly query?: unknown;
+        };
+    };
+};
+/**
+ * Shape of the default-version pins. Each action *may* map to one of its
+ * versions: a visible action can be exported without an eligible default (the
+ * service drops an ineligible pin), so the map is partial. An unpinned action
+ * carries no default and requires an explicit `version` at the call site.
+ */
+export type DefaultVersionsShape<Ops extends OperationsShape> = {
+    readonly [A in keyof Ops]?: keyof Ops[A] & number;
+};
+/**
+ * The keys of `Defaults` that carry a *guaranteed* pin: present as a required
+ * property whose value type excludes `undefined`. A widened/optional
+ * `DefaultVersionsShape` (every key optional) reduces to `never`, so it can
+ * never expose an unsafe options-omitted call — only a concrete required pin
+ * does. Not part of the public surface (`core/index.ts` does not re-export it).
+ */
+export type GuaranteedPinKeys<Defaults> = {
+    [K in keyof Defaults]-?: Pick<Defaults, K> extends Required<Pick<Defaults, K>> ? undefined extends Defaults[K] ? never : K : never;
+}[keyof Defaults];
+/**
+ * The concrete default version of a pinned action, narrowed with `Extract` to a
+ * version actually declared for `Ops[A]`. `never` when the action is unpinned or
+ * its pin is not a declared version (a defensive guard; the generator emits only
+ * declared pins). Not part of the public surface.
+ */
+export type PinnedVersion<Ops extends OperationsShape, A extends keyof Ops, Defaults extends DefaultVersionsShape<Ops>> = A extends keyof Defaults ? Extract<Defaults[A], keyof Ops[A] & number> : never;
+/** Per-version runtime metadata carried in the typed catalog. */
+export interface VersionEntry {
+    /** Immutable contract digest (`sha256:...`) — identity, not integrity proof. */
+    readonly digest: string;
+}
+/**
+ * The typed per-action entries, tied to `Operations`/`DefaultVersions` at the
+ * type level: each declared action is present, `versions` has an entry for
+ * exactly its declared versions, and a *pinned* action's `defaultVersion` is
+ * exactly its pin. An *unpinned* action (absent from `Defaults`) carries no
+ * `defaultVersion` — the field is forbidden as a number (`?: never`) so a value
+ * cannot invent a default the service did not declare — while a value may still
+ * omit it. So a catalog value can neither disagree with, nor over-claim, the
+ * pins it advertises.
+ */
+export type TypedActions<Ops extends OperationsShape, Defaults extends DefaultVersionsShape<Ops>> = {
+    readonly [A in keyof Ops]: {
+        readonly versions: {
+            readonly [V in keyof Ops[A] & number]: VersionEntry;
+        };
+    } & (A extends GuaranteedPinKeys<Defaults> ? {
+        readonly defaultVersion: PinnedVersion<Ops, A, Defaults>;
+    } : {
+        readonly defaultVersion?: PinnedVersion<Ops, A, Defaults>;
+    });
+};
+/**
+ * Runtime-facing action entry, used for the client's untyped catalog lookup.
+ * `defaultVersion` is optional: an unpinned action carries no default, and an
+ * options-omitted call against it is rejected at runtime (`version_required`).
+ */
+export interface ActionEntry {
+    readonly defaultVersion?: number;
+    readonly versions: {
+        readonly [version: number]: VersionEntry;
+    };
+}
+declare const OPS: unique symbol;
+declare const DEFAULTS: unique symbol;
+declare const CATALOG_KIND: unique symbol;
+/**
+ * The generated runtime catalog. `Ops`/`Defaults` are phantom type parameters
+ * (carried by the branded symbols); `actions`/`generatorVersion` are the value.
+ */
+export interface TypedCatalog<Ops extends OperationsShape, Defaults extends DefaultVersionsShape<Ops>> {
+    /** Generator version that emitted this catalog, for reproducibility. */
+    readonly generatorVersion: string;
+    readonly actions: TypedActions<Ops, Defaults>;
+    readonly [OPS]?: Ops;
+    readonly [DEFAULTS]?: Defaults;
+    readonly [CATALOG_KIND]?: "typed";
+}
+/**
+ * The structural base every {@link TypedCatalog} satisfies regardless of its pin
+ * map's shape: the generator version, a string-indexed actions map, and the
+ * typed brand. Used only as `createClient`'s accept-constraint so both pinned
+ * and unpinned concrete typed catalogs are assignable to it — the pin-aware
+ * {@link TypedActions} of a concrete `TypedCatalog` is not a subtype of the same
+ * type computed over the widened `DefaultVersionsShape`, so a deep base would
+ * reject unpinned values. Inference still reads `Ops`/`Defaults` off the
+ * concrete value via the branded phantoms. Not publicly re-exported.
+ */
+export interface TypedCatalogBase {
+    readonly generatorVersion: string;
+    readonly actions: {
+        readonly [action: string]: ActionEntry;
+    };
+    readonly [CATALOG_KIND]?: "typed";
+}
+/**
+ * A catalog loaded from the server at runtime: it supplies default-version pins
+ * and per-version digests without inventing compile-time types. A client built
+ * from one returns `unknown` (never `any`). The `"runtime"` brand keeps it
+ * distinct from `TypedCatalog` so the untyped call surface is reachable only
+ * through this catalog, never as a catch-all on a typed client.
+ */
+export interface RuntimeCatalog {
+    readonly generatorVersion: string;
+    readonly actions: {
+        readonly [action: string]: ActionEntry;
+    };
+    readonly [CATALOG_KIND]?: "runtime";
+}
+/** Extract the `Operations` map a typed catalog is associated with. */
+export type OperationsOf<C> = C extends TypedCatalog<infer Ops, infer _Defaults> ? Ops : never;
+/** Extract the `DefaultVersions` pins a typed catalog is associated with. */
+export type DefaultsOf<C> = C extends TypedCatalog<infer _Ops, infer Defaults> ? Defaults : never;
+/**
+ * Build a typed catalog value with its `Operations`/`DefaultVersions`
+ * association. The `Ops`/`Defaults` arguments are type-only, so this is a thin,
+ * dependency-free constructor; `TypedActions` enforces value/type agreement.
+ */
+export declare function defineCatalog<Ops extends OperationsShape, Defaults extends DefaultVersionsShape<Ops>>(catalog: {
+    generatorVersion: string;
+    actions: TypedActions<Ops, Defaults>;
+}): TypedCatalog<Ops, Defaults>;
+/**
+ * Build a runtime (untyped) catalog value from a server-loaded shape. Stamping
+ * the `RuntimeCatalog` return type is what routes it to `createClient`'s untyped
+ * overload — a bare object literal would satisfy `TypedCatalog` too and resolve
+ * to the typed client. Dependency-free; the value is returned unchanged.
+ */
+export declare function defineRuntimeCatalog(catalog: {
+    generatorVersion: string;
+    actions: {
+        readonly [action: string]: ActionEntry;
+    };
+}): RuntimeCatalog;
+export {};

package/dist/core/catalog.js

@@ -0,0 +1,24 @@
+/**
+ * The runtime catalog ABI: the one type + value shape the generator emits and
+ * this runtime consumes. The typed catalog carries default-version pins and
+ * per-version contract digests only — no per-action JSON schemas — so a typed
+ * consumer never pulls in a validator. Digests are identity metadata, not
+ * payload authentication.
+ */
+/**
+ * Build a typed catalog value with its `Operations`/`DefaultVersions`
+ * association. The `Ops`/`Defaults` arguments are type-only, so this is a thin,
+ * dependency-free constructor; `TypedActions` enforces value/type agreement.
+ */
+export function defineCatalog(catalog) {
+    return catalog;
+}
+/**
+ * Build a runtime (untyped) catalog value from a server-loaded shape. Stamping
+ * the `RuntimeCatalog` return type is what routes it to `createClient`'s untyped
+ * overload — a bare object literal would satisfy `TypedCatalog` too and resolve
+ * to the typed client. Dependency-free; the value is returned unchanged.
+ */
+export function defineRuntimeCatalog(catalog) {
+    return catalog;
+}