@onesi/genesis 0.0.1-stage → 0.1.13

package/dist/henry.d.ts

@@ -0,0 +1,168 @@
+import type { GenesisClient } from './client.js';
+import type { OperationInput } from './types.js';
+/** Henry always derives its organization from the gateway's verified caller. */
+export declare function henryModule(client: GenesisClient): {
+    config: () => Promise<{
+        credential_configured: boolean;
+        models: {
+            id: string;
+        }[];
+    }>;
+    credential: (api_key: string) => Promise<{
+        credential_configured: boolean;
+        models: {
+            id: string;
+        }[];
+    }>;
+    /** Foundry models the stored organization key can run; 409 when no key is stored. */
+    models: () => Promise<{
+        models: {
+            id: string;
+        }[];
+    }>;
+    receipts: {
+        /** Current standalone Henry public signer. Pin through trusted deployment custody before verifying a receipt. */
+        verificationKey: () => Promise<{
+            keyId: string;
+            publicKeyBase64: string;
+        }>;
+    };
+    runs: {
+        list: (page_token?: string) => Promise<{
+            runs: import("./index.js").components["schemas"]["Henry.Run"][];
+            next_page_token?: string | null;
+        }>;
+        create: (body: NonNullable<OperationInput<"henry_createRun">["body"]>) => Promise<{
+            id: string;
+            task: string;
+            model: string;
+            status: "ready" | "running" | "acting" | "paused" | "awaiting_approval" | "completed" | "cancelled" | "failed" | "waiting_input";
+            created_at: string;
+            updated_at: string;
+            activity: {
+                id: string;
+                at: string;
+                type: string;
+                detail: string;
+            }[];
+            approvals: {
+                id: string;
+                action: string;
+                url: string;
+                status: string;
+                requested_at: string;
+            }[];
+            phases: {
+                id?: string;
+                code?: number;
+                receipt?: Record<string, never>;
+                usage?: Record<string, never> | null;
+            }[];
+            messages: ({
+                role: string;
+                content?: string | null;
+            } & {
+                [key: string]: unknown;
+            })[];
+        }>;
+        get: (run_id: string) => Promise<{
+            id: string;
+            task: string;
+            model: string;
+            status: "ready" | "running" | "acting" | "paused" | "awaiting_approval" | "completed" | "cancelled" | "failed" | "waiting_input";
+            created_at: string;
+            updated_at: string;
+            activity: {
+                id: string;
+                at: string;
+                type: string;
+                detail: string;
+            }[];
+            approvals: {
+                id: string;
+                action: string;
+                url: string;
+                status: string;
+                requested_at: string;
+            }[];
+            phases: {
+                id?: string;
+                code?: number;
+                receipt?: Record<string, never>;
+                usage?: Record<string, never> | null;
+            }[];
+            messages: ({
+                role: string;
+                content?: string | null;
+            } & {
+                [key: string]: unknown;
+            })[];
+        }>;
+        command: (run_id: string, action: "pause" | "resume" | "cancel" | "input", text?: string) => Promise<{
+            id: string;
+            task: string;
+            model: string;
+            status: "ready" | "running" | "acting" | "paused" | "awaiting_approval" | "completed" | "cancelled" | "failed" | "waiting_input";
+            created_at: string;
+            updated_at: string;
+            activity: {
+                id: string;
+                at: string;
+                type: string;
+                detail: string;
+            }[];
+            approvals: {
+                id: string;
+                action: string;
+                url: string;
+                status: string;
+                requested_at: string;
+            }[];
+            phases: {
+                id?: string;
+                code?: number;
+                receipt?: Record<string, never>;
+                usage?: Record<string, never> | null;
+            }[];
+            messages: ({
+                role: string;
+                content?: string | null;
+            } & {
+                [key: string]: unknown;
+            })[];
+        }>;
+        approval: (run_id: string, approval_id: string, decision: "approve" | "reject") => Promise<{
+            id: string;
+            task: string;
+            model: string;
+            status: "ready" | "running" | "acting" | "paused" | "awaiting_approval" | "completed" | "cancelled" | "failed" | "waiting_input";
+            created_at: string;
+            updated_at: string;
+            activity: {
+                id: string;
+                at: string;
+                type: string;
+                detail: string;
+            }[];
+            approvals: {
+                id: string;
+                action: string;
+                url: string;
+                status: string;
+                requested_at: string;
+            }[];
+            phases: {
+                id?: string;
+                code?: number;
+                receipt?: Record<string, never>;
+                usage?: Record<string, never> | null;
+            }[];
+            messages: ({
+                role: string;
+                content?: string | null;
+            } & {
+                [key: string]: unknown;
+            })[];
+        }>;
+    };
+};

package/dist/henry.js

@@ -0,0 +1,45 @@
+import { GenesisError } from './errors.js';
+function receiptVerificationKey(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('Henry returned an invalid receipt verification key.');
+    const key = value;
+    if (Object.keys(key).length !== 2 || !Object.hasOwn(key, 'keyId') || !Object.hasOwn(key, 'publicKeyBase64')
+        || typeof key.keyId !== 'string' || !key.keyId.trim() || key.keyId.length > 256 || /[\x00-\x1f\x7f]/.test(key.keyId)
+        || typeof key.publicKeyBase64 !== 'string' || key.publicKeyBase64.length !== 44
+        || !/^[A-Za-z0-9+/]{42}[AEIMQUYcgkosw048]=$/.test(key.publicKeyBase64)) {
+        throw new Error('Henry returned an invalid receipt verification key.');
+    }
+    return { keyId: key.keyId, publicKeyBase64: key.publicKeyBase64 };
+}
+/** Henry always derives its organization from the gateway's verified caller. */
+export function henryModule(client) {
+    return {
+        config: () => client.request('henry_getConfig'),
+        credential: async (api_key) => {
+            if (typeof api_key !== 'string' || !api_key || new TextEncoder().encode(api_key).byteLength > 4096 || /[\r\n\0]/.test(api_key)) {
+                throw new GenesisError({ status: 0, type: 'invalid_request', operationId: 'henry_putCredential', message: 'Foundry key must contain 1–4096 UTF-8 bytes without CR, LF or NUL.' });
+            }
+            return client.request('henry_putCredential', { body: { api_key } });
+        },
+        /** Foundry models the stored organization key can run; 409 when no key is stored. */
+        models: () => client.request('henry_listFoundryModels'),
+        receipts: {
+            /** Current standalone Henry public signer. Pin through trusted deployment custody before verifying a receipt. */
+            verificationKey: async () => {
+                try {
+                    return receiptVerificationKey(await client.request('henry_getReceiptVerificationKey'));
+                }
+                catch {
+                    throw new Error('Henry returned an invalid receipt verification key.');
+                }
+            },
+        },
+        runs: {
+            list: (page_token) => client.request('henry_listRuns', page_token ? { page_token } : {}),
+            create: (body) => client.request('henry_createRun', { body: { ...body, run_id: body.run_id ?? globalThis.crypto.randomUUID() } }),
+            get: (run_id) => client.request('henry_getRun', { run_id }),
+            command: (run_id, action, text) => client.request('henry_commandRun', { run_id, body: { action, ...(text === undefined ? {} : { text }) } }),
+            approval: (run_id, approval_id, decision) => client.request('henry_decideApproval', { run_id, approval_id, body: { decision } }),
+        },
+    };
+}

package/dist/hives-cells.d.ts

@@ -0,0 +1,127 @@
+import type { GenesisClient } from './client.js';
+import { type HivesResourceOptions } from './hives-resources-transport.js';
+export interface HivesCorsRule {
+    allowed_origins: string[];
+    allowed_methods: string[];
+    allowed_headers: string[];
+    exposed_headers: string[];
+    max_age_secs: number;
+}
+export interface HivesBucket {
+    id: string;
+    tenant_id: string;
+    project_id: string;
+    name: string;
+    region: string;
+    visibility: string;
+    status: string;
+    object_count: number | null;
+    size_bytes: number | null;
+    statistics_scope: 'unmeasured_provider_inventory' | 'retained_legacy_metadata';
+    created_at: string;
+    provider_binding: {
+        provider: 'gcs';
+        region: string;
+        state: string;
+        requires_reconciliation: boolean;
+    } | null;
+    operation_state: string | null;
+}
+export interface HivesObject {
+    key: string;
+    bucket_id: string;
+    size_bytes: number;
+    etag: string;
+    last_modified: string;
+    generation: string;
+    content_type: string | null;
+    metadata: Record<string, string> | null;
+    metadata_scope: string;
+}
+export interface HivesObjectAcknowledgement {
+    bucket_id: string;
+    key: string;
+    size_bytes: number;
+    etag: string;
+    generation: string;
+    content_type: string | null;
+}
+export interface HivesObjectList {
+    objects: HivesObject[];
+    common_prefixes: string[];
+    is_truncated: boolean;
+    next_continuation_token: string | null;
+    total: number | null;
+}
+export interface HivesBucketList {
+    data: HivesBucket[];
+    pagination: {
+        page: number;
+        per_page: number;
+        total: number;
+        total_pages: number;
+        has_next: boolean;
+        has_prev: boolean;
+    };
+}
+export interface HivesCreateBucket {
+    name: string;
+    region?: 'us-central1';
+    visibility?: 'private' | 'publicread';
+    cors_rules?: HivesCorsRule[];
+}
+export interface HivesPresign {
+    key: string;
+    method?: 'GET' | 'PUT';
+    expires_in_secs?: number;
+    content_type?: string;
+    content_length?: number;
+}
+export interface HivesPresignedUrl {
+    url: string;
+    expires_at: string;
+    method: 'GET' | 'PUT';
+    required_headers?: Record<string, string>;
+}
+export declare function hivesObjectKey(key: string): string;
+export declare function hivesCells(client: GenesisClient): {
+    list(project: string, query?: {
+        page?: number;
+        per_page?: number;
+    }, options?: HivesResourceOptions): Promise<HivesBucketList>;
+    get(project: string, id: string, options?: HivesResourceOptions): Promise<HivesBucket>;
+    /** A pending provider_binding is an uncertain outcome, never a completed-create claim. */
+    create(project: string, body: HivesCreateBucket, options?: HivesResourceOptions): Promise<HivesBucket>;
+    remove(project: string, id: string, options?: HivesResourceOptions): Promise<{
+        id: string;
+        success: boolean;
+        message: string;
+    }>;
+    reconcile(project: string, id: string, options?: HivesResourceOptions): Promise<{
+        bucket: HivesBucket;
+        outcome: string;
+    }>;
+    cors: {
+        get: (project: string, id: string, options?: HivesResourceOptions) => Promise<HivesCorsRule[]>;
+        set: (project: string, id: string, rules: HivesCorsRule[], options?: HivesResourceOptions) => Promise<HivesCorsRule[]>;
+    };
+    objects: {
+        list(project: string, id: string, query?: {
+            prefix?: string;
+            delimiter?: string;
+            continuation_token?: string;
+            max_keys?: number;
+        }, options?: HivesResourceOptions): Promise<HivesObjectList>;
+        put(project: string, id: string, key: string, bytes: Blob | ArrayBuffer | ArrayBufferView, options?: HivesResourceOptions & {
+            content_type?: string;
+        }): Promise<HivesObjectAcknowledgement>;
+        remove: (project: string, id: string, key: string, options?: HivesResourceOptions) => Promise<void>;
+        download: (project: string, id: string, key: string, options?: HivesResourceOptions) => Promise<Response>;
+        /** Existing flat-key path compatibility; nested keys use canonical collection methods above. */
+        putFlat(project: string, id: string, key: string, bytes: Blob | ArrayBuffer | ArrayBufferView, options?: HivesResourceOptions & {
+            content_type?: string;
+        }): Promise<HivesObjectAcknowledgement>;
+        removeFlat: (project: string, id: string, key: string, options?: HivesResourceOptions) => Promise<void>;
+    };
+    presign(project: string, id: string, body: HivesPresign, options?: HivesResourceOptions): Promise<HivesPresignedUrl>;
+};

package/dist/hives-cells.js

@@ -0,0 +1,151 @@
+import { HIVES_OBJECT_BYTES, hivesResourceCall, hivesResourceId, hivesObjectBody, hivesContentType, resourceError } from './hives-resources-transport.js';
+export function hivesObjectKey(key) {
+    const bytes = new TextEncoder().encode(key);
+    if (typeof key !== 'string' || !key || bytes.length > 1024 || new TextDecoder('utf-8', { fatal: true }).decode(bytes) !== key
+        || key.startsWith('/') || key.endsWith('/') || /[\u0000-\u001f\u007f-\u009f\\]/.test(key) || key.split('/').some(p => !p || p === '.' || p === '..'))
+        throw resourceError(0);
+    let binary = '';
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+function cors(rules) {
+    if (!Array.isArray(rules) || rules.length > 100)
+        throw resourceError(0);
+    return rules.map(rule => {
+        if (!rule || typeof rule !== 'object' || Object.keys(rule).some(k => !['allowed_origins', 'allowed_methods', 'allowed_headers', 'exposed_headers', 'max_age_secs'].includes(k))
+            || !Array.isArray(rule.allowed_origins) || !rule.allowed_origins.length || rule.allowed_origins.length > 100
+            || !Array.isArray(rule.allowed_methods) || !rule.allowed_methods.length || rule.allowed_methods.length > 6
+            || !Array.isArray(rule.allowed_headers) || rule.allowed_headers.length !== 1 || rule.allowed_headers[0] !== '*'
+            || !Array.isArray(rule.exposed_headers) || rule.exposed_headers.length > 100
+            || !Number.isInteger(rule.max_age_secs) || rule.max_age_secs < 0 || rule.max_age_secs > 86400)
+            throw resourceError(0);
+        for (const origin of rule.allowed_origins) {
+            if (origin === '*')
+                continue;
+            if (typeof origin !== 'string')
+                throw resourceError(0);
+            let url;
+            try {
+                url = new URL(origin);
+            }
+            catch {
+                throw resourceError(0);
+            }
+            if (!['http:', 'https:'].includes(url.protocol) || !url.hostname || url.username || url.password || url.pathname !== '/' || url.search || url.hash)
+                throw resourceError(0);
+        }
+        if (rule.allowed_methods.some(m => !['GET', 'HEAD', 'PUT', 'POST', 'DELETE'].includes(m))
+            || rule.exposed_headers.some(h => typeof h !== 'string' || h.length > 256 || !/^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/.test(h)))
+            throw resourceError(0);
+        return { allowed_origins: [...rule.allowed_origins], allowed_methods: [...rule.allowed_methods], allowed_headers: ['*'], exposed_headers: [...rule.exposed_headers], max_age_secs: rule.max_age_secs };
+    });
+}
+function bucket(value, project, id) {
+    if (!value || typeof value !== 'object' || value.project_id !== project || typeof value.id !== 'string' || id !== undefined && value.id !== id
+        || !['unmeasured_provider_inventory', 'retained_legacy_metadata'].includes(value.statistics_scope)
+        || [value.object_count, value.size_bytes].some(v => v !== null && (!Number.isSafeInteger(v) || v < 0))
+        || (value.statistics_scope === 'unmeasured_provider_inventory' && (value.object_count !== null || value.size_bytes !== null)))
+        throw resourceError(0);
+    if (value.statistics_scope === 'unmeasured_provider_inventory' && !value.provider_binding)
+        throw resourceError(0);
+    if (value.provider_binding !== null && (!value.provider_binding || value.provider_binding.provider !== 'gcs' || typeof value.provider_binding.state !== 'string' || typeof value.provider_binding.requires_reconciliation !== 'boolean'))
+        throw resourceError(0);
+    return Object.fromEntries(['id', 'tenant_id', 'project_id', 'name', 'region', 'visibility', 'status', 'object_count', 'size_bytes', 'statistics_scope', 'created_at', 'provider_binding', 'operation_state'].map(k => [k, value[k]]));
+}
+function object(value, id) {
+    if (!value || value.bucket_id !== id || typeof value.key !== 'string' || !Number.isSafeInteger(value.size_bytes) || value.size_bytes < 0 || typeof value.generation !== 'string')
+        throw resourceError(0);
+    hivesObjectKey(value.key);
+    return Object.fromEntries(['key', 'bucket_id', 'size_bytes', 'etag', 'last_modified', 'generation', 'content_type', 'metadata', 'metadata_scope'].map(k => [k, value[k]]));
+}
+function acknowledgement(value, key, id, size) {
+    if (!value || value.bucket_id !== id || value.key !== key || value.size_bytes !== size || !Number.isSafeInteger(value.size_bytes) || value.size_bytes < 0 || typeof value.etag !== 'string' || typeof value.generation !== 'string' || value.content_type !== null && typeof value.content_type !== 'string')
+        throw resourceError(0);
+    return { key: value.key, bucket_id: value.bucket_id, size_bytes: value.size_bytes, etag: value.etag, generation: value.generation, content_type: value.content_type };
+}
+export function hivesCells(client) {
+    const ids = (project_id, bucket_id) => ({ project_id: hivesResourceId(project_id), ...(bucket_id === undefined ? {} : { bucket_id: hivesResourceId(bucket_id) }) });
+    const call = (id, input, options, mode = 'json', limit = 2 * 1024 * 1024) => hivesResourceCall(client, id, input, options, mode, limit, 100_000);
+    return {
+        async list(project, query = {}, options) {
+            if (Object.keys(query).some(k => !['page', 'per_page'].includes(k)) || query.page !== undefined && (!Number.isInteger(query.page) || query.page < 1 || query.page > 10000) || query.per_page !== undefined && (!Number.isInteger(query.per_page) || query.per_page < 1 || query.per_page > 100))
+                throw resourceError(0);
+            const result = await call('hives_list_buckets', { ...query, ...ids(project) }, options);
+            if (!result || !Array.isArray(result.data) || !result.pagination)
+                throw resourceError(0);
+            return { ...result, data: result.data.map(row => bucket(row, project)) };
+        },
+        async get(project, id, options) { return bucket(await call('hives_get_bucket', ids(project, id), options), project, id); },
+        /** A pending provider_binding is an uncertain outcome, never a completed-create claim. */
+        async create(project, body, options) {
+            if (!body || typeof body.name !== 'string' || !/^[a-z0-9][a-z0-9.-]{1,61}[a-z0-9]$/.test(body.name) || body.region !== undefined && body.region !== 'us-central1'
+                || body.visibility !== undefined && !['private', 'publicread'].includes(body.visibility) || Object.keys(body).some(k => !['name', 'region', 'visibility', 'cors_rules'].includes(k)))
+                throw resourceError(0);
+            const checked = { ...body, ...(body.cors_rules === undefined ? {} : { cors_rules: cors(body.cors_rules) }) };
+            return bucket(await call('hives_create_bucket', { ...ids(project), body: checked }, options), project);
+        },
+        async remove(project, id, options) {
+            const result = await call('hives_delete_bucket', ids(project, id), options);
+            if (!result || result.id !== id || result.success !== true)
+                throw resourceError(0);
+            return result;
+        },
+        async reconcile(project, id, options) {
+            const result = await call('hives_reconcile', ids(project, id), options);
+            if (!result || typeof result.outcome !== 'string' || result.bucket?.id !== id)
+                throw resourceError(0);
+            return { ...result, bucket: bucket(result.bucket, project) };
+        },
+        cors: {
+            get: async (project, id, options) => cors(await call('hives_get_cors_config', ids(project, id), options)),
+            set: async (project, id, rules, options) => cors(await call('hives_set_cors_config', { ...ids(project, id), body: { rules: cors(rules) } }, options)),
+        },
+        objects: {
+            async list(project, id, query = {}, options) {
+                if (query.max_keys !== undefined && (!Number.isInteger(query.max_keys) || query.max_keys < 1 || query.max_keys > 1000))
+                    throw resourceError(0);
+                const result = await call('hives_list_objects', { ...query, ...ids(project, id) }, options);
+                if (!result || !Array.isArray(result.objects) || !Array.isArray(result.common_prefixes) || typeof result.is_truncated !== 'boolean' || result.total !== null)
+                    throw resourceError(0);
+                return { ...result, objects: result.objects.map(row => object(row, id)) };
+            },
+            async put(project, id, key, bytes, options = {}) {
+                const body = await hivesObjectBody(bytes);
+                const content_type = hivesContentType(options.content_type);
+                return acknowledgement(await call('hives_upload_object_by_key', { ...ids(project, id), key_base64url: hivesObjectKey(key), body, content_type }, options), key, id, body.byteLength);
+            },
+            remove: (project, id, key, options) => call('hives_delete_object_by_key', { ...ids(project, id), key_base64url: hivesObjectKey(key) }, options, 'empty'),
+            download: (project, id, key, options) => call('hives_download_object_by_key', { ...ids(project, id), key_base64url: hivesObjectKey(key) }, options, 'binary', HIVES_OBJECT_BYTES),
+            /** Existing flat-key path compatibility; nested keys use canonical collection methods above. */
+            async putFlat(project, id, key, bytes, options = {}) {
+                hivesObjectKey(key);
+                if (!/^[A-Za-z0-9_-]+(?:\.[A-Za-z0-9_-]+)*$/.test(key))
+                    throw resourceError(0);
+                const body = await hivesObjectBody(bytes);
+                return acknowledgement(await call('hives_upload_object', { ...ids(project, id), key, body, content_type: hivesContentType(options.content_type) }, options), key, id, body.byteLength);
+            },
+            removeFlat: (project, id, key, options) => { hivesObjectKey(key); if (!/^[A-Za-z0-9_-]+(?:\.[A-Za-z0-9_-]+)*$/.test(key))
+                throw resourceError(0); return call('hives_delete_object', { ...ids(project, id), key }, options, 'empty'); },
+        },
+        async presign(project, id, body, options) {
+            hivesObjectKey(body.key);
+            const method = body.method ?? 'GET';
+            if (!['GET', 'PUT'].includes(method) || body.expires_in_secs !== undefined && (!Number.isInteger(body.expires_in_secs) || body.expires_in_secs < 60 || body.expires_in_secs > 900)
+                || method === 'PUT' && (body.content_length === undefined || !Number.isInteger(body.content_length) || body.content_length < 0 || body.content_length > HIVES_OBJECT_BYTES))
+                throw resourceError(0);
+            if (body.content_type !== undefined)
+                hivesContentType(body.content_type);
+            const result = await call('hives_generate_presigned_url', { ...ids(project, id), body }, options);
+            if (!result || typeof result.url !== 'string' || result.method !== method || typeof result.expires_at !== 'string')
+                throw resourceError(0);
+            const url = new URL(result.url);
+            if (url.protocol !== 'https:' || url.hostname !== 'storage.googleapis.com' || url.username || url.password || url.hash)
+                throw resourceError(0);
+            const headers = result.required_headers;
+            if (headers !== undefined && (!headers || typeof headers !== 'object' || Array.isArray(headers) || Object.entries(headers).some(([k, v]) => !['content-type', 'content-length', 'x-goog-if-generation-match'].includes(k.toLowerCase()) || typeof v !== 'string' || /[\u0000-\u001f\u007f]/.test(v))))
+                throw resourceError(0);
+            return { url: result.url, expires_at: result.expires_at, method: result.method, ...(headers ? { required_headers: { ...headers } } : {}) };
+        },
+    };
+}

package/dist/hives-environment.d.ts

@@ -0,0 +1,28 @@
+/** Environment metadata never carries stored values. Reveals are explicit. */
+export declare function validateHivesEnvironment(input: unknown): Record<string, string>;
+export declare function hivesEnvironmentMetadata(value: unknown, project: unknown, updated: boolean): {
+    project_id: string;
+    updated: {
+        name: string;
+    }[];
+    data?: undefined;
+    pagination?: undefined;
+} | {
+    project_id: string;
+    data: {
+        name: string;
+    }[];
+    pagination: {
+        page: unknown;
+        per_page: unknown;
+        total: unknown;
+        total_pages: unknown;
+        has_next: boolean;
+        has_prev: boolean;
+    };
+    updated?: undefined;
+};
+export declare function hivesEnvironmentReveal(value: unknown, key: unknown): {
+    name: string;
+    value: string;
+};

package/dist/hives-environment.js

@@ -0,0 +1,58 @@
+/** Environment metadata never carries stored values. Reveals are explicit. */
+export function validateHivesEnvironment(input) {
+    if (!input || typeof input !== 'object' || Array.isArray(input))
+        throw new Error('Environment input must be a flat JSON map of names to string values.');
+    const entries = Object.entries(input);
+    if (entries.length < 1 || entries.length > 100)
+        throw new Error('Environment updates require 1–100 names.');
+    const result = Object.create(null);
+    for (const [name, value] of entries) {
+        if (name.length > 255 || !/^[A-Za-z][A-Za-z0-9_]*$/.test(name))
+            throw new Error('Environment names must start with a letter and contain only letters, numbers and underscores (up to 255 characters).');
+        if (typeof value !== 'string' || new TextEncoder().encode(value).length > 65536)
+            throw new Error('Environment values must be strings of at most 65,536 UTF-8 bytes. Empty values are allowed.');
+        result[name] = value;
+    }
+    if (new TextEncoder().encode(JSON.stringify(result)).length > 2 * 1024 * 1024)
+        throw new Error('Environment input exceeds 2 MiB. Split it into smaller batches.');
+    return result;
+}
+function record(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('Hives returned invalid environment metadata.');
+    return value;
+}
+function names(value) {
+    if (!Array.isArray(value))
+        throw new Error('Hives returned invalid environment metadata.');
+    return value.map((value) => {
+        const row = record(value);
+        if (typeof row.name !== 'string')
+            throw new Error('Hives returned invalid environment metadata.');
+        return { name: row.name };
+    });
+}
+export function hivesEnvironmentMetadata(value, project, updated) {
+    const data = record(value);
+    if (typeof project !== 'string' || data.project_id !== project)
+        throw new Error('Hives returned environment metadata for a different project.');
+    if (updated)
+        return { project_id: project, updated: names(data.updated) };
+    const pagination = record(data.pagination);
+    for (const key of ['page', 'per_page', 'total', 'total_pages']) {
+        if (!Number.isSafeInteger(pagination[key]) || pagination[key] < (key === 'page' || key === 'per_page' ? 1 : 0))
+            throw new Error('Hives returned invalid environment pagination.');
+    }
+    if (typeof pagination.has_next !== 'boolean' || typeof pagination.has_prev !== 'boolean')
+        throw new Error('Hives returned invalid environment pagination.');
+    return { project_id: project, data: names(data.data), pagination: {
+            page: pagination.page, per_page: pagination.per_page, total: pagination.total, total_pages: pagination.total_pages,
+            has_next: pagination.has_next, has_prev: pagination.has_prev,
+        } };
+}
+export function hivesEnvironmentReveal(value, key) {
+    const data = record(value);
+    if (typeof key !== 'string' || data.name !== key || typeof data.value !== 'string' || new TextEncoder().encode(data.value).length > 65536)
+        throw new Error('Hives returned invalid environment reveal data.');
+    return { name: data.name, value: data.value };
+}

package/dist/hives-functions.d.ts

@@ -0,0 +1,36 @@
+import { GenesisError } from './errors.js';
+/** The service separately bounds its serialized guest stdin envelope at 10 MiB. */
+export declare const MAX_FUNCTION_BODY_BYTES: number;
+export declare const MAX_FUNCTION_JSON_BYTES: number;
+export interface HivesInvokeRequest {
+    method?: string;
+    path?: string;
+    headers?: Record<string, string>;
+    body?: unknown;
+    body_base64?: string;
+}
+export interface HivesInvokeOptions {
+    signal?: AbortSignal;
+    idempotencyKey?: string;
+}
+export interface HivesOperationStatus {
+    operation_id: string;
+    state: 'prepared' | 'reserve_unknown' | 'reserved' | 'dispatch_unknown' | 'dispatch_authorized' | 'dispatched' | 'settle_unknown' | 'settled' | 'release_pending' | 'released';
+    code: string;
+    funding_source: 'sandbox_allowance' | 'stripe_test_metered' | null;
+    reservation_id: string | null;
+    retry_execution: false;
+}
+export declare function hivesInvokeHeaders(options: HivesInvokeOptions): Record<string, string>;
+export declare function hivesOperationStatus(value: unknown, expected: string): HivesOperationStatus;
+export declare class HivesOperationError extends GenesisError {
+    readonly operation: HivesOperationStatus;
+    constructor(status: number, operation: HivesOperationStatus);
+}
+/** Read only the small platform receipt; never retain reflected guest request data. */
+export declare function hivesOperationError(response: Response): Promise<HivesOperationError | undefined>;
+export declare function validateHivesInvocation(input: unknown): asserts input is HivesInvokeRequest;
+/** Safe display/transport headers; customer headers never establish identity. */
+export declare function hivesFunctionResponseHeaders(headers: Headers): Headers;
+/** Metadata contracts cannot accidentally expose an upstream env/ciphertext field. */
+export declare function hivesFunctionMetadata(input: unknown, project: unknown, expectedId?: unknown): Record<string, unknown>;