@warmhub/sdk-ts 0.44.0

package/dist/index.d.ts

@@ -0,0 +1,3316 @@
+type ActionAttempt = {
+    attempt: number;
+    status: string;
+    startedAt: number;
+    finishedAt?: number;
+    httpStatus?: number;
+    errorCode?: string;
+    errorMessage?: string;
+    responseSnippet?: string;
+};
+type ActionLiveFeedResult = {
+    items: Array<{
+        subscriptionName: string;
+        runId?: string;
+        status: string;
+        matchedOperationIndexes: Array<number>;
+        matchedOperations: Array<{
+            index: number;
+            operation?: unknown;
+        }>;
+        createdAt: number;
+        updatedAt?: number;
+        runStatus?: string;
+        attemptCount?: number;
+        maxAttempts?: number;
+        lastErrorCode?: string;
+        lastErrorMessage?: string;
+        lastResponseSnippet?: string;
+        traceId?: string;
+        causationId?: string;
+        hopCount?: number;
+        originRunId?: string;
+        originRepoId?: string;
+        actionContainer?: string;
+    }>;
+    nextCursor?: string;
+};
+type ActionNotification = {
+    subscriptionName?: string;
+    attempt: number;
+    channel: string;
+    status: string;
+    eventType?: string;
+    errorCode?: string;
+    errorMessage?: string;
+    createdAt: number;
+};
+type ActionRun = {
+    runId: string;
+    subscriptionName?: string;
+    status: string;
+    matchedOperationIndexes: Array<number>;
+    attemptCount: number;
+    maxAttempts: number;
+    lastErrorCode?: string;
+    lastErrorMessage?: string;
+    traceId?: string;
+    causationId?: string;
+    hopCount?: number;
+    originRunId?: string;
+    originRepoId?: string;
+    createdAt: number;
+    updatedAt: number;
+};
+type AuthSyncResult = {
+    success: boolean;
+};
+type CollectionAbout$2 = {
+    pair: [string, string];
+} | {
+    triple: [string, string, string];
+} | {
+    set: Array<string>;
+} | {
+    list: Array<string>;
+};
+type CollectionTag$1 = 'pair' | 'triple' | 'set' | 'list';
+type CommitApplyResult = {
+    committer?: string;
+    createdByEmail?: string;
+    message?: string;
+    operationCount: number;
+    operations: Array<{
+        name: string;
+        operation: 'add' | 'revise' | 'retract' | 'noop';
+        version: number;
+        dataHash: string;
+        warnings?: {
+            undeclaredFields: Array<string>;
+            undeclaredFieldsTruncated?: true;
+            totalUndeclared?: number;
+        };
+    }>;
+};
+type ComponentDetail = {
+    componentId: string;
+    componentName: string;
+    version?: string;
+    state?: string;
+    source?: string;
+    sourceRef?: string;
+    resolvedSha?: string;
+    manifestHash?: string;
+    installedAt?: string;
+    checkedAt?: string;
+    active: boolean;
+    wref: string;
+    install: {
+        wref: string;
+        pinnedWref?: string;
+        name: string;
+        kind: 'shape' | 'thing' | 'assertion' | 'collection';
+        shape?: string;
+        shapeName?: string;
+        validatedShape?: string;
+        version: number;
+        data?: unknown;
+        active: boolean;
+        aboutWref?: string;
+        committerWref?: string;
+        createdByWref?: string;
+    };
+    ownedShapes: Array<{
+        name: string;
+        kind: 'shape';
+        active: boolean;
+        version: {
+            version: number;
+            operation: 'add' | 'revise' | 'retract';
+            data: unknown;
+            dataHash: string;
+        } | null;
+        componentId?: string;
+    }>;
+    ownedThings: Array<{
+        wref: string;
+        name: string;
+        kind: 'shape' | 'thing' | 'assertion' | 'collection';
+        shapeName?: string;
+        componentId?: string;
+        version: number;
+        createdAt: number;
+        data?: unknown;
+        active: boolean;
+        aboutWref?: string;
+    }>;
+};
+type ComponentListResult = {
+    items: Array<{
+        componentId: string;
+        componentName: string;
+        version?: string;
+        state?: string;
+        source?: string;
+        sourceRef?: string;
+        resolvedSha?: string;
+        manifestHash?: string;
+        installedAt?: string;
+        checkedAt?: string;
+        active: boolean;
+        wref: string;
+    }>;
+    nextCursor?: string;
+};
+type ComponentSummary = {
+    componentId: string;
+    componentName: string;
+    version?: string;
+    state?: string;
+    source?: string;
+    sourceRef?: string;
+    resolvedSha?: string;
+    manifestHash?: string;
+    installedAt?: string;
+    checkedAt?: string;
+    active: boolean;
+    wref: string;
+};
+type InstallBundledSystemComponentResult = {
+    componentId: string;
+    componentName: string;
+    version: string;
+    state: 'ready' | 'unchanged';
+    componentInstallShapeCreated: boolean;
+    componentInstallShapeReconciled: boolean;
+    componentConfigShapeCreated: boolean;
+    componentConfigShapeReconciled: boolean;
+    componentInstallRecordCreated: boolean;
+    componentInstallRecordReconciled: boolean;
+    identityShapeCreated: boolean;
+    identityShapeReconciled: boolean;
+};
+type CredentialDeleteResult$1 = {
+    ok: true;
+    name: string;
+};
+type CredentialKeyMutationResult$1 = {
+    ok: true;
+    keyName?: string;
+    keyNames: Array<string>;
+};
+type CredentialRevokeResult$1 = {
+    revoked: boolean;
+};
+type Capabilities = {
+    apiVersion: string;
+    minSupportedSdk: string;
+    features: Record<string, boolean>;
+};
+type StreamAppendInput$1 = {
+    orgName: string;
+    repoName: string;
+    streamId: string;
+    componentId?: string;
+    workspaceName?: never;
+    committer?: string;
+    allocatedTokens?: Array<{
+        tokenNumber: number;
+    }>;
+    operations: Array<{
+        operation: 'add';
+        kind: 'shape';
+        name: string;
+        data: unknown;
+        skipExisting?: boolean;
+    } | {
+        operation: 'add';
+        kind: 'thing';
+        name: string;
+        data: unknown;
+        skipExisting?: boolean;
+    } | {
+        operation: 'add';
+        kind: 'assertion';
+        name: string;
+        about: string | {
+            pair: [string, string];
+        } | {
+            triple: [string, string, string];
+        } | {
+            set: Array<string>;
+        } | {
+            list: Array<string>;
+        };
+        data: unknown;
+        skipExisting?: boolean;
+    } | {
+        operation: 'add';
+        kind: 'collection';
+        name?: string;
+        type: 'pair' | 'triple' | 'set' | 'list';
+        members: Array<string>;
+        skipExisting?: boolean;
+    } | {
+        operation: 'revise';
+        kind: 'shape';
+        name: string;
+        data: unknown;
+        active?: never;
+    } | {
+        operation: 'revise';
+        kind: 'thing';
+        name: string;
+        data: unknown;
+        active?: never;
+    } | {
+        operation: 'revise';
+        kind: 'assertion';
+        name: string;
+        data: unknown;
+        active?: never;
+    } | {
+        operation: 'retract';
+        name: string;
+        kind?: 'thing' | 'assertion' | 'shape' | 'collection';
+        reason?: string;
+    }>;
+};
+type StreamAppendResult$1 = {
+    allocatedTokens: Array<{
+        tokenNumber: number;
+    }>;
+    results: Array<{
+        name: string;
+        operation?: 'add' | 'revise' | 'retract' | 'noop';
+        version?: number;
+        dataHash?: string;
+        status?: 'success' | 'noop' | 'failed';
+        error?: {
+            code: string;
+            message: string;
+        };
+        warnings?: {
+            undeclaredFields: Array<string>;
+            undeclaredFieldsTruncated?: true;
+            totalUndeclared?: number;
+        };
+    }>;
+    appendTotalMs?: number;
+    appendResolveRepoMs?: number;
+    appendTokenResolveMs?: number;
+    appendApplyMs?: number;
+    applySubphases?: {
+        addThingMs?: number;
+        addAssertionMs?: number;
+        addAssertionResolveAboutMs?: number;
+        reviseThingMs?: number;
+        reviseAssertionMs?: number;
+        reviseCollectionMs?: number;
+        preparePinnedLoadShapeFieldsMs?: number;
+        preparePinnedPinWrefsMs?: number;
+        preparePinnedResolveTokensMs?: number;
+        preparePinnedValidateMs?: number;
+        operationLoopMs?: number;
+        persistMs?: number;
+        persistThingsMs?: number;
+        persistVersionsMs?: number;
+        persistAssertionsMs?: number;
+        persistUpdatesMs?: number;
+        persistOutboxMs?: number;
+        refInsertMs?: number;
+        refSourceCount?: number;
+    };
+};
+type Org = {
+    name: string;
+    displayName: string;
+    description?: string;
+    tier: 'free' | 'pro' | 'enterprise';
+    archivedAt?: number;
+    createdAt: number;
+    repoCount?: number;
+    errorCount?: number;
+    lastActivityAt?: number;
+};
+type OrgListResult = Array<{
+    name: string;
+    displayName: string;
+    description?: string;
+    tier: 'free' | 'pro' | 'enterprise';
+    archivedAt?: number;
+    createdAt: number;
+    repoCount?: number;
+    errorCount?: number;
+    lastActivityAt?: number;
+}>;
+type OrgMember = {
+    email: string;
+    firstName?: string;
+    lastName?: string;
+    role: 'owner' | 'admin' | 'editor' | 'viewer';
+    status: 'active' | 'pending';
+    invitedBy?: string;
+    createdAt: number;
+};
+type RefsResult$1 = {
+    items: Array<{
+        wref: string;
+        kind?: 'shape' | 'thing' | 'assertion' | 'collection';
+        shapeName?: string;
+        version?: number;
+        fieldPath?: string;
+    }>;
+    nextCursor?: string;
+};
+type ShapeGetResult = {
+    name: string;
+    kind: 'shape';
+    active: boolean;
+    version: {
+        version: number;
+        operation: 'add' | 'revise' | 'retract';
+        data: unknown;
+        dataHash: string;
+    } | null;
+    componentId?: string;
+};
+type ShapeListResult = {
+    items: Array<{
+        name: string;
+        kind: 'shape';
+        active: boolean;
+        version: {
+            version: number;
+            operation: 'add' | 'revise' | 'retract';
+            data: unknown;
+            dataHash: string;
+        } | null;
+        componentId?: string;
+    }>;
+};
+type ThingGetManyResult$1 = {
+    requested: number;
+    items: Array<{
+        wref: string;
+        pinnedWref?: string;
+        name: string;
+        kind: 'shape' | 'thing' | 'assertion' | 'collection';
+        shape?: string;
+        shapeName?: string;
+        validatedShape?: string;
+        version: number;
+        data?: unknown;
+        active: boolean;
+        aboutWref?: string;
+        committerWref?: string;
+        createdByWref?: string;
+    }>;
+    missing: Array<string>;
+};
+type RenameResult$1 = {
+    renamed: true;
+};
+type RepoConfigureStats = {
+    subscriptionCount: number;
+};
+type RepoDescribeResult$1 = {
+    repo: {
+        orgName: string;
+        name: string;
+        description?: string;
+        visibility: 'public' | 'private';
+        archivedAt?: number;
+        createdAt: number;
+    };
+    shapes: {
+        items: Array<unknown>;
+    };
+    subscriptions: Array<unknown>;
+    stats: {
+        total: number;
+        byKind: {
+            shape: number;
+            thing: number;
+            assertion: number;
+        };
+        byShape: Record<string, number>;
+    };
+    configureStats: {
+        subscriptionCount: number;
+    };
+    head: {
+        items: Array<unknown>;
+    };
+    additionalInformation: Array<{
+        name: string;
+        wref: string;
+        synthesized: boolean;
+    }>;
+};
+type RepoListResult = {
+    items: Array<{
+        orgName: string;
+        name: string;
+        description?: string;
+        visibility: 'public' | 'private';
+        archivedAt?: number;
+        createdAt: number;
+    }>;
+    nextCursor?: string;
+};
+type RepoShapeInstanceCounts = Record<string, {
+    things: number;
+    assertions: number;
+}>;
+type RepoStats = {
+    total: number;
+    byKind: {
+        shape: number;
+        thing: number;
+        assertion: number;
+    };
+    byShape: Record<string, number>;
+};
+type RepoStatsBatchResult$1 = {
+    items: Array<{
+        orgName: string;
+        repoName: string;
+        total: number;
+        byKind?: {
+            shape: number;
+            thing: number;
+            assertion: number;
+        };
+    }>;
+};
+type RepoVisibility = 'public' | 'private';
+type SynthesizedRepoContent$1 = {
+    shape: 'Content';
+    name: 'LlmsTxt';
+    active: true;
+    synthesized: true;
+    data: {
+        content: string;
+    };
+    refs?: {
+        outbound: {
+            sameOrg: Array<{
+                wref: string;
+                title: string;
+                description?: string;
+            }>;
+            crossOrg: Array<{
+                wref: string;
+                title: string;
+                description?: string;
+            }>;
+        };
+        inbound: {
+            sameOrg: Array<{
+                wref: string;
+                title: string;
+                description?: string;
+            }>;
+            crossOrg: Array<{
+                wref: string;
+                title: string;
+                description?: string;
+            }>;
+        };
+    };
+};
+type ShapeChangeResult = {
+    name: string;
+    operation: 'add' | 'revise' | 'retract';
+    version: number;
+    dataHash: string;
+};
+type SubscriptionBindCredentialsResult$1 = {
+    bound: true;
+    subscriptionName: string;
+    credentialSetName: string;
+};
+type SubscriptionUnbindCredentialsResult$1 = {
+    unbound: true;
+    subscriptionName: string;
+};
+type TokenCreateInput = {
+    name: string;
+    scopes?: Array<{
+        resource?: string;
+        permissions: Array<string>;
+        allowedMatches?: Array<string>;
+    }>;
+    structured?: boolean;
+    description?: string;
+    expiresAt?: number;
+    committerIdentityWref?: string;
+};
+type TokenCreateResult = {
+    token: string;
+    name: string;
+    scopes?: Array<{
+        resource?: string;
+        permissions: Array<string>;
+        allowedMatches?: Array<string>;
+    }>;
+    warnings?: Array<string>;
+    expiresAt: number;
+    createdAt: number;
+};
+type TokenRevokeResult = {
+    ok: boolean;
+};
+type WireScopeEntry$1 = {
+    resource?: string;
+    permissions: Array<string>;
+    allowedMatches?: Array<string>;
+};
+
+/**
+ * Add operation accepted by `client.commit.apply`. Use this shape to create new
+ * shapes, things, assertions, or collections in a single commit.
+ *
+ * @see https://docs.warmhub.ai/commits/operations/#add-operations
+ */
+interface AddOperation {
+    /**
+     * Operation discriminator. Defaults to `add` when omitted.
+     */
+    operation?: 'add';
+    /**
+     * Optional kind override: `shape`, `thing`, `assertion`, or `collection`.
+     * When omitted, kind is inferred from `name` segmentation (1-seg → thing,
+     * 2-seg `Shape/name` → thing, 3+ segments → assertion).
+     */
+    kind?: 'shape' | 'thing' | 'assertion' | 'collection';
+    /**
+     * Target name. Use `Shape/localName` for things and assertions; use the
+     * plain shape name for shapes.
+     */
+    name?: string;
+    /**
+     * Assertion target wref or inline collection descriptor. Presence of
+     * `about` makes the add an assertion unless `kind` overrides it.
+     */
+    about?: string | CollectionAbout$2;
+    /**
+     * Shape-validated data payload for shape, thing, or assertion adds.
+     */
+    data?: unknown;
+    /**
+     * Collection type. Used only for collection adds.
+     */
+    type?: CollectionTag$1;
+    /**
+     * Collection member wrefs. Used only for collection adds.
+     */
+    members?: string[];
+    /**
+     * When true, an existing target returns `noop` instead of failing with
+     * `ALREADY_EXISTS`. Use for caller-side idempotency on retried writes.
+     */
+    skipExisting?: boolean;
+}
+/**
+ * Revise operation accepted by `client.commit.apply`. Replaces the shape-validated
+ * data on an existing shape, thing, or assertion and creates a new version.
+ *
+ * `data` is a full replacement, not a patch — include every shape field, not
+ * just the ones that changed. Revise cannot deactivate a target: the `active`
+ * field is declared `never` at the type level, so passing `active: false` is
+ * a compile error. Use a {@link RetractOperation} to mark an entity inactive.
+ *
+ * @see https://docs.warmhub.ai/commits/operations/#revise-operations
+ */
+interface ReviseOperation {
+    /**
+     * Operation discriminator. Defaults to `revise` when omitted.
+     */
+    operation?: 'revise';
+    /**
+     * Optional kind safety hint: `shape`, `thing`, `assertion`, or `collection`.
+     */
+    kind?: 'shape' | 'thing' | 'assertion' | 'collection';
+    /**
+     * Target name to revise. Equivalent to `wref` for local paths.
+     */
+    name?: string;
+    /**
+     * Target wref to revise. Cross-repo references use `wh:org/repo/Shape/name`.
+     */
+    wref?: string;
+    /**
+     * New shape-validated data payload.
+     */
+    data?: unknown;
+    /**
+     * Type-level guard: revise cannot toggle activity. The field is declared
+     * `never` so passing `active: true` or `active: false` is a TypeScript error.
+     * To mark an entity inactive, use a {@link RetractOperation} instead.
+     */
+    active?: never;
+}
+/**
+ * Retract operation accepted by `client.commit.apply`. Marks the target as
+ * retracted in a new version; prior versions remain queryable by history.
+ *
+ * @see https://docs.warmhub.ai/commits/operations/#retract-operations
+ */
+interface RetractOperation {
+    /**
+     * Operation discriminator. Required.
+     */
+    operation: 'retract';
+    /**
+     * Target wref or local name to retract.
+     */
+    name: string;
+    /**
+     * Optional kind safety hint: `thing`, `assertion`, `shape`, or `collection`.
+     */
+    kind?: 'thing' | 'assertion' | 'shape' | 'collection';
+    /**
+     * Optional human-readable retraction reason.
+     */
+    reason?: string;
+}
+/**
+ * Commit operation accepted by `client.commit.apply`. Discriminated union over
+ * {@link AddOperation}, {@link ReviseOperation}, and {@link RetractOperation},
+ * keyed on `operation`.
+ *
+ * Inline array literals passed directly to `client.commit.apply` are
+ * contextually typed by the parameter, so `operation: "add"` stays narrowed
+ * and the call typechecks. Binding the array to a variable **without** a
+ * type annotation widens `operation` to `string`, so the variable no
+ * longer assigns to the `Operation[]` parameter. Either annotate the
+ * variable as `Operation[]` (contextually typed by the annotation) or use
+ * `satisfies Operation[]` to preserve the inferred literal types:
+ *
+ * ```ts
+ * // 1. Annotate the variable.
+ * const ops: Operation[] = [
+ *   { operation: "add", kind: "thing", name: "Sensor/temp-1", data: { x: 1 } },
+ *   { operation: "revise", name: "Sensor/temp-1", data: { x: 2 } },
+ * ];
+ *
+ * // 2. Or use `satisfies` to keep the inferred literal types.
+ * const ops2 = [
+ *   { operation: "add", kind: "thing", name: "Sensor/temp-1", data: { x: 1 } },
+ *   { operation: "revise", name: "Sensor/temp-1", data: { x: 2 } },
+ * ] satisfies Operation[];
+ *
+ * await client.commit.apply("acme", "world", "seed", ops);
+ * ```
+ *
+ * @see https://docs.warmhub.ai/sdk/commit-vs-builder/#typing-operation-arrays
+ */
+type Operation = AddOperation | ReviseOperation | RetractOperation;
+
+/**
+ * Default number of operations the SDK sends per stream append chunk.
+ * @see https://docs.warmhub.ai/sdk-reference/variables/default_stream_chunk_size/
+ */
+declare const DEFAULT_STREAM_CHUNK_SIZE = 1000;
+/**
+ * Maximum number of operations accepted by one stream append chunk.
+ * @see https://docs.warmhub.ai/sdk-reference/variables/max_stream_append_operation_count/
+ */
+declare const MAX_STREAM_APPEND_OPERATION_COUNT = 10000;
+interface OperationStreamClient {
+    stream: {
+        append(input: StreamAppendInput$1): Promise<StreamAppendResult$1>;
+    };
+}
+type SubmittedStreamResult = {
+    committer?: string;
+    message: string | undefined;
+    operationCount: number;
+    operations: Array<{
+        name: string;
+        operation: 'add' | 'revise' | 'retract' | 'noop';
+        dataHash: string;
+        version: number;
+        status?: 'success' | 'noop' | 'failed';
+        error?: {
+            code: string;
+            message: string;
+        };
+        /**
+         * Non-blocking warnings collected during shape validation — see GH-1418.
+         * Aliased to the generated wire shape so this type cannot drift from
+         * the backend's `streamMutationResultEntrySchema.warnings`.
+         */
+        warnings?: NonNullable<StreamAppendResult$1['results'][number]['warnings']>;
+    }>;
+};
+/**
+ * Continuation state for caller-managed streamed commit submissions.
+ * @see https://docs.warmhub.ai/sdk-reference/type-aliases/streamcontinuationstate/
+ */
+type StreamContinuationState = {
+    streamId: string;
+    allocatedTokens: StreamAppendResult$1['allocatedTokens'];
+};
+/**
+ * Caller-facing knobs for the SDK's auto-idempotency retry on transient
+ * first-chunk failures.
+ *
+ * Defaults are tuned for interactive and agent latency budgets: 3 attempts
+ * with exponential backoff capped at 8s, so a one-off flake recovers without
+ * user-perceptible latency. Override individual fields as needed.
+ *
+ * @see https://docs.warmhub.ai/sdk/transient-retry/#tuning-retry
+ */
+type RetryPolicyOptions = {
+    maxAttempts?: number;
+    baseDelayMs?: number;
+    maxDelayMs?: number;
+};
+/**
+ * Error raised when a streamed commit submission fails after an ambiguous or
+ * partial append.
+ *
+ * The `completedOperations` field contains operations the SDK knows completed.
+ * Before retrying manually, inspect repository state because the failed append
+ * may have committed additional operations that were not reflected locally.
+ *
+ * @see https://docs.warmhub.ai/sdk/transient-retry/#partial-submissions
+ */
+declare class PartialStreamSubmissionError extends Error {
+    /**
+     * Stable error code. Always `'PARTIAL_STREAM_SUBMISSION'`.
+     */
+    readonly code = "PARTIAL_STREAM_SUBMISSION";
+    /**
+     * Operations the SDK confirmed completed before the ambiguous or failing
+     * append. The remaining operations may or may not have landed; inspect
+     * repository state before retrying manually.
+     * @see https://docs.warmhub.ai/sdk-reference/classes/partialstreamsubmissionerror/#completedoperations
+     */
+    readonly completedOperations: SubmittedStreamResult['operations'];
+    /**
+     * Underlying error that triggered the partial submission, preserved for
+     * diagnostics. Inspect via `isWarmHubError(err.cause)` / `err.cause.kind`.
+     * @see https://docs.warmhub.ai/sdk-reference/classes/partialstreamsubmissionerror/#cause
+     */
+    readonly cause: unknown;
+    constructor(input: {
+        cause: unknown;
+        completedOperations: SubmittedStreamResult['operations'];
+    });
+}
+/**
+ * Submit `operations` to the WarmHub stream-append surface, chunked to
+ * stay under MAX_STREAM_APPEND_OPERATION_COUNT.
+ *
+ * **Retry policy (default-on, first-chunk + single-op only).** A
+ * transport-ambiguous failure (timeout / 5xx / network reset / no-code
+ * error) on the first chunk triggers a bounded retry — but only when
+ * the first chunk contains exactly one operation. The SDK mints a
+ * fresh `streamId`, resets `allocatedTokens`, sleeps with jittered
+ * exponential backoff, and re-issues the same operation. The retried
+ * call is observationally indistinguishable from a single clean
+ * apply — the SDK does not rewrite the request or the response.
+ *
+ * Multi-op chunks bypass retry entirely because the backend applies
+ * operations one-at-a-time in their own transactions, so a mid-chunk
+ * transport failure on attempt 1 may have committed an arbitrary
+ * prefix. Chunks that allocate or reference `$N`/`#N` tokens also
+ * bypass retry — the backend resolves those tokens against `streamId`,
+ * so re-issuing under a fresh `streamId` would commit a different
+ * identity than the first attempt may have landed. Multi-chunk
+ * mid-flight failures (`chunkResults.length > 0`) also bypass retry.
+ * All three surface `PartialStreamSubmissionError` exactly as before;
+ * the existing CLI continuation flags (`--stream-id`,
+ * `--allocated-tokens`, `--operation-offset`) remain the manual-resume
+ * contract.
+ *
+ * Definite client rejections (`UNAUTHENTICATED`, `VALIDATION_ERROR`,
+ * `CONFLICT`, `RATE_LIMITED`, `UNRESOLVED_TOKEN`, `ALREADY_RETRACTED`,
+ * …) on the first chunk still rethrow the raw cause unchanged — they
+ * are not transient, and structured detail (e.g. `retryAfter` on
+ * `RATE_LIMITED`) survives. If the caller's original attempt landed but
+ * the response was lost, the retry surfaces the resulting `CONFLICT`
+ * (for `add`) or `ALREADY_RETRACTED` (for `retract`) directly so the
+ * caller sees the truth.
+ *
+ * **Ambiguity preservation across attempts.** Once any attempt has
+ * been transport-ambiguous (timeout / 5xx / reset), a subsequent
+ * definite-reject (e.g. `RATE_LIMITED` on a quota check) does *not*
+ * prove the prior attempt didn't land. In that case the SDK wraps the
+ * cause as `PartialStreamSubmissionError` instead of rethrowing raw,
+ * so the "inspect repo state before continuing" warning survives.
+ *
+ * **Operation normalization.** `args.operations` accepts the public
+ * `Operation[]` write contract. The SDK normalizes operations to the
+ * backend stream shape before chunking, token checks, and appends.
+ *
+ * **Idempotency is the caller's responsibility.** To make `add` ops
+ * idempotent under retry (the GH #2243 agent-health-write use case),
+ * pass `skipExisting: true` per-op, via `args.skipExisting`, or via
+ * `commit.apply`'s `opts`:
+ *
+ * ```ts
+ * client.commit.apply(org, repo, msg, ops, { skipExisting: true })
+ * ```
+ *
+ * `args.skipExisting: true` applies `skipExisting: true` to every
+ * normalized `add` op. The server then returns `noop` for `add` ops
+ * whose target already exists. `revise` is naturally idempotent on
+ * equal `dataHash` + `aboutThingId`; built-in collection adds dedupe
+ * on `dataHash`.
+ *
+ * Pass `args.retry: false` to disable retry entirely; pass
+ * `args.retry: { maxAttempts, baseDelayMs, maxDelayMs }` to override
+ * any subset of the defaults (`{ 3, 250, 8_000 }`).
+ *
+ * Retry is automatically suppressed when the caller supplies
+ * `args.streamId` or a non-empty `args.allocatedTokens` (manual-resume
+ * mode). Re-minting a fresh `streamId` on retry would invalidate the
+ * `$N`/`#N` token bindings carried in the supplied `allocatedTokens`,
+ * so a resumed call instead surfaces `PartialStreamSubmissionError` on
+ * any append failure exactly as before.
+ *
+ * The server remains stateless across `stream.append` calls — there is
+ * no `streamId`-keyed dedup table. See docs/dev/commit-flow.md for the
+ * full idempotency contract.
+ *
+ * @see https://docs.warmhub.ai/sdk/transient-retry/
+ */
+declare function submitOperationsViaStream(client: OperationStreamClient, args: {
+    orgName: string;
+    repoName: string;
+    committer?: string;
+    message?: string;
+    operations: Operation[];
+    componentId?: string;
+    chunkSize?: number;
+    skipExisting?: boolean;
+    streamId?: string;
+    allocatedTokens?: StreamAppendResult$1['allocatedTokens'];
+    /**
+     * Bounded auto-idempotency retry for transient first-chunk failures.
+     * Default-on (3 attempts, 250ms base, 8s cap, jittered exponential).
+     * Pass `false` to disable. Multi-chunk mid-flight failures still
+     * surface PartialStreamSubmissionError unchanged.
+     */
+    retry?: RetryPolicyOptions | false;
+}): Promise<SubmittedStreamResult>;
+
+type CollectionAbout$1 = {
+    pair: [string, string];
+} | {
+    triple: [string, string, string];
+} | {
+    set: string[];
+} | {
+    list: string[];
+};
+
+/**
+ * Hardcoded meta-schema for validating shape definitions.
+ * Shapes are NOT validated against a DB-stored shape — they validate against this constant.
+ * This avoids the bootstrap chicken-and-egg problem.
+ *
+ * A valid shape definition is:
+ * { fields: Record<string, TypeSpec>, description?: string }
+ * where TypeSpec is one of:
+ *   - primitive string: "number", "string", "boolean", "wref"
+ *   - optional primitive: "number?", "string?", "boolean?", "wref?"
+ *   - typed field object: { type: primitive, description?: string }
+ *   - array: [TypeSpec]
+ *   - nested object: { fieldName: TypeSpec, ... } (key may end with "?" for optional)
+ * @see https://docs.warmhub.ai/sdk-reference/variables/max_content_field_bytes/
+ */
+declare const MAX_CONTENT_FIELD_BYTES: number;
+/**
+ * @see https://docs.warmhub.ai/sdk-reference/variables/content_field_limit_error/
+ */
+declare const CONTENT_FIELD_LIMIT_ERROR: string;
+/**
+ * @see https://docs.warmhub.ai/sdk-reference/functions/contentfieldlimiterror/
+ */
+declare function contentFieldLimitError(path: string, value: string): string | null;
+/**
+ * Validate a data payload against shape field definitions.
+ *
+ * Shape field types:
+ * - "number", "string", "boolean": primitive types
+ * - "wref": string (reference to another thing)
+ * - Typed field objects: { type: primitive, description?: string }
+ * - Nested objects: { fieldName: type, ... }
+ * - Arrays: [elementType]
+ * - Optional fields: field name ending with "?" (e.g. "terminal_reason?": "string")
+ *   OR type string ending with "?" (e.g. "terminal_reason": "string?")
+ *   OR typed object type ending with "?" (e.g. { type: "string?" })
+ *
+ * For v1 this is permissive: validates top-level field existence and basic types.
+ * Returns a {@link ShapeValidatorResult} discriminated union — read `result.valid`
+ * to branch, then `result.errors` (only present when invalid) for the list of
+ * messages. `result.warnings` may be present in either branch and carries
+ * undeclared top-level field names.
+ *
+ * @example
+ * ```ts
+ * import { validateAgainstShape } from "@warmhub/sdk-ts";
+ *
+ * const shapeFields = { x: "number", y: "number", label: "string?" };
+ *
+ * const ok = validateAgainstShape({ x: 1, y: 2 }, shapeFields);
+ * // ok.valid === true
+ *
+ * const bad = validateAgainstShape({ x: "not-a-number" }, shapeFields);
+ * if (!bad.valid) {
+ *   for (const message of bad.errors) console.error(message);
+ *   // ['Field "x" must be a number', 'Missing required field: "y"']
+ * }
+ * ```
+ * @see https://docs.warmhub.ai/sdk-reference/functions/validateagainstshape/
+ */
+declare function validateAgainstShape(data: Record<string, unknown>, shapeFields: Record<string, unknown>): ShapeValidatorResult;
+/**
+ * @see https://docs.warmhub.ai/sdk-reference/type-aliases/undeclaredfieldswarning/
+ */
+type UndeclaredFieldsWarning = {
+    undeclaredFields: string[];
+    undeclaredFieldsTruncated?: true;
+    totalUndeclared?: number;
+};
+/**
+ * @see https://docs.warmhub.ai/sdk-reference/type-aliases/shapevalidatorresult/
+ */
+type ShapeValidatorResult = {
+    valid: true;
+    warnings?: UndeclaredFieldsWarning;
+} | {
+    valid: false;
+    errors: string[];
+    warnings?: UndeclaredFieldsWarning;
+};
+
+/**
+ * Shape field definitions — the value side of a shape's data.fields
+ * @see https://docs.warmhub.ai/sdk-reference/type-aliases/shapefields/
+ */
+type ShapeFields = Record<string, unknown>;
+
+/**
+ * Builder add operation for shapes, things, assertions, and collections.
+ * @see https://docs.warmhub.ai/sdk-reference/interfaces/addop/
+ */
+interface AddOp {
+    /**
+     * Operation discriminator. Always `add`.
+     */
+    readonly operation: 'add';
+    /**
+     * Target name. Use `Shape/localName` for things and assertions; use the plain shape name for shapes.
+     */
+    readonly name: string;
+    /**
+     * Optional kind override: `shape`, `thing`, `assertion`, or `collection`.
+     */
+    readonly kind?: string;
+    /**
+     * Assertion target wref or inline collection descriptor. Presence of `about` makes the add an assertion unless `kind` overrides it.
+     */
+    readonly about?: string | CollectionAbout$1;
+    /**
+     * Collection type. Used only for collection adds.
+     */
+    readonly type?: string;
+    /**
+     * Collection member wrefs. Used only for collection adds.
+     */
+    readonly members?: string[];
+    /**
+     * Optional shape wref used by local validation.
+     */
+    readonly shapeWref?: string;
+    /**
+     * Deprecated spelling for `about`; retained for compatibility.
+     */
+    readonly aboutWref?: string;
+    /**
+     * Shape-validated data payload for shape, thing, or assertion adds.
+     */
+    readonly data?: unknown;
+    /**
+     * When true, an existing target returns `noop` instead of failing.
+     */
+    readonly skipExisting?: boolean;
+}
+/**
+ * Builder revise operation.
+ * @see https://docs.warmhub.ai/sdk-reference/interfaces/reviseop/
+ */
+interface ReviseOp {
+    /**
+     * Operation discriminator. Always `revise`.
+     */
+    readonly operation: 'revise';
+    /**
+     * Target wref to revise.
+     */
+    readonly wref?: string;
+    /**
+     * Target name to revise. Equivalent to `wref` for local paths.
+     */
+    readonly name?: string;
+    /**
+     * Optional kind safety hint: `shape`, `thing`, `assertion`, or `collection`.
+     */
+    readonly kind?: string;
+    /**
+     * New shape-validated data payload.
+     */
+    readonly data?: unknown;
+}
+/**
+ * Builder retract operation.
+ * @see https://docs.warmhub.ai/sdk-reference/interfaces/retractop/
+ */
+interface RetractOp {
+    /**
+     * Operation discriminator. Always `retract`.
+     */
+    readonly operation: 'retract';
+    /**
+     * Target wref or local name to retract.
+     */
+    readonly name: string;
+    /**
+     * Optional kind safety hint: `thing`, `assertion`, `shape`, or `collection`.
+     */
+    readonly kind?: 'thing' | 'assertion' | 'shape' | 'collection';
+    /**
+     * Optional human-readable retraction reason.
+     */
+    readonly reason?: string;
+}
+/**
+ * Operation queued by `OperationBuilder`.
+ * @see https://docs.warmhub.ai/sdk-reference/type-aliases/operationbuilderop/
+ */
+type OperationBuilderOp = AddOp | ReviseOp | RetractOp;
+type OperationSubmitResult$1 = SubmittedStreamResult;
+/**
+ * Client-side validation diagnostic returned by `OperationBuilder.validate`.
+ * @see https://docs.warmhub.ai/sdk-reference/interfaces/validationdiagnostic/
+ */
+interface ValidationDiagnostic {
+    /**
+     * Machine-readable diagnostic code.
+     */
+    code: string;
+    /**
+     * Zero-based operation index, or `-1` for whole-builder diagnostics.
+     */
+    operationIndex: number;
+    /**
+     * Human-readable diagnostic message.
+     */
+    message: string;
+}
+/**
+ * Result returned by `OperationBuilder.validate`.
+ * @see https://docs.warmhub.ai/sdk-reference/interfaces/validationresult/
+ */
+interface ValidationResult {
+    /**
+     * Whether validation produced no errors.
+     */
+    valid: boolean;
+    /**
+     * Blocking diagnostics that prevent commit submission.
+     */
+    errors: ValidationDiagnostic[];
+    /**
+     * Non-blocking diagnostics for suspicious but possibly valid operations.
+     */
+    warnings: ValidationDiagnostic[];
+}
+/**
+ * Options for constructing an `OperationBuilder`.
+ * @see https://docs.warmhub.ai/sdk-reference/interfaces/operationbuilderoptions/
+ */
+interface OperationBuilderOptions {
+    /**
+     * Known shape definitions used for local data validation.
+     */
+    shapes?: Record<string, ShapeFields>;
+}
+/** @internal */
+type OperationBuilderClient = OperationStreamClient;
+type AddInput = Omit<AddOp, 'operation'> | AddOp;
+type ReviseInput = Omit<ReviseOp, 'operation'> | ReviseOp;
+/**
+ * Fluent builder for composing, validating, and submitting WarmHub commit
+ * operations.
+ *
+ * Use this when a caller needs to build a batch incrementally, run local
+ * preflight checks, optionally validate data against known shapes, and submit
+ * through the SDK stream-append path with continuation and retry options.
+ *
+ * The builder is not a promise — there is no `build()` method, and `await cb`
+ * alone will not submit anything. Finalize the batch by calling
+ * `await cb.commit({ client, orgName, repoName, ... })`, which validates,
+ * submits, and seals the builder in one step. Reusing a sealed builder throws.
+ *
+ * @example
+ * ```ts
+ * const cb = new OperationBuilder();
+ * cb
+ *   .add({ name: "Sensor/temp-1", data: { location: "A" } })
+ *   .revise({ name: "Sensor/temp-1", data: { location: "B" } });
+ * const result = await cb.commit({ client, orgName: "acme", repoName: "world" });
+ * ```
+ *
+ * @see https://docs.warmhub.ai/sdk/commit-vs-builder/
+ */
+declare class OperationBuilder {
+    private readonly ops;
+    private readonly pendingNames;
+    private readonly shapes;
+    private readonly wrefToShape;
+    private submitted;
+    private inFlight;
+    /**
+     * Create an empty operation builder.
+     *
+     * Pass known shape definitions when you want local data validation before submitting operations.
+     */
+    constructor(options?: OperationBuilderOptions);
+    /**
+     * Add a shape, thing, assertion, or collection operation.
+     *
+     * For things and assertions, names use `Shape/localName`. Supplying `about` makes the operation an assertion. Supplying collection `type` and `members` makes it a collection. Otherwise the builder infers kind from the name.
+     *
+     * Set `kind: 'thing'` explicitly for hierarchical thing names that would otherwise look like assertion paths.
+     * @see https://docs.warmhub.ai/sdk-reference/classes/operationbuilder/#add
+     */
+    add(op: AddInput): this;
+    /**
+     * Add a revise operation.
+     *
+     * The target can be supplied as `name` or `wref`. When shape definitions were provided to the constructor, revise data is validated locally before the operation is queued.
+     * @see https://docs.warmhub.ai/sdk-reference/classes/operationbuilder/#revise
+     */
+    revise(op: ReviseInput): this;
+    /**
+     * Add a retract operation.
+     *
+     * Pass a wref string shorthand or an object with a target name, optional kind safety hint, and optional reason.
+     * @see https://docs.warmhub.ai/sdk-reference/classes/operationbuilder/#retract
+     */
+    retract(target: string | {
+        name: string;
+        kind?: 'thing' | 'assertion' | 'shape' | 'collection';
+        reason?: string;
+    }): this;
+    /**
+     * Return the queued operations.
+     *
+     * The returned array is read-only; use `add`, `revise`, and `retract` to modify the builder.
+     * @see https://docs.warmhub.ai/sdk-reference/classes/operationbuilder/#operations
+     */
+    get operations(): ReadonlyArray<OperationBuilderOp>;
+    /**
+     * Return the number of queued operations.
+     * @see https://docs.warmhub.ai/sdk-reference/classes/operationbuilder/#size
+     */
+    get size(): number;
+    /**
+     * Return whether this builder has queued an add operation for a name.
+     * @see https://docs.warmhub.ai/sdk-reference/classes/operationbuilder/#has
+     */
+    has(name: string): boolean;
+    /**
+     * Run client-side validation without contacting the server.
+     *
+     * Validation checks for empty commits, duplicate adds, missing revise targets, revise-after-retract patterns, local shape-data errors when shapes were provided, and the same preflight diagnostics used before commit submission.
+     *
+     * Returns a {@link ValidationResult} object (`{ valid, errors, warnings }`) —
+     * not a boolean. Read `result.valid` to gate submission, and iterate
+     * `result.errors` for blocking diagnostics or `result.warnings` for
+     * informational ones.
+     *
+     * @example
+     * ```ts
+     * const cb = new OperationBuilder();
+     * cb.add({ name: "Location/cave", data: { x: 0, y: 0 } });
+     * const result = cb.validate();
+     * if (!result.valid) {
+     *   for (const err of result.errors) {
+     *     console.error(`op ${err.operationIndex}: ${err.code} — ${err.message}`);
+     *   }
+     *   throw new Error("validation failed");
+     * }
+     * for (const warn of result.warnings) console.warn(warn.message);
+     * ```
+     * @see https://docs.warmhub.ai/sdk-reference/classes/operationbuilder/#validate
+     */
+    validate(): ValidationResult;
+    /**
+     * Validate, submit, and seal the builder.
+     *
+     * A successful call submits operations through the same stream path as `client.commit.apply` and makes the builder single-use. Validation failures throw before any server request is made. Ambiguous multi-chunk failures surface as `PartialStreamSubmissionError`.
+     *
+     * @param params.client WarmHub client or compatible stream client used for submission.
+     * @param params.message Optional commit message.
+     * @param params.committer Optional wref identifying the actor on whose behalf the write is made.
+     * @param params.chunkSize Maximum operations per stream append.
+     * @param params.streamId Advanced continuation hook for caller-managed streams.
+     * @param params.allocatedTokens Advanced continuation hook for `$N` / `#N` token allocation state.
+     * @param params.retry Retry policy for transient first-chunk failures, or `false` to disable automatic retry.
+     * @see https://docs.warmhub.ai/sdk-reference/classes/operationbuilder/#commit
+     */
+    commit(params: {
+        client: OperationBuilderClient;
+        orgName: string;
+        repoName: string;
+        committer?: string;
+        message?: string;
+        chunkSize?: number;
+        streamId?: string;
+        allocatedTokens?: StreamContinuationState['allocatedTokens'];
+        retry?: RetryPolicyOptions | false;
+    }): Promise<OperationSubmitResult$1>;
+    private assertNotSubmitted;
+}
+
+/** @internal */
+type CollectionAbout = CollectionAbout$2;
+/** @internal */
+type CollectionTag = CollectionTag$1;
+/** @internal */
+type WireScopeEntry = WireScopeEntry$1;
+/**
+ * Low-level stream append input accepted by `client.stream.append`.
+ * @see https://docs.warmhub.ai/sdk-reference/type-aliases/streamappendinput/
+ */
+type StreamAppendInput = StreamAppendInput$1;
+/**
+ * Low-level stream append result returned by `client.stream.append`.
+ * @see https://docs.warmhub.ai/sdk-reference/type-aliases/streamappendresult/
+ */
+type StreamAppendResult = StreamAppendResult$1;
+/**
+ * Remove an `@vN`, `@HEAD`, or `@ALL` version suffix from a wref.
+ *
+ * @see https://docs.warmhub.ai/data-modeling/wrefs/#version-modifiers
+ */
+declare function normalizeWref(wref: string): string;
+/**
+ * Options for constructing a `WarmHubClient`.
+ * @see https://docs.warmhub.ai/sdk-reference/interfaces/warmhubclientoptions/
+ */
+interface WarmHubClientOptions {
+    /**
+     * Override the WarmHub API URL. Defaults to the public WarmHub API.
+     */
+    apiUrl?: string;
+    /**
+     * Custom `fetch` implementation for non-standard runtimes or tests.
+     */
+    fetch?: typeof globalThis.fetch;
+    /**
+     * Static token or sync/async token provider used for authenticated requests.
+     */
+    accessToken?: AccessTokenProvider;
+    /**
+     * Authentication provider object. Prefer `auth.getToken` when integrating with an existing session system.
+     */
+    auth?: {
+        getToken: () => Promise<string | undefined>;
+    };
+    /**
+     * Control replay of backend function log lines. Defaults to `off`.
+     */
+    functionLogs?: FunctionLogMode;
+}
+/**
+ * Version string for the installed SDK package.
+ * @see https://docs.warmhub.ai/sdk-reference/variables/sdk_version/
+ */
+declare const SDK_VERSION: string;
+/**
+ * Default WarmHub API URL used when a client is constructed without `apiUrl`.
+ * @see https://docs.warmhub.ai/sdk-reference/variables/default_api_url/
+ */
+declare const DEFAULT_API_URL = "https://api.warmhub.ai";
+/** @internal */
+type FunctionLogMode = 'raw' | 'off';
+/** @internal */
+interface RequestEvent {
+    operation: 'query' | 'mutation' | 'action';
+    functionPath: string;
+}
+/** @internal */
+type CoreErrorKind = 'BACKEND' | 'NOT_FOUND' | 'FORBIDDEN' | 'UNAUTHENTICATED' | 'VALIDATION_ERROR' | 'CONFLICT' | 'RATE_LIMITED' | 'CANCELLED' | 'NETWORK';
+/**
+ * Stable SDK error kinds plus backend domain codes that pass through as strings.
+ *
+ * Branch on this (or {@link WarmHubError.kind}) to recover from expected
+ * failures. {@link isRetryable} returns the retryability column verbatim.
+ *
+ * @remarks
+ * Stable kinds (members of `CoreErrorKind`):
+ *
+ * - `BACKEND` — cause: server-side failure that did not carry a more specific domain code (tRPC error data has no `data.warmhub.code`, REST status mapped to the catch-all default — primarily 5xx that lack a body `error.code` — or an SDK transport throw such as a non-OK SSE response); retryable: true; action: retry with backoff and surface the message if it persists; if the underlying error is a deterministic local-adapter failure (e.g. a misconfigured custom `fetch`), fix the adapter rather than retrying; origin: SDK tRPC fallback, `httpStatusToWarmHubCode` default for unmapped HTTP statuses, SSE transport, unknown thrown values inside tRPC paths (custom-`fetch` adapter throws are normalized to `BACKEND` only on tRPC surfaces — on REST and `ping` surfaces the raw error escapes uncaught). REST responses with a parseable body surface as their pass-through `error.code` (typically `INTERNAL_ERROR`), and REST 4xx responses without a body code fall through to the HTTP-status mapping (`NOT_FOUND`, `UNAUTHENTICATED`, `FORBIDDEN`, `CONFLICT`, `VALIDATION_ERROR`, `RATE_LIMITED`), not `BACKEND`.
+ * - `NOT_FOUND` — cause: a referenced entity (repo, org, thing, shape, subscription, credential set, etc.) is missing or the caller cannot see it; retryable: false; action: verify the identifier the call site used (wref, slug, name) and escalate to a caller with read access if the entity should exist; origin: SDK reads across all surfaces, commit pipeline, REST query endpoints
+ * - `FORBIDDEN` — cause: caller is authenticated but lacks the required permission; retryable: false; action: request the missing permission or use a token with broader scope; origin: SDK + REST authorization middleware
+ * - `UNAUTHENTICATED` — cause: missing, expired, or invalid bearer token on a tRPC or REST call; retryable: false; action: mint a fresh PAT and update whichever client option the application wires it into (`auth.getToken` callback or `accessToken` — the SDK does not read `WH_TOKEN` or any env var directly); `wh auth login` only refreshes the CLI's on-disk credentials and does not propagate to a constructed SDK client; for export tickets, remint via the appropriate backend endpoint; origin: SDK + REST auth middleware. Live-ticket SSE auth failures surface as `BACKEND`, not `UNAUTHENTICATED`, because `openSse` maps every non-OK SSE response to `BACKEND`.
+ * - `VALIDATION_ERROR` — cause: input failed schema, shape, or content-length validation; retryable: false; action: fix the offending field per the error message; origin: commit pipeline, SDK writes, client-side content limits
+ * - `CONFLICT` — cause: write collides with current state (concurrent edit, name already in use); retryable: false; action: refetch the current state and reconcile before retrying the write; origin: commit pipeline, repo/org creation. Archived org / repo writes surface as the pass-through code `ARCHIVED`, not `CONFLICT`.
+ * - `RATE_LIMITED` — cause: caller exceeded the per-token or per-org request budget; retryable: true; action: wait {@link WarmHubError.retryAfter} seconds before retrying; origin: REST + tRPC throttling
+ * - `CANCELLED` — cause: caller aborted the request via `AbortSignal`; retryable: true; action: retry only if the caller still wants the result; origin: SDK `AbortError` mapping
+ * - `NETWORK` — cause: connection failed before the server produced a response (DNS, refused, timeout, fetch error); retryable: true; action: check connectivity to the configured `apiUrl` and retry with backoff; origin: SDK `fetchWithAuth` connection-error mapping
+ *
+ * Backend domain codes (e.g. `SHAPE_MISMATCH`, `WREF_UNRESOLVABLE`,
+ * `UNRESOLVED_TOKEN`, `ARCHIVED`, `INTERNAL_ERROR`) pass through unchanged on
+ * `code` / `kind`. Surface the `message` and `hint` verbatim and use the
+ * message to decide whether to retry — most pass-through codes are terminal,
+ * but the backend reuses some codes for transient failures (notably
+ * `INTERNAL_ERROR`, which the webhook-validation path emits with a
+ * `please retry` message when DNS or HEAD probes flake). See the
+ * [HTTP error catalog](/http-api/overview/#response-format)
+ * for HTTP-status mapping and the most common backend codes (the catalog is
+ * not exhaustive — rarer codes such as `UNRESOLVED_TOKEN` and
+ * `WREF_UNRESOLVABLE` are emitted by the backend but not yet tabulated).
+ * @see https://docs.warmhub.ai/sdk-reference/type-aliases/errorkind/
+ */
+type ErrorKind = CoreErrorKind | (string & {});
+/**
+ * Result returned by successful commit submissions.
+ * @see https://docs.warmhub.ai/sdk-reference/type-aliases/operationsubmitresult/
+ */
+type OperationSubmitResult = SubmittedStreamResult;
+/** @internal */
+type ShapeChange = ShapeChangeResult;
+/** @internal */
+type Shape = ShapeGetResult;
+/** @internal */
+type ShapeList = ShapeListResult;
+/**
+ * Result of `client.shape.remove` — confirms the retraction with the new version metadata.
+ * @internal
+ */
+type ShapeRemove = {
+    name: string;
+    operation: 'add' | 'revise' | 'retract';
+    version: number;
+    dataHash: string;
+    removed: true;
+};
+/**
+ * Shape of a subscription record returned from `client.subscription.list`,
+ * `client.subscription.get`, `client.subscription.create`, and
+ * `client.subscription.update`.
+ *
+ * `filterJson` is typed as `unknown`; treat it as an opaque value owned by
+ * the server and pass it through unchanged on updates. `actionContainer`
+ * and `actionContainerConfig` appear on the type as optional fields but are
+ * always returned as `undefined` on reads.
+ *
+ * @internal
+ */
+type SubscriptionInfo = {
+    name: string;
+    kind: 'webhook' | 'cron';
+    active: boolean;
+    shapeName?: string;
+    sourceRepo?: string;
+    filterJson?: unknown;
+    webhookUrl?: string;
+    fallbackWebhookUrl?: string;
+    actionContainerConfig?: unknown;
+    actionContainer?: string;
+    cronConfig?: {
+        cronspec: string;
+        timezone?: string;
+    };
+    allowTraceReentry?: boolean;
+    notifyOnSuccess?: boolean;
+    componentId?: string;
+    credentialSetNames: Array<string>;
+    createdAt: number;
+};
+/**
+ * Array result type for `client.subscription.list`.
+ * @internal
+ */
+type SubscriptionList = SubscriptionInfo[];
+/**
+ * Input shape for `client.subscription.create`. Non-cron subscriptions
+ * require either `shapeName` or `filterJson.shape` (or a shape-lifecycle
+ * `filterJson` such as `{ kind: 'shape' }`).
+ *
+ * @see https://docs.warmhub.ai/subscriptions/creating/
+ */
+type SubscriptionCompatCreateInput = {
+    orgName: string;
+    repoName: string;
+    shapeName?: string;
+    name: string;
+    filterJson?: Record<string, unknown>;
+    kind: 'webhook' | 'cron';
+    webhookUrl?: string;
+    fallbackWebhookUrl?: string;
+    cronConfig?: {
+        cronspec: string;
+        timezone?: string;
+    };
+    allowTraceReentry?: boolean;
+    notifyOnSuccess?: boolean;
+    componentId?: string;
+    sourceRepoRef?: string;
+    workspacePolicy?: never;
+    /** @internal */
+    actionContainer?: string;
+    /** @internal */
+    actionContainerConfig?: unknown;
+};
+/**
+ * Input shape for `client.subscription.update`. `orgName`, `repoName`, and
+ * `name` identify the subscription; all other fields are optional and only
+ * the ones you provide get patched.
+ *
+ * @see https://docs.warmhub.ai/subscriptions/managing/#update-subscription
+ */
+type SubscriptionCompatUpdateInput = {
+    orgName: string;
+    repoName: string;
+    name: string;
+    shapeName?: string;
+    filterJson?: Record<string, unknown>;
+    webhookUrl?: string;
+    fallbackWebhookUrl?: string | null;
+    cronConfig?: {
+        cronspec: string;
+        timezone?: string;
+    };
+    allowTraceReentry?: boolean;
+    notifyOnSuccess?: boolean;
+    /** @internal Back-compat field; not consumed by the backend update mutation. */
+    sourceRepoRef?: string;
+    workspacePolicy?: never;
+    /** @internal */
+    actionContainer?: string;
+    /** @internal */
+    actionContainerConfig?: unknown;
+};
+/** @internal */
+type ActionRunInfo = ActionRun;
+/** @internal */
+type ActionAttemptInfo = ActionAttempt;
+/** @internal */
+type ActionNotificationInfo = ActionNotification;
+/** @internal */
+type ActionLiveFeed = ActionLiveFeedResult;
+/** @internal */
+type ActionLeaseAcquire = {
+    ok: true;
+    reused: boolean;
+} | {
+    ok: false;
+    reason: string;
+};
+/** @internal */
+type ActionLeaseOp = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Result returned by in-place rename mutations: `client.shape.rename` and
+ * `client.thing.rename`. A rename patches the identity field directly and
+ * preserves the existing version history; no new version is created. The
+ * `renamed: true` discriminator distinguishes the success shape from a
+ * rejected request (which throws `WarmHubError`).
+ *
+ * @see https://docs.warmhub.ai/data-modeling/naming-as-navigation/
+ */
+type RenameResult = RenameResult$1;
+/** @internal */
+type ComponentInfo = ComponentSummary;
+/** @internal */
+type ComponentView = ComponentDetail;
+/** @internal */
+type ComponentList = ComponentListResult;
+/** @internal */
+type ComponentListOptions = {
+    limit?: number;
+    cursor?: string;
+};
+/** @internal */
+type ComponentInstallSystemResult = InstallBundledSystemComponentResult;
+type ComponentRegistryInfo = {
+    id: string;
+    ownerOrgName: string;
+    componentName: string;
+    ref: string;
+    isPrivate: boolean;
+    mintedTokens: boolean;
+    sourceUrl?: string;
+    sourceDefaultRef?: string;
+    setupUrl?: string;
+    uninstallUrl?: string;
+    allowedCallbackDomains: string[];
+    credentialSetId?: string;
+    credentialSetName?: string;
+    description?: string;
+    createdAt: number;
+    updatedAt: number;
+};
+type ComponentRegistryList = {
+    items: ComponentRegistryInfo[];
+};
+type ComponentRegistryMutationInput = {
+    isPrivate?: boolean;
+    mintedTokens?: boolean;
+    sourceUrl?: string;
+    sourceDefaultRef?: string;
+    setupUrl?: string;
+    uninstallUrl?: string;
+    allowedCallbackDomains?: string[];
+    credentialSetName?: string;
+    description?: string;
+};
+type ComponentRegistryResolveResult = {
+    sourceUrl: string;
+    sourceDefaultRef?: string;
+    hasSetup: boolean;
+    installId: string;
+};
+type ComponentRegistrySourceDownloadInput = {
+    installRepo: string;
+    ref?: string;
+};
+type ComponentRegistrySourceDownloadResult = {
+    archive: Uint8Array;
+    sourceUrl: string;
+    sourceRef?: string;
+    resolvedSha?: string;
+    componentRef: string;
+    contentType: string;
+};
+type ComponentRegistrySetupCallInput = {
+    installId: string;
+    installRepo: string;
+    ref?: string;
+    resolvedSha?: string;
+};
+type ComponentRegistrySetupCallResult = {
+    ok: boolean;
+    status: number;
+    body?: string;
+    warnings: string[];
+};
+type ComponentRegistryCliCallInput = {
+    installRepo: string;
+    args?: Record<string, unknown>;
+};
+/**
+ * Backend wraps the component-service response in an envelope identical to
+ * `ComponentRegistrySetupCallResult`. The type alias keeps the SDK drift gate
+ * happy (no new *Result shape to audit) and signals that callers should expect
+ * the same `{ ok, status, body?, warnings }` contract — upstream non-2xx
+ * comes back as `{ ok: false, status, body }`, not a thrown `WarmHubError`.
+ */
+type ComponentRegistryCliCallResult = ComponentRegistrySetupCallResult;
+/** @internal */
+type ShapeListOptions = {
+    match?: string;
+    componentId?: string;
+    excludeComponents?: boolean;
+    includeRetracted?: boolean;
+};
+/** @internal */
+type ShapeGetOptions = {
+    includeRetracted?: boolean;
+};
+/** @internal */
+type ShapeCreateOptions = {
+    description?: string;
+};
+/** @internal */
+type ShapeReviseOptions = {
+    description?: string;
+};
+/** @internal */
+interface ShapeHistoryOptions {
+    includeRetracted?: boolean;
+    limit?: number;
+    cursor?: string;
+}
+/** @internal */
+type ShapeHistory = HistoryResult;
+/** @internal */
+type OrgInfo = Org;
+/** @internal */
+type OrgList = OrgListResult;
+/** @internal */
+type OrgMemberInfo = OrgMember;
+/**
+ * Caller's role within an organization. Returned by
+ * `client.org.getCallerRole`, carried as `callerRole` on
+ * `client.org.listMembers` results, and accepted by
+ * `client.org.changeMemberRole` to set a member's role (only owners
+ * may promote to or demote from `'owner'`; the last owner cannot be
+ * demoted). Mirrors `orgRoleSchema` in `@warmhub/backend`; the
+ * static check below blocks any drift between this literal and the
+ * generated copy.
+ *
+ * @see https://docs.warmhub.ai/auth/personal-access-tokens/#available-permissions
+ */
+type OrgRole = 'owner' | 'admin' | 'editor' | 'viewer';
+/** @internal */
+type OrgMemberList = {
+    members: OrgMemberInfo[];
+    callerRole: OrgRole;
+};
+/**
+ * Repository metadata returned by `client.repo.get`, `create`,
+ * `setDescription`, `setVisibility`, `rename`, `archive`, and `unarchive`.
+ * @see https://docs.warmhub.ai/sdk-reference/type-aliases/repoinfo/
+ */
+type RepoInfo = {
+    orgName: string;
+    name: string;
+    description?: string;
+    visibility: 'public' | 'private';
+    archivedAt?: number;
+    createdAt: number;
+};
+/** @internal */
+type RepoList = RepoListResult;
+/** @internal */
+type OrgListOptions = {
+    includeArchived?: boolean;
+};
+/** @internal */
+type OrgListMembersOptions = {
+    pending?: boolean;
+};
+/** @internal */
+type RepoStatsView = RepoStats;
+/** @internal */
+type RepoConfigureStatsView = RepoConfigureStats;
+/** @internal */
+type RepoShapeInstanceCountsView = RepoShapeInstanceCounts;
+/** @internal */
+type RepoStatsBatchResult = RepoStatsBatchResult$1;
+/** @internal */
+type RepoWithStatsInfo = {
+    orgName: string;
+    name: string;
+    description?: string;
+    visibility: 'public' | 'private';
+    archivedAt?: number;
+    createdAt: number;
+    total: number;
+    byKind: {
+        thing: number;
+        assertion: number;
+        shape: number;
+    };
+    lastWriteAt?: number;
+    hasErrors: boolean;
+};
+/** @internal */
+type RepoListPageResult = Page<RepoWithStatsInfo>;
+/** @internal */
+type RepoSort = 'newest' | 'oldest' | 'nameAsc' | 'nameDesc';
+/** @internal */
+type RepoListPageOptions = {
+    limit?: number;
+    cursor?: string;
+    includeArchived?: boolean;
+    search?: string;
+    sort?: RepoSort;
+};
+/** @internal */
+type CurrentUserInfo = {
+    id: string;
+    email: string;
+    firstName?: string;
+    lastName?: string;
+    identityWref: string | null;
+} | null;
+/** @internal */
+type WhoamiScopeEntry = {
+    resource?: string;
+    redactedResource?: true;
+    permissions: string[];
+    allowedMatches?: string[];
+};
+/** @internal */
+type WhoamiInfo = {
+    authenticated: false;
+    error?: string;
+} | {
+    authenticated: true;
+    email: string;
+    userId: string;
+    authMethod: 'interactive' | 'pat';
+    tokenName: string | null;
+    tokenDescription: string | null;
+    scopes: WhoamiScopeEntry[] | null;
+    expiresAt: number | null;
+    identityWref: string | null;
+};
+/** @internal */
+type RepoListOptions = {
+    limit?: number;
+    cursor?: string;
+    includeArchived?: boolean;
+    search?: string;
+    sort?: RepoSort;
+};
+/** @internal */
+type PageRequest = {
+    limit?: number;
+    cursor?: string;
+};
+/**
+ * Cursor page envelope used by paginated SDK methods.
+ *
+ * `Page` is generic over the item type — always supply the type argument when
+ * annotating a variable that holds a page (`Page<ThingItem>`, `Page<RepoInfo>`,
+ * etc.). Using the bare name `Page` fails with `TS2314: Generic type 'Page'
+ * requires 1 type argument(s)`.
+ *
+ * @example
+ * ```ts
+ * import type { Page, ThingItem } from "@warmhub/sdk-ts";
+ *
+ * const page: Page<ThingItem> = await client.thing.head("acme", "world", { limit: 50 });
+ * for (const item of page.items) console.log(item.wref);
+ * if (page.nextCursor) {
+ *   // pass page.nextCursor back as `cursor` on the next call
+ * }
+ * ```
+ * @see https://docs.warmhub.ai/sdk-reference/type-aliases/page/
+ */
+type Page<T> = {
+    items: T[];
+    nextCursor?: string;
+};
+/** @internal */
+type OrgRef = OrgInfo;
+/** @internal */
+type RepoRef = RepoInfo;
+/** @internal */
+type ShapeRef = ShapeChange;
+/** @internal */
+type RepoLocator = {
+    orgName: string;
+    repoName: string;
+};
+/** @internal */
+type ThingItem = {
+    wref: string;
+    name: string;
+    kind: string;
+    shapeName?: string;
+    version: number;
+    createdAt: number;
+    active?: boolean;
+    data?: unknown;
+    aboutWref?: string;
+    [key: string]: unknown;
+};
+/** @internal */
+type ThingHeadOptions = Omit<ThingHeadRequest, 'orgName' | 'repoName'>;
+/** @internal */
+type HeadResult = {
+    items: ThingItem[];
+    nextCursor?: string;
+};
+/** @internal */
+type ThingGet = ThingDetail;
+/**
+ * Full record shape for a single Thing returned by single-record SDK
+ * reads. Returned by `client.thing.get` and `client.thing.resolve`, the
+ * `items[]` element type for `client.thing.getMany`, the base of
+ * `client.thing.graph`, and the return of `client.repo.getReadme` and
+ * `getAgents` (nullable). Identity fields (`wref`, `name`, `kind`,
+ * `shape`/`shapeName`) are always populated. `data` carries the
+ * shape-validated payload when present; `active` is `false` for retracted
+ * reads. The `[key: string]: unknown` index signature is a forward-compat
+ * affordance — current callers should rely on the named fields. Note: list
+ * reads — `client.thing.head`, `query`, and `search` — return a thinner
+ * row shape (no `shape`, `validatedShape`, or `committerWref`); use
+ * `client.thing.get` to hydrate a full `ThingDetail` from a list result.
+ *
+ * @see https://docs.warmhub.ai/data-modeling/things/
+ */
+type ThingDetail = {
+    wref: string;
+    pinnedWref?: string;
+    name: string;
+    kind: string;
+    shape?: string;
+    shapeName?: string;
+    validatedShape?: string;
+    version: number;
+    active: boolean;
+    data?: unknown;
+    aboutWref?: string;
+    committerWref?: string;
+    createdByWref?: string;
+    [key: string]: unknown;
+};
+/** @internal */
+type RefLink = RefsResult$1['items'][number];
+/** @internal */
+type SynthesizedRepoContent = SynthesizedRepoContent$1;
+/** @internal */
+type RepoDescribeResult = RepoDescribeResult$1;
+/** @internal */
+type ThingGraphValue = ThingGraphResult | string | number | boolean | null | ThingGraphValue[];
+/** @internal */
+type ThingGraphResult = ThingDetail & {
+    about?: ThingGraphValue;
+    assertions?: ThingGraphResult[];
+    resolved?: Record<string, ThingGraphValue>;
+    graph?: {
+        depth: number;
+        limit: number;
+        truncated: boolean;
+    };
+};
+/** @internal */
+type ThingHistory = HistoryResult;
+/** @internal */
+type HistoryResult = {
+    thing?: {
+        wref: string;
+        name?: string;
+        kind: string;
+        shapeName?: string;
+    };
+    versions: Array<{
+        version: number;
+        wref: string;
+        operation: 'add' | 'revise' | 'retract';
+        retractReason?: string;
+        active: boolean;
+        createdAt: number;
+        thingName?: string;
+        thingKind?: string;
+        shapeName?: string;
+        data?: unknown;
+        committerWref?: string;
+        createdByWref?: string;
+        [key: string]: unknown;
+    }>;
+    nextCursor?: string;
+};
+/** @internal */
+type ThingHeadRequest = {
+    orgName: string;
+    repoName: string;
+    shape?: string;
+    kind?: string;
+    match?: string;
+    dataMode?: 'full' | 'summary' | 'none';
+    includeRetracted?: boolean;
+    limit?: number;
+    cursor?: string;
+    componentId?: string;
+    excludeComponents?: boolean;
+    excludeInfraShapes?: boolean;
+};
+/** @internal */
+type ThingHead = HeadResult;
+/** @internal */
+type LiveWatchResult = {
+    updates: number;
+};
+/**
+ * Handle returned by live subscription helpers.
+ * @see https://docs.warmhub.ai/sdk-reference/type-aliases/livehandle/
+ */
+type LiveHandle = {
+    close: () => void;
+    closed: Promise<LiveWatchResult>;
+};
+/** @internal */
+type LiveThingHeadOptions = ThingHeadOptions & {
+    signal?: AbortSignal;
+};
+/** @internal */
+type LiveThingHistoryOptions = ThingHistoryOptions & {
+    signal?: AbortSignal;
+};
+/** @internal */
+type LiveSubscriptionLogOptions = ActionLiveFeedOptions & {
+    signal?: AbortSignal;
+};
+/**
+ * Raw SSE invalidation event from a watched repo.
+ *
+ * @see https://docs.warmhub.ai/subscriptions/overview/#how-subscriptions-work
+ */
+type LiveRepoEvent = {
+    topic: 'commit.applied' | 'action.updated';
+    affectedShapes: string[];
+    affectedThings: string[];
+    affectedTargets: string[];
+    hasNewCommit: boolean;
+};
+/** @internal */
+type ActionListRunsOptions = {
+    subscriptionName?: string;
+    status?: 'pending' | 'running' | 'retry_wait' | 'succeeded' | 'failed_terminal' | 'dead_letter';
+    since?: number;
+    limit?: number;
+};
+/** @internal */
+type ActionLiveFeedOptions = {
+    limit?: number;
+    cursor?: string;
+};
+/** @internal */
+type ActionListNotificationsOptions = {
+    since?: number;
+    limit?: number;
+};
+/** @internal */
+type ThingHistoryOptions = {
+    wref?: string;
+    shape?: string;
+    about?: string;
+    includeRetracted?: boolean;
+    resolveCollections?: boolean;
+    match?: string;
+    limit?: number;
+    cursor?: string;
+};
+/** @internal */
+type ThingGetOptions = {
+    includeRetracted?: boolean;
+};
+/** @internal */
+type ThingGraphOptions = {
+    version?: number;
+    depth?: number;
+    limit?: number;
+};
+/**
+ * Result from `client.token.create`. Includes the one-time secret token
+ * value and its metadata — persist the secret immediately, it is only
+ * returned on creation.
+ *
+ * @internal
+ */
+type TokenResult = TokenCreateResult;
+/**
+ * Shape of an access token record returned from `client.token.list` and
+ * `client.token.get`.
+ *
+ * `expiresAt` and `revokedAt` are normalized to `number | null` so
+ * "never expires" / "not revoked" (`null`) is distinguishable from
+ * "expired at timestamp" / "revoked at timestamp" without probing for
+ * `undefined`.
+ *
+ * @internal
+ */
+type TokenInfo = {
+    name: string;
+    description?: string;
+    scopes?: Array<{
+        resource?: string;
+        permissions: Array<string>;
+        allowedMatches?: Array<string>;
+        redactedResource?: true;
+    }>;
+    expiresAt: number | null;
+    revokedAt: number | null;
+    createdAt: number;
+    /**
+     * Default committer identity wref. Null when this PAT has no
+     * associated identity.
+     */
+    committerIdentityWref?: string | null;
+};
+/** @internal */
+type CredentialInfo = {
+    name: string;
+    scope: 'org' | 'repo';
+    description?: string;
+    keyNames: string[];
+    revokedAt?: number;
+    createdAt: number;
+    updatedAt: number;
+};
+/** @internal */
+type CredentialAuditEntry = {
+    timestamp: number;
+    action: string;
+    actorId: string;
+};
+/** @internal */
+type CredentialGrantResult = {
+    granted: boolean;
+    repoName: string;
+};
+/** @internal */
+type CredentialUngrantResult = {
+    ungranted: boolean;
+    repoName: string;
+};
+/** @internal */
+type CredentialKeyMutationResult = CredentialKeyMutationResult$1;
+/** @internal */
+type CredentialDeleteResult = CredentialDeleteResult$1;
+/** @internal */
+type CredentialRevokeResult = CredentialRevokeResult$1;
+/** @internal */
+type SubscriptionBindCredentialsResult = SubscriptionBindCredentialsResult$1;
+/** @internal */
+type SubscriptionUnbindCredentialsResult = SubscriptionUnbindCredentialsResult$1;
+/** @internal */
+type Assertion = ThingDetail & {
+    children: Assertion[];
+};
+/** @internal */
+type AboutResult = {
+    target?: ThingDetail;
+    assertions: Assertion[];
+    nextCursor?: string;
+};
+/** @internal */
+type FilterResult = HeadResult;
+/** @internal */
+type SearchResult = HeadResult;
+/** @internal */
+type RefsResult = RefsResult$1;
+/** @internal */
+type ResolveWrefResult = ThingDetail;
+/** @internal */
+type ThingGetManyResult = ThingGetManyResult$1;
+/** @internal */
+type CountResult = {
+    count: number;
+};
+/** @internal */
+type AboutOptions = {
+    shape?: string;
+    match?: string;
+    includeRetracted?: boolean;
+    depth?: number;
+    resolveCollections?: boolean;
+    limit?: number;
+    cursor?: string;
+};
+/**
+ * Filter options for `client.thing.query`.
+ *
+ * All fields are optional and combine as AND filters; unspecified fields do
+ * not constrain the result set. See [Read Semantics](/sdk/read-semantics/)
+ * for glob `match` behavior, retraction visibility, and pagination rules.
+ *
+ * @see https://docs.warmhub.ai/sdk/read-semantics/
+ */
+type FilterOptions = {
+    /** Filter to records of this shape name (for example `Player`). */
+    shape?: string;
+    /** Filter to records of this kind: `shape`, `thing`, `assertion`, or `collection`. */
+    kind?: string;
+    /** Filter assertions whose `about` target wref matches the supplied value. */
+    about?: string;
+    /** Glob pattern matched against record names (for example `Player/*`). */
+    match?: string;
+    /** Include retracted versions in the result set. */
+    includeRetracted?: boolean;
+    /** Maximum records returned per page. */
+    limit?: number;
+    /** Pagination cursor returned by the prior call. */
+    cursor?: string;
+    /** Filter to records attributed to this component identifier. */
+    componentId?: string;
+    /** Exclude records attributed to any component. */
+    excludeComponents?: boolean;
+    /** Exclude internal infrastructure shapes from the result set. */
+    excludeInfraShapes?: boolean;
+    /** Expand collection targets to their members in the result. */
+    resolveCollections?: boolean;
+};
+/**
+ * Options for `client.thing.search`. Extends {@link FilterOptions} with
+ * search-specific fields.
+ *
+ * When `about` is set or `resolveCollections` is true, result pages may be
+ * sparse — keep paginating until `nextCursor` is absent.
+ *
+ * @see https://docs.warmhub.ai/sdk/read-semantics/#search-modes
+ */
+type SearchOptions = FilterOptions & {
+    /** Restrict the search to assertions about this wref target. */
+    about?: string;
+    /** Search mode: `text` (BM25), `vector` (semantic), or `hybrid` (combined). Defaults to `text`. */
+    mode?: 'text' | 'vector' | 'hybrid';
+    /** Expand collection members in the result; pages may be sparse when set. */
+    resolveCollections?: boolean;
+    /** Exclude internal infrastructure shapes from results. */
+    excludeInfraShapes?: boolean;
+};
+/**
+ * Options for `client.thing.count`. Same filter set as {@link FilterOptions};
+ * pagination fields (`limit`, `cursor`) are ignored.
+ * @see https://docs.warmhub.ai/sdk-reference/type-aliases/countoptions/
+ */
+type CountOptions = FilterOptions;
+/**
+ * Options for `client.thing.refs` — wref-field reverse and forward lookups.
+ *
+ * @see https://docs.warmhub.ai/sdk/read-semantics/#reference-queries
+ */
+type RefsOptions = {
+    /** `inbound` finds records whose wref fields point at the target; `outbound` finds records the target points to. Defaults to `inbound`. */
+    direction?: 'inbound' | 'outbound';
+    /** Narrow an inbound search to a specific wref field path on the source shape. */
+    fieldPath?: string;
+    /** Maximum references returned per page. */
+    limit?: number;
+    /** Pagination cursor returned by the prior call. */
+    cursor?: string;
+};
+/** @internal */
+type PingResult = {
+    ok: boolean;
+    error?: string;
+};
+/** @internal */
+type AccessTokenProvider = string | (() => string | undefined | Promise<string | undefined>);
+/** @internal */
+declare function resolveFunctionLogMode(mode?: FunctionLogMode): FunctionLogMode;
+/** @internal */
+declare function sanitizeErrorMessage(message: string): string;
+/**
+ * Normalized error shape thrown by the WarmHub SDK.
+ *
+ * SDK helpers convert transport, tRPC, validation, and backend failures into
+ * this class so callers can branch on stable `code` / `kind` values and read
+ * optional response metadata such as `status`, `hint`, and `retryAfter`.
+ *
+ * See {@link ErrorKind} for the catalog of stable kinds with cause,
+ * retryability, corrective action, and origin per kind, and
+ * {@link isRetryable} for the canonical retry test.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await client.repo.get('acme', 'world')
+ * } catch (err) {
+ *   if (isWarmHubError(err) && err.kind === 'NOT_FOUND') {
+ *     // handle missing repo
+ *   } else if (isRetryable(err)) {
+ *     // safe to retry (NETWORK, CANCELLED, BACKEND, RATE_LIMITED)
+ *   } else {
+ *     throw err
+ *   }
+ * }
+ * ```
+ * @see https://docs.warmhub.ai/sdk-reference/classes/warmhuberror/
+ */
+declare class WarmHubError extends Error {
+    /**
+     * Stable SDK error code or pass-through backend domain code. Branch on this
+     * (or the alias {@link kind}) to handle expected failure modes.
+     * @see https://docs.warmhub.ai/sdk-reference/classes/warmhuberror/#code
+     */
+    readonly code: string;
+    /**
+     * HTTP status from the failing response when one was available.
+     */
+    readonly status?: number;
+    /**
+     * Optional human-readable hint surfaced by the backend.
+     */
+    readonly hint?: string;
+    /**
+     * Seconds the caller should wait before retrying. Present on `RATE_LIMITED`
+     * responses and other backend signals that carry a Retry-After header.
+     */
+    readonly retryAfter?: number;
+    constructor(code: string, message: string, status?: number, hint?: string, retryAfter?: number);
+    get kind(): ErrorKind;
+}
+/**
+ * Normalize an unknown thrown value into `WarmHubError`.
+ * @see https://docs.warmhub.ai/sdk-reference/functions/towarmhuberror/
+ */
+declare function toWarmHubError(error: unknown): WarmHubError;
+/**
+ * Return whether a thrown value is already a `WarmHubError`.
+ * @see https://docs.warmhub.ai/sdk-reference/functions/iswarmhuberror/
+ */
+declare function isWarmHubError(error: unknown): error is WarmHubError;
+/**
+ * Return whether an error kind is generally safe to retry.
+ *
+ * Returns `true` for these {@link ErrorKind} values:
+ *
+ * - `NETWORK` — transport-level failure during a request (DNS, refused,
+ *   timeout, mid-flight fetch error). Safe to retry GETs and other read
+ *   surfaces; for side-effectful POSTs the request may already have landed
+ *   on the server, so retry only when the surface is idempotent or use an
+ *   idempotency key / state reconciliation before replaying.
+ * - `CANCELLED` — the caller aborted; retry only if the caller still wants
+ *   the result.
+ * - `BACKEND` — generic server-side failure with no specific domain code;
+ *   retry with backoff and surface the message if it persists.
+ * - `RATE_LIMITED` — caller exceeded the budget; retry after the
+ *   {@link WarmHubError.retryAfter} interval.
+ *
+ * All other kinds — including backend pass-through domain codes such as
+ * `SHAPE_MISMATCH` or `WREF_UNRESOLVABLE` — return `false`. This is a
+ * conservative default: for most pass-through codes the caller must fix the
+ * input or escalate, but the backend reuses some codes for transient
+ * conditions (notably `INTERNAL_ERROR` from the webhook-validation path,
+ * whose `message` literally says `please retry`). See the pass-through
+ * paragraph on {@link ErrorKind} — read `WarmHubError.message` before
+ * giving up on a `false` return from this helper.
+ * @see https://docs.warmhub.ai/sdk-reference/functions/isretryable/
+ */
+declare function isRetryable(error: unknown): boolean;
+/**
+ * True if `error` is a connection-level fetch failure — raised before the
+ * server produced a response. Detects both `TypeError('fetch failed')` (Node
+ * undici, browsers) and Bun's native `Error` with a `code` like
+ * `ConnectionRefused` / `ECONNREFUSED`.
+ * @see https://docs.warmhub.ai/sdk-reference/functions/isconnectionerror/
+ */
+declare function isConnectionError(error: unknown): boolean;
+/**
+ * Canonical user-facing message for a connection-level failure. Embeds the
+ * target URL so the user can see which endpoint was unreachable.
+ * @see https://docs.warmhub.ai/sdk-reference/functions/connectionerrormessage/
+ */
+declare function connectionErrorMessage(url: string): string;
+/**
+ * Primary TypeScript client for the WarmHub API.
+ *
+ * The client groups API calls by domain (`repo`, `thing`, `shape`, `commit`,
+ * `subscription`, and related surfaces), applies configured authentication to
+ * every request, and normalizes most transport and backend failures through
+ * `WarmHubError`. Streamed commit writes may instead throw
+ * `PartialStreamSubmissionError` when an append outcome is ambiguous.
+ *
+ * @see https://docs.warmhub.ai/sdk/client/
+ */
+declare class WarmHubClient {
+    /**
+     * The resolved API base URL the client issues requests against. Defaults to
+     * {@link DEFAULT_API_URL} when no `apiUrl` is passed to the constructor.
+     * @see https://docs.warmhub.ai/sdk-reference/classes/warmhubclient/#apiurl
+     */
+    readonly apiUrl: string;
+    private readonly fetchImpl;
+    private readonly accessToken;
+    protected readonly functionLogMode: FunctionLogMode;
+    protected readonly getToken?: () => Promise<string | undefined>;
+    private readonly trpc;
+    /**
+     * Authentication helpers for browser sign-in flows, session checks, and token diagnostics.
+     * @see https://docs.warmhub.ai/sdk-reference/classes/warmhubclient/#auth
+     */
+    readonly auth: {
+        /**
+         * Return the configured browser authentication client ID.
+         *
+         * Use this in browser sign-in flows that need to initialize the configured auth provider before redirecting or opening a login UI.
+         */
+        getClientId: () => Promise<string>;
+        /**
+         * Sync the authenticated identity with WarmHub.
+         *
+         * Call after a browser or server session is established so WarmHub can provision or refresh the corresponding user and personal organization records.
+         */
+        sync: () => Promise<AuthSyncResult>;
+        /**
+         * Return the current authenticated WarmHub user.
+         *
+         * Throws when the request is unauthenticated or the token cannot be resolved.
+         */
+        currentUser: () => Promise<CurrentUserInfo>;
+        /**
+         * Return authentication status, identity details, and token scope diagnostics for the current request.
+         */
+        whoami: () => Promise<WhoamiInfo>;
+    };
+    /**
+     * Lightweight permission checks for UI gating and service-side authorization probes.
+     * @see https://docs.warmhub.ai/sdk-reference/classes/warmhubclient/#access
+     */
+    readonly access: {
+        /**
+         * Check whether the caller has a repo-scoped permission.
+         *
+         * @param permission Permission string such as `repo:read`, `repo:write`, `repo:configure`, or `repo:admin`.
+         */
+        checkRepoPermission: (orgName: string, repoName: string, permission: string) => Promise<boolean>;
+        /**
+         * Check whether the caller has an org-scoped permission.
+         *
+         * @param permission Permission string such as `org:read`, `org:configure`, or `org:admin`.
+         */
+        checkOrgPermission: (orgName: string, permission: string) => Promise<boolean>;
+    };
+    /**
+     * Connectivity and compatibility helpers for checking the configured WarmHub backend.
+     * @see https://docs.warmhub.ai/sdk-reference/classes/warmhubclient/#diagnostics
+     */
+    readonly diagnostics: {
+        /**
+         * Perform a health-check request against the configured backend URL.
+         *
+         * This uses the HTTP health endpoint rather than tRPC, so it is useful for distinguishing connection failures from procedure-level errors.
+         */
+        ping: () => Promise<PingResult>;
+        /**
+         * Return backend API version, minimum supported SDK version, and feature flags.
+         */
+        capabilities: () => Promise<Capabilities>;
+    };
+    /**
+     * Installed component inspection for packages that add shapes, subscriptions, credentials, and seed data to a repository.
+     *
+     * The top-level methods cover per-repo installation queries, bundled system installs, and the registry-backed install pipeline used by `wh component install <org/name>`.
+     * @see https://docs.warmhub.ai/sdk-reference/classes/warmhubclient/#component
+     */
+    readonly component: {
+        /**
+         * List components installed in a repository.
+         *
+         * Pass pagination options when a repository may have many installed components.
+         */
+        list: (orgName: string, repoName: string, opts?: ComponentListOptions) => Promise<ComponentList>;
+        /**
+         * Fetch one installed component by component ID.
+         */
+        get: (orgName: string, repoName: string, componentId: string) => Promise<ComponentView>;
+        /**
+         * Install an allowlisted bundled system component into a repository.
+         */
+        installSystem: (orgName: string, repoName: string, componentId: string) => Promise<ComponentInstallSystemResult>;
+        /**
+         * Registered-component identity and install-pipeline operations.
+         *
+         * This sub-surface drives the backend-mediated install flow that powers `wh component install <org/name>`. It manages registered component identities (`register`, `unregister`, `list`, `view`, `update`) and the install pipeline (`resolve` mints an install id, `downloadSource` fetches the source archive through the backend, `setupCall` dispatches the optional setup callback). Use these when building a custom installer; most callers should run the CLI instead.
+         */
+        registry: {
+            register: (orgName: string, componentName: string, input?: ComponentRegistryMutationInput) => Promise<ComponentRegistryInfo>;
+            unregister: (orgName: string, componentName: string) => Promise<{
+                unregistered: true;
+            }>;
+            list: (orgName: string) => Promise<ComponentRegistryList>;
+            view: (orgName: string, componentName: string) => Promise<ComponentRegistryInfo>;
+            update: (orgName: string, componentName: string, input: ComponentRegistryMutationInput) => Promise<ComponentRegistryInfo>;
+            resolve: (orgName: string, componentName: string, installRepo: string) => Promise<ComponentRegistryResolveResult>;
+            downloadSource: (orgName: string, componentName: string, input: ComponentRegistrySourceDownloadInput) => Promise<ComponentRegistrySourceDownloadResult>;
+            setupCall: (orgName: string, componentName: string, input: ComponentRegistrySetupCallInput) => Promise<ComponentRegistrySetupCallResult>;
+        };
+        /**
+         * Operator-invoked CLI methods (GH-3193).
+         *
+         * `cli.call(orgName, componentName, method, { installRepo, args })`
+         * dispatches a component-declared method via the backend. The backend
+         * loads the install's manifest snapshot, verifies the method exists,
+         * authorizes the operator, signs the request with the install-repo
+         * credential set (HMAC over `${timestamp}.${body}` by default), and
+         * proxies the component service's JSON response back as the envelope's
+         * `body`.
+         *
+         * WarmHub-level failures (component not installed, method not in snapshot,
+         * `ComponentConfig.cliBaseUrl` missing, credentials missing, operator
+         * lacks `requiresPermission`) come back as a thrown `WarmHubError`.
+         * Upstream non-2xx responses do **not** throw — they arrive inside the
+         * envelope as `{ ok: false, status, body }` so the CLI can pretty-print
+         * the component's own error payload.
+         */
+        cli: {
+            call: (orgName: string, componentName: string, method: string, input: ComponentRegistryCliCallInput) => Promise<ComponentRegistryCliCallResult>;
+        };
+    };
+    /**
+     * High-level write surface for submitting WarmHub operations through the commit pipeline.
+     *
+     * @see https://docs.warmhub.ai/sdk/commit-vs-builder/
+     */
+    readonly commit: {
+        /**
+         * Submit one or more operations through WarmHub's commit pipeline.
+         *
+         * This is the primary write path for SDK callers. It streams operations to the backend, preserves server-side per-operation results, supports chunking for large submissions, and can attribute writes to a committer wref or installed component.
+         *
+         * Simple first-chunk transport failures are retried by default. Multi-chunk ambiguous failures are surfaced as `PartialStreamSubmissionError` so callers can inspect repository state before deciding whether to resume or retry. See [Transient Retry](/sdk/transient-retry/) for the full retry and partial-submission rules.
+         *
+         * Writing to an archived organization or repository fails with an `ARCHIVED` error before any operations are applied.
+         *
+         * @param message Optional commit message stored with the submitted operations.
+         * @param operations Add, revise, or retract operations to submit in order.
+         * @param opts.committer Optional wref identifying the actor on whose behalf the write is made. Must be a full wref string like `"Agent/bot-1"` (a thing that already exists), or a cross-repo wref like `"wh:other-org/other-repo/Agent/bot-1"`. Bare names such as `"eval-runner"` are rejected by the backend with a "Thing wref required" error — there is no implicit shape.
+         * @param opts.componentId Attribute writes to an installed component when the caller is allowed to claim it.
+         * @param opts.chunkSize Maximum operations per stream append. Values are clamped by the SDK.
+         * @param opts.skipExisting Return `noop` for add operations whose target already exists.
+         * @param opts.streamId Advanced continuation hook for caller-managed streams.
+         * @param opts.allocatedTokens Advanced continuation hook for `$N` / `#N` token allocation state.
+         * @param opts.retry Retry policy for transient first-chunk failures, or `false` to disable automatic retry.
+         */
+        apply: (orgName: string, repoName: string, message: string | undefined, operations: Operation[], opts?: {
+            committer?: string;
+            componentId?: string;
+            chunkSize?: number;
+            skipExisting?: boolean;
+            streamId?: string;
+            allocatedTokens?: StreamAppendResult$1["allocatedTokens"];
+            retry?: RetryPolicyOptions | false;
+        }) => Promise<OperationSubmitResult>;
+    };
+    /**
+     * Organization management surface for namespaces, membership, roles, and scoped member permissions.
+     * @see https://docs.warmhub.ai/sdk-reference/classes/warmhubclient/#org
+     */
+    readonly org: {
+        /**
+         * Get an organization by name.
+         */
+        get: (orgName: string) => Promise<OrgInfo>;
+        /**
+         * Return the caller's role in an organization, or `null` when the caller is not a member.
+         *
+         * Useful for UI gating before showing organization-level controls.
+         */
+        getCallerRole: (orgName: string) => Promise<OrgRole | null>;
+        /**
+         * List organizations visible to the caller.
+         *
+         * Archived organizations are hidden unless `includeArchived` is set.
+         */
+        list: (opts?: OrgListOptions) => Promise<Page<OrgInfo>>;
+        /**
+         * Create a new organization.
+         *
+         * The description is trimmed and empty strings are ignored. Organization names must avoid reserved public slugs such as `docs`, `api`, `login`, and `warmhub`.
+         *
+         * @param displayName Optional display label. Defaults to the organization name when omitted.
+         */
+        create: (name: string, displayName?: string, description?: string) => Promise<OrgInfo>;
+        /**
+         * Set or clear an organization description.
+         *
+         * Descriptions are trimmed; empty strings clear the stored value.
+         */
+        setDescription: (orgName: string, description?: string) => Promise<OrgInfo>;
+        /**
+         * Update an organization's display name.
+         *
+         * Display names are trimmed; empty or whitespace-only values are rejected.
+         */
+        setDisplayName: (orgName: string, displayName: string) => Promise<OrgInfo>;
+        /**
+         * Rename an organization in place.
+         *
+         * The new slug must satisfy the same naming and reserved-name rules as organization creation.
+         */
+        rename: (orgName: string, newName: string) => Promise<OrgInfo>;
+        /**
+         * Atomic combined update of an organization's display name and/or slug.
+         *
+         * Both writes run in a single backend transaction so a slug conflict cannot leave a partial display-name change behind. Pass at least one of `displayName` or `newName`.
+         */
+        update: (input: {
+            orgName: string;
+            displayName?: string;
+            newName?: string;
+        }) => Promise<OrgInfo>;
+        /**
+         * Add a member to an organization or create a pending invite.
+         *
+         * The role defaults to `editor`. If the email address does not belong to an existing WarmHub user, WarmHub creates a pending invite and attempts to send the invite email asynchronously. Only owners can assign the `owner` role.
+         *
+         * @param role Organization role to assign. Defaults to `editor`.
+         */
+        addMember: (orgName: string, email: string, role?: "owner" | "admin" | "editor" | "viewer") => Promise<OrgMemberInfo>;
+        /**
+         * Remove an active member or revoke a pending invite by email address.
+         */
+        removeMember: (orgName: string, email: string) => Promise<void>;
+        /**
+         * Change a member's organization role.
+         *
+         * Only owners can promote another member to owner or demote an existing owner. WarmHub rejects attempts to remove the final owner.
+         */
+        changeMemberRole: (orgName: string, email: string, role: "owner" | "admin" | "editor" | "viewer") => Promise<OrgMemberInfo>;
+        /**
+         * Replace a member's scoped permission entries.
+         *
+         * Each entry targets either the organization (`acme`) or one repository (`acme/world`) and carries the full desired permission set for that resource. Matching entries replace the role-derived permission set for that resource; include every permission the member should retain.
+         *
+         * Member scope entries share the same wire shape as personal access token scopes, but `allowedMatches` is enforced for PATs only. Member scopes cannot restrict access by thing-name glob.
+         *
+         * @param scopes Scoped permission entries with `resource` and `permissions` fields.
+         */
+        setMemberScopes: (orgName: string, email: string, scopes: WireScopeEntry[]) => Promise<void>;
+        /**
+         * Remove all scoped permission entries from a member.
+         *
+         * After clearing, the member's effective access comes from their organization role only.
+         */
+        clearMemberScopes: (orgName: string, email: string) => Promise<void>;
+        /**
+         * List organization members and pending invites.
+         *
+         * The response includes the caller's current organization role so frontend settings pages can gate owner/admin-only controls without making a second request.
+         *
+         * @param opts.pending When `true`, return only pending invites.
+         */
+        listMembers: (orgName: string, opts?: OrgListMembersOptions) => Promise<OrgMemberList>;
+        /**
+         * Archive an organization, blocking new repositories and membership changes.
+         */
+        archive: (orgName: string) => Promise<OrgInfo>;
+        /**
+         * Unarchive an organization.
+         */
+        unarchive: (orgName: string) => Promise<OrgInfo>;
+    };
+    /**
+     * Repository management surface for lifecycle operations, metadata, statistics, and content documents.
+     *
+     * @see https://docs.warmhub.ai/sdk/repo-stats/
+     */
+    readonly repo: {
+        /**
+         * Get a repository by organization and repository name.
+         */
+        get: (orgName: string, repoName: string) => Promise<RepoInfo>;
+        /**
+         * Return authoritative active-item totals for a single repository.
+         *
+         * The returned `total` is the sum of active shapes, things, and assertions. Use this when billing, quota checks, health reports, or per-shape breakdowns need single-repo stats.
+         *
+         * The per-shape breakdown counts active things by shape; assertions are not included in that map.
+         */
+        getStats: (orgName: string, repoName: string) => Promise<RepoStatsView>;
+        /**
+         * Return active-item totals for up to 100 repositories in one request.
+         *
+         * Use this instead of issuing one `getStats` request per repository when building organization dashboards. Batch entries include the exact `total` for visible repositories; call `getStats` for an individual repository when you need the per-shape map.
+         */
+        getStatsBatch: (orgName: string, repoNames: string[]) => Promise<RepoStatsBatchResult>;
+        /**
+         * Return configuration-surface counts for a repository.
+         *
+         * Currently this reports the number of subscriptions attached to the repository, which is useful before delete or visibility-change flows.
+         */
+        getConfigureStats: (orgName: string, repoName: string) => Promise<RepoConfigureStatsView>;
+        /**
+         * Return per-shape thing and assertion counts for a repository.
+         *
+         * The server computes the totals directly, so callers do not need to page through repository contents to build shape summary UI.
+         */
+        getShapeInstanceCounts: (orgName: string, repoName: string) => Promise<RepoShapeInstanceCountsView>;
+        /**
+         * List repositories in an organization.
+         *
+         * Archived repositories are hidden by default. Search and sort options are applied before pagination.
+         */
+        list: (orgName: string, opts?: RepoListOptions) => Promise<RepoList>;
+        /**
+         * Create a repository inside an organization.
+         *
+         * Repositories are private by default. Descriptions are trimmed and capped by the backend.
+         *
+         * @param visibility `public` or `private`; defaults to `private`.
+         */
+        create: (orgName: string, repoName: string, description?: string, visibility?: RepoVisibility) => Promise<RepoInfo>;
+        /**
+         * Set or clear a repository description.
+         *
+         * Descriptions are trimmed; empty strings clear the stored value.
+         */
+        setDescription: (orgName: string, repoName: string, description?: string) => Promise<RepoInfo>;
+        /**
+         * Set a repository's visibility to `public` or `private`.
+         */
+        setVisibility: (orgName: string, repoName: string, visibility: RepoVisibility) => Promise<RepoInfo>;
+        /**
+         * Rename a repository within its organization.
+         *
+         * The new name must be unused in the organization and follow the same path-segment rules as repository creation.
+         */
+        rename: (orgName: string, repoName: string, newName: string) => Promise<RepoInfo>;
+        /**
+         * Archive a repository, blocking new writes.
+         */
+        archive: (orgName: string, repoName: string) => Promise<RepoInfo>;
+        /**
+         * Unarchive a repository.
+         */
+        unarchive: (orgName: string, repoName: string) => Promise<RepoInfo>;
+        /**
+         * Soft-delete a repository.
+         *
+         * The repository is hidden immediately and scheduled for permanent purge after a 30-day grace window. WarmHub blocks deletion when another repository still has inbound cross-repo references, active subscriptions, or active credential grants that depend on the repository.
+         */
+        delete: (orgName: string, repoName: string) => Promise<{
+            graceExpiresAt: Date;
+        }>;
+        /**
+         * Immediately and irreversibly purge a repository.
+         *
+         * This owner-only operation has no grace window and uses the same inbound-reference guard as `delete`.
+         */
+        hardDelete: (orgName: string, repoName: string) => Promise<void>;
+        /**
+         * List repositories with dashboard-oriented per-repository metadata.
+         *
+         * Each item includes exact active counts, an activity-oriented `lastWriteAt`, and a `hasErrors` flag for terminal action failures.
+         *
+         * Search and sort are applied before pagination, so cursors remain stable across the filtered and ordered list.
+         */
+        listPage: (orgName: string, opts?: RepoListPageOptions) => Promise<RepoListPageResult>;
+        /**
+         * Fetch a repository's `Content/Readme` markdown record.
+         *
+         * The SDK contract allows `null`; current backend behavior returns a synthesized empty stub for repositories that have not committed README content yet. Callers should still null-check defensively.
+         */
+        getReadme: (orgName: string, repoName: string) => Promise<ThingDetail | null>;
+        /**
+         * Generate a README draft from the repository's current shapes, things, and assertions.
+         *
+         * This does not commit the draft. Save returned content with `setReadme` after review.
+         */
+        generateReadme: (orgName: string, repoName: string) => Promise<{
+            content: string;
+        }>;
+        /**
+         * Fetch a repository's `Content/Agents` markdown record.
+         *
+         * The SDK contract allows `null`; current backend behavior mirrors `getReadme` and returns a synthesized empty stub when no AGENTS.md content has been committed yet.
+         */
+        getAgents: (orgName: string, repoName: string) => Promise<ThingDetail | null>;
+        /**
+         * Commit a new `Content/Readme` value.
+         *
+         * The backend adds or revises the content record through the normal commit pipeline.
+         */
+        setReadme: (orgName: string, repoName: string, content: string) => Promise<CommitApplyResult>;
+        /**
+         * Commit a new `Content/Agents` value through the normal commit pipeline.
+         */
+        setAgents: (orgName: string, repoName: string, content: string) => Promise<CommitApplyResult>;
+        /**
+         * Generate an AGENTS.md draft from the repository's current content and schema.
+         *
+         * This does not commit the draft. Save returned content with `setAgents` after review.
+         */
+        generateAgents: (orgName: string, repoName: string) => Promise<{
+            content: string;
+        }>;
+        /**
+         * Fetch the synthesized `Content/LlmsTxt` sitemap for a repository.
+         *
+         * The returned markdown follows the llms.txt convention. Authenticated callers also receive structured reference metadata partitioned by readable outbound and inbound references; cross-org references the caller cannot read are omitted.
+         */
+        getLlmsTxt: (orgName: string, repoName: string) => Promise<SynthesizedRepoContent>;
+    };
+    /**
+     * Shape management surface for schema definitions that validate things and assertions.
+     * @see https://docs.warmhub.ai/sdk-reference/classes/warmhubclient/#shape
+     */
+    readonly shape: {
+        /**
+         * List shape definitions in a repository.
+         *
+         * Options can include retracted shapes, filter by component ownership, or hide component-owned shapes.
+         */
+        list: (orgName: string, repoName: string, opts?: ShapeListOptions) => Promise<ShapeList>;
+        /**
+         * Get one shape definition by name.
+         *
+         * Returns the full shape thing record, with `name`,
+         * `kind: "shape"`, `active`, and a nested `version: { version, operation,
+         * data, dataHash } | null`. This is **not** the same shape as the
+         * shape returned by `create` and `revise`: the change result
+         * is flat (`name`, `operation`, `version: number`, `dataHash`) and does
+         * not carry `data`. To read shape fields, call `get` and read
+         * `result.version?.data` — the change result alone is not enough.
+         *
+         * @param opts.includeRetracted Include a retracted shape instead of treating it as missing.
+         */
+        get: (orgName: string, repoName: string, shapeName: string, opts?: ShapeGetOptions) => Promise<Shape>;
+        /**
+         * Create a shape definition.
+         *
+         * Shape data should describe the fields used to validate things and assertions with that shape.
+         *
+         * Returns `{ name, operation, version, dataHash }`.
+         * The result confirms the write and exposes the new version number, but it
+         * does **not** include the shape data — call `client.shape.get` for the
+         * full shape record (with `kind`, `active`, and nested
+         * `version.data`).
+         *
+         * @param opts.description Optional human-readable shape description.
+         */
+        create: (orgName: string, repoName: string, shapeName: string, fields: Record<string, unknown>, opts?: ShapeCreateOptions) => Promise<ShapeChange>;
+        /**
+         * Revise a shape definition, creating a new shape version.
+         *
+         * Returns `{ name, operation, version, dataHash }`,
+         * the same flat shape as `create`. To read the revised fields back, call
+         * `client.shape.get` for the full shape record.
+         *
+         * @param opts.description Optional human-readable description for the revised shape.
+         */
+        revise: (orgName: string, repoName: string, shapeName: string, newFields: Record<string, unknown>, opts?: ShapeReviseOptions) => Promise<ShapeChange>;
+        /**
+         * Retract a shape definition.
+         */
+        remove: (orgName: string, repoName: string, shapeName: string) => Promise<ShapeRemove>;
+        /**
+         * Rename a shape within a repository.
+         *
+         * The rename is applied in place: the existing shape history is preserved and no new version is created.
+         */
+        rename: (orgName: string, repoName: string, oldName: string, newName: string) => Promise<RenameResult>;
+        /**
+         * Return add, revise, retract, and rename history for a shape.
+         *
+         * Use pagination options for long-lived shapes with many revisions.
+         */
+        history: (orgName: string, repoName: string, name: string, opts?: ShapeHistoryOptions) => Promise<ShapeHistory>;
+    };
+    /**
+     * Webhook and cron subscription management surface scoped to a repository.
+     *
+     * @see https://docs.warmhub.ai/sdk/component-identity/#subscriptions
+     */
+    readonly subscription: {
+        /**
+         * Create a webhook or cron subscription.
+         *
+         * Both subscription kinds require a delivery URL. Webhook subscriptions can also forward events from another repository, allow trace reentry, bind fallback delivery, and opt into success notifications. Component identity is set at creation time and follows the same authority rules as commit writes.
+         *
+         * Webhook subscriptions must specify a shape filter via `shapeName` or `filterJson.shape`, except [shape-lifecycle subscriptions](/subscriptions/creating/#shape-lifecycle-subscriptions) which omit both and rely on a `{ kind: 'shape', ... }` filter.
+         */
+        create: (input: SubscriptionCompatCreateInput) => Promise<SubscriptionInfo>;
+        /**
+         * Get one subscription by name.
+         */
+        get: (orgName: string, repoName: string, name: string) => Promise<SubscriptionInfo>;
+        /**
+         * List subscriptions attached to a repository.
+         */
+        list: (orgName: string, repoName: string) => Promise<SubscriptionList>;
+        /**
+         * Update an existing webhook or cron subscription.
+         *
+         * Use `null` for nullable fields such as fallback webhook URL when you need to clear an existing value.
+         */
+        update: (input: SubscriptionCompatUpdateInput) => Promise<SubscriptionInfo>;
+        /**
+         * Pause a subscription.
+         */
+        pause: (orgName: string, repoName: string, name: string) => Promise<{
+            name: string;
+            active: boolean;
+        }>;
+        /**
+         * Resume a paused subscription.
+         */
+        resume: (orgName: string, repoName: string, name: string) => Promise<{
+            name: string;
+            active: boolean;
+        }>;
+        /**
+         * Delete a subscription.
+         */
+        remove: (orgName: string, repoName: string, name: string) => Promise<{
+            ok: true;
+        }>;
+        /**
+         * Bind a credential set to a subscription for outbound webhook authentication.
+         */
+        bindCredentials: (orgName: string, repoName: string, subscriptionName: string, credentialSetName: string) => Promise<SubscriptionBindCredentialsResult>;
+        /**
+         * Remove the credential set currently bound to a subscription.
+         */
+        unbindCredentials: (orgName: string, repoName: string, subscriptionName: string) => Promise<SubscriptionUnbindCredentialsResult>;
+    };
+    /**
+     * Low-level action lease, delivery, run, and notification primitives for subscription consumers.
+     * @see https://docs.warmhub.ai/sdk-reference/classes/warmhubclient/#action
+     */
+    readonly action: {
+        /**
+         * Acquire an exclusive processing lease for a subscription consumer.
+         *
+         * @param holderId Stable identifier for the process claiming the lease.
+         * @param holderType Kind of consumer claiming the lease.
+         */
+        acquireLease: (orgName: string, repoName: string, subscriptionName: string, holderId: string, holderType: "sdk" | "cli", opts?: {
+            graceMs?: number;
+            ttlMs?: number;
+        }) => Promise<ActionLeaseAcquire>;
+        /**
+         * Extend the TTL for an existing processing lease.
+         */
+        heartbeatLease: (orgName: string, repoName: string, subscriptionName: string, holderId: string, ttlMs?: number) => Promise<ActionLeaseOp>;
+        /**
+         * Release an existing processing lease.
+         */
+        releaseLease: (orgName: string, repoName: string, subscriptionName: string, holderId: string) => Promise<ActionLeaseOp>;
+        /**
+         * Claim one action delivery run for processing.
+         */
+        claimDelivery: (orgName: string, repoName: string, runId: string, holderId: string) => Promise<ActionLeaseOp>;
+        /**
+         * Mark one claimed action delivery run as complete.
+         */
+        completeDelivery: (orgName: string, repoName: string, runId: string, holderId: string) => Promise<ActionLeaseOp>;
+        /**
+         * Query the live delivery feed for a subscription.
+         *
+         * Use this for polling or live-log views that need recent delivery status entries.
+         */
+        liveFeed: (orgName: string, repoName: string, subscriptionName: string, opts?: ActionLiveFeedOptions) => Promise<ActionLiveFeed>;
+        /**
+         * List subscription action runs for a repository.
+         *
+         * The result can be filtered by subscription name, status, and start time.
+         */
+        listRuns: (orgName: string, repoName: string, opts?: ActionListRunsOptions) => Promise<ActionRunInfo[]>;
+        /**
+         * List delivery attempts for one action run.
+         */
+        getRunAttempts: (orgName: string, repoName: string, runId: string) => Promise<ActionAttemptInfo[]>;
+        /**
+         * List repo-scoped action notifications.
+         *
+         * Use `since` or `limit` to bound notification-center style reads.
+         */
+        listNotifications: (orgName: string, repoName: string, opts?: ActionListNotificationsOptions) => Promise<ActionNotificationInfo[]>;
+    };
+    /**
+     * Read surface for things, assertions, histories, references, search, and in-place thing renames.
+     * @see https://docs.warmhub.ai/sdk-reference/classes/warmhubclient/#thing
+     */
+    readonly thing: {
+        /**
+         * Return the current HEAD snapshot for repository contents.
+         *
+         * Filter by shape, kind, assertion target, or glob `match` pattern, and choose the data mode appropriate for the payload size. Component filters can narrow results to component-owned records or hide component infrastructure records.
+         *
+         * Tokenless reads of public repositories have stricter page-size and page-count limits than authenticated reads.
+         */
+        head: (orgName: string, repoName: string, opts?: ThingHeadOptions) => Promise<ThingHead>;
+        /**
+         * Iterate every current HEAD row matching the supplied filters.
+         *
+         * Prefer this over hand-written cursor loops when scanning all matching records. Pass `opts.cursor` to resume from a saved cursor; the iterator advances the cursor automatically after the first request. Pass `limit` to control page size.
+         */
+        headIter: (orgName: string, repoName: string, opts?: ThingHeadOptions) => AsyncIterableIterator<ThingItem>;
+        /**
+         * Materialize every current HEAD row matching the supplied filters.
+         *
+         * Use `max` to guard memory usage; throws a `WarmHubError` with kind `VALIDATION_ERROR` once more than `max` items have actually been observed across pages.
+         */
+        headAll: (orgName: string, repoName: string, opts?: ThingHeadOptions & {
+            max?: number;
+        }) => Promise<ThingItem[]>;
+        /**
+         * Get one thing, assertion, shape, or collection by wref.
+         *
+         * @param version Optional exact version to pin when the wref is not already version-qualified.
+         * @param opts.includeRetracted Include retracted records instead of treating them as missing.
+         */
+        get: (orgName: string, repoName: string, wref: string, version?: number, opts?: ThingGetOptions) => Promise<ThingGet>;
+        /**
+         * Get one record and its embedded assertion, about, and wref graph.
+         *
+         * Depth and limit options bound traversal size. References the caller cannot read remain string wrefs in the returned graph.
+         */
+        graph: (orgName: string, repoName: string, wref: string, opts?: ThingGraphOptions) => Promise<ThingGraphResult>;
+        /**
+         * Batch-fetch wrefs, auto-chunking above the backend's 500-wref transport cap.
+         *
+         * The result preserves duplicate requested wrefs and reports inaccessible or missing refs in `missing` rather than throwing per item. A top-level version pins every unqualified wref; per-wref version pins remain intact.
+         *
+         * @param version Optional exact version to apply to unqualified wrefs.
+         * @param opts.includeRetracted Include retracted records in `items` instead of reporting them in `missing`.
+         * @param opts.chunkSize Maximum wrefs per backend request. Defaults to 500 and is clamped to the backend cap.
+         * @param opts.chunkConcurrency Maximum concurrent chunk requests. Defaults to 1 and is clamped to 8.
+         */
+        getMany: (orgName: string, repoName: string, wrefs: string[], version?: number, opts?: {
+            includeRetracted?: boolean;
+            chunkSize?: number;
+            chunkConcurrency?: number;
+        }) => Promise<ThingGetManyResult>;
+        /**
+         * Return version history and timeline metadata for repository records.
+         *
+         * Provide at least one selector: a concrete wref, a shape filter, or an assertion target. Shape- and target-filtered histories support pagination and optional collection resolution.
+         */
+        history: (orgName: string, repoName: string, opts: ThingHistoryOptions) => Promise<ThingHistory>;
+        /**
+         * Rename a thing within its shape namespace.
+         *
+         * The rename is applied in place: the thing's existing history is preserved and no new version is created.
+         */
+        rename: (orgName: string, repoName: string, shapeName: string, oldName: string, newName: string) => Promise<RenameResult>;
+        /**
+         * Resolve a wref to its current projected record.
+         */
+        resolve: (orgName: string, repoName: string, wref: string) => Promise<ResolveWrefResult>;
+        /**
+         * Return assertions about a thing or collection target.
+         *
+         * Filter by assertion shape or glob `match` pattern, optionally resolve collection targets, and page through large assertion sets with `limit` and `cursor`.
+         *
+         * Returns `{ target?, assertions, nextCursor? }`.
+         * The array is named `assertions`, **not** `items`. This breaks the repo-wide
+         * `items` convention used by `HeadResult`, `FilterResult`, `SearchResult`,
+         * `RefsResult`, and `LogResult`; destructure explicitly to avoid the trap:
+         *
+         * ```ts
+         * const { target, assertions } = await client.thing.about(org, repo, "Location/cave");
+         * for (const a of assertions) console.log(a.wref);
+         * ```
+         *
+         * Any returned subjective-logic opinion tuple `(b, d, u, α)` is a binomial opinion — well-formed only when the underlying assertion expresses a binary proposition. See [Opinions as Separate Assertions](/data-modeling/patterns/#opinions-as-separate-assertions).
+         */
+        about: (orgName: string, repoName: string, wref: string, opts?: AboutOptions) => Promise<AboutResult>;
+        /**
+         * Iterate every assertion about a thing or collection target.
+         *
+         * Prefer this over hand-written cursor loops when scanning all matching assertions. The iterator reads the `assertions` envelope field and advances the cursor automatically; pass `opts.cursor` to resume from a saved cursor and `limit` to control page size.
+         */
+        aboutIter: (orgName: string, repoName: string, wref: string, opts?: AboutOptions) => AsyncIterableIterator<Assertion>;
+        /**
+         * Materialize every assertion about a thing or collection target.
+         *
+         * Use `max` to guard memory usage; throws a `WarmHubError` with kind `VALIDATION_ERROR` once more than `max` assertions have actually been observed across pages.
+         */
+        aboutAll: (orgName: string, repoName: string, wref: string, opts?: AboutOptions & {
+            max?: number;
+        }) => Promise<Assertion[]>;
+        /**
+         * Query repository records by shape, kind, assertion target, text filters, or glob `match` pattern.
+         *
+         * Use this for structured reads where the caller controls filters. For ranked text or vector search, use `thing.search`. For count-only reads, use `thing.count`.
+         */
+        query: (orgName: string, repoName: string, opts?: FilterOptions) => Promise<FilterResult>;
+        /**
+         * Iterate every repository record matching the supplied filters.
+         *
+         * Prefer this over hand-written cursor loops when scanning all matching records. Pass `opts.cursor` to resume from a saved cursor; the iterator advances the cursor automatically after the first request. Pass `limit` to control page size.
+         */
+        queryIter: (orgName: string, repoName: string, opts?: FilterOptions) => AsyncIterableIterator<ThingItem>;
+        /**
+         * Materialize every repository record matching the supplied filters.
+         *
+         * Use `max` to guard memory usage; throws a `WarmHubError` with kind `VALIDATION_ERROR` once more than `max` items have actually been observed across pages.
+         */
+        queryAll: (orgName: string, repoName: string, opts?: FilterOptions & {
+            max?: number;
+        }) => Promise<ThingItem[]>;
+        /**
+         * Search repository records with text, vector, or hybrid mode.
+         *
+         * When searching with an assertion target or collection resolution, pages may be sparse; keep paginating until `nextCursor` is absent.
+         */
+        search: (orgName: string, repoName: string, query: string, opts?: SearchOptions) => Promise<SearchResult>;
+        /**
+         * Count matching repository records without returning record data.
+         */
+        count: (orgName: string, repoName: string, opts?: CountOptions) => Promise<CountResult>;
+        /**
+         * Query wref-typed field references for a record.
+         *
+         * Inbound mode finds records whose wref fields point at the supplied wref. Outbound mode finds records that the supplied record points to. Inbound queries can be narrowed to a field path.
+         */
+        refs: (orgName: string, repoName: string, wref: string, opts?: RefsOptions) => Promise<RefsResult>;
+        /**
+         * Iterate every wref-typed field reference for a record.
+         *
+         * Prefer this over hand-written cursor loops when scanning all matching references. Pass `opts.cursor` to resume from a saved cursor; the iterator advances the cursor automatically after the first request. Pass `limit` to control page size.
+         */
+        refsIter: (orgName: string, repoName: string, wref: string, opts?: RefsOptions) => AsyncIterableIterator<RefLink>;
+        /**
+         * Materialize every wref-typed field reference for a record.
+         *
+         * Use `max` to guard memory usage; throws a `WarmHubError` with kind `VALIDATION_ERROR` once more than `max` refs have actually been observed across pages.
+         */
+        refsAll: (orgName: string, repoName: string, wref: string, opts?: RefsOptions & {
+            max?: number;
+        }) => Promise<RefLink[]>;
+    };
+    /**
+     * Live repository update surface backed by server-sent events.
+     * @see https://docs.warmhub.ai/sdk-reference/classes/warmhubclient/#live
+     */
+    readonly live: {
+        /**
+         * Stream refreshed `thing.head` results whenever the repository changes.
+         *
+         * The SDK re-runs the underlying `thing.head` query after each invalidation and passes the latest snapshot to `onUpdate`.
+         */
+        thingHead: (orgName: string, repoName: string, opts: LiveThingHeadOptions | undefined, onUpdate: (result: ThingHead) => void | Promise<void>) => Promise<LiveHandle>;
+        /**
+         * Stream refreshed history results for a single wref whenever the repository changes.
+         */
+        thingHistory: (orgName: string, repoName: string, opts: LiveThingHistoryOptions, onUpdate: (result: ThingHistory) => void | Promise<void>) => Promise<LiveHandle>;
+        /**
+         * Stream refreshed action live-feed entries for a subscription.
+         */
+        subscriptionLog: (orgName: string, repoName: string, subscriptionName: string, opts: LiveSubscriptionLogOptions | undefined, onUpdate: (result: ActionLiveFeed) => void | Promise<void>) => Promise<LiveHandle>;
+        /**
+         * Subscribe to raw repository invalidation events.
+         *
+         * Unlike the higher-level live helpers, this method does not re-query. It
+         * forwards invalidation metadata such as affected shapes, affected things,
+         * affected assertion targets, and whether the event corresponds to a new
+         * commit.
+         *
+         * @param opts.signal Optional abort signal used to close the SSE stream.
+         * @param onEvent Callback invoked for each repository invalidation event.
+         */
+        subscribe: (orgName: string, repoName: string, opts: {
+            signal?: AbortSignal;
+        } | undefined, onEvent: (event: LiveRepoEvent) => void | Promise<void>) => Promise<LiveHandle>;
+    };
+    /**
+     * Personal access token management for the authenticated user.
+     * @see https://docs.warmhub.ai/sdk-reference/classes/warmhubclient/#token
+     */
+    readonly token: {
+        /**
+         * Create a personal access token for the authenticated user.
+         *
+         * Omit `scopes` to mint a token with the same authority as the calling principal. PATs cannot create or revoke other PATs — token-management permissions are excluded from the grantable set. Server enforces a maximum lifetime; pass an `expiresAt` unix-millis value to clamp earlier.
+         *
+         * See [Personal Access Tokens](/auth/personal-access-tokens/) for scope grammar (resource format, permission strings, `allowedMatches`), rotation, and CI usage.
+         *
+         * @param input.name Caller-chosen identifier for the token, returned in `list`, `get`, and `revoke`.
+         * @param input.scopes Scope entries narrowing the token's authority. Omit for full-principal authority.
+         * @param input.expiresAt Unix epoch milliseconds at which the token expires.
+         * @param input.description Human-readable description shown in token listings.
+         */
+        create: (input: TokenCreateInput) => Promise<TokenResult>;
+        /**
+         * List personal access tokens for the authenticated user.
+         */
+        list: () => Promise<TokenInfo[]>;
+        /**
+         * Get one personal access token by name.
+         */
+        get: (name: string) => Promise<TokenInfo | null>;
+        /**
+         * Revoke a personal access token by name.
+         */
+        revoke: (name: string) => Promise<TokenRevokeResult>;
+    };
+    /**
+     * Low-level stream append surface for callers that already have backend stream operations.
+     * @see https://docs.warmhub.ai/sdk-reference/classes/warmhubclient/#stream
+     */
+    readonly stream: {
+        /**
+         * Append one non-empty chunk of stream operations to a repository.
+         *
+         * Most callers should prefer `commit.apply` or `OperationBuilder`. Use this low-level surface only when you already have stream operations, a stream ID, and any allocated `$N` / `#N` token state you need to continue.
+         */
+        append: (input: StreamAppendInput$1) => Promise<StreamAppendResult$1>;
+    };
+    /**
+     * Credential set management for subscription webhook authentication and component integrations.
+     *
+     * Sets are scoped at creation time. Repo-scoped sets are visible only to the owning repo; org-scoped sets can be granted to multiple repositories in the same organization. Methods that operate on a specific set accept `repoName: string | undefined` — pass the owning repo name for repo-scoped sets or `undefined` for org-scoped sets.
+     * @see https://docs.warmhub.ai/sdk-reference/classes/warmhubclient/#credential
+     */
+    readonly credential: {
+        /**
+         * Create a credential set.
+         *
+         * Credential sets are repo-scoped by default. Org-scoped sets can be granted to multiple repositories in the same organization.
+         */
+        createSet: (orgName: string, repoName: string | undefined, name: string, opts?: {
+            scope?: "org" | "repo";
+            description?: string;
+        }) => Promise<CredentialInfo>;
+        /**
+         * List credential sets visible from a repository.
+         */
+        listSets: (orgName: string, repoName?: string) => Promise<CredentialInfo[]>;
+        /**
+         * Get credential set metadata without secret values.
+         */
+        getSet: (orgName: string, repoName: string | undefined, name: string) => Promise<CredentialInfo>;
+        /**
+         * Set or replace one secret key in a credential set.
+         */
+        setKey: (orgName: string, repoName: string | undefined, setName: string, keyName: string, value: string) => Promise<CredentialKeyMutationResult>;
+        /**
+         * Set or replace multiple secret keys in one request.
+         */
+        setKeys: (orgName: string, repoName: string | undefined, setName: string, secrets: Record<string, string>) => Promise<CredentialKeyMutationResult>;
+        /**
+         * Remove one secret key from a credential set.
+         */
+        unsetKey: (orgName: string, repoName: string | undefined, setName: string, keyName: string) => Promise<CredentialKeyMutationResult>;
+        /**
+         * Delete a credential set and its stored secrets.
+         */
+        deleteSet: (orgName: string, repoName: string | undefined, setName: string) => Promise<CredentialDeleteResult>;
+        /**
+         * List audit entries for a credential set.
+         */
+        listAuditLog: (orgName: string, repoName: string | undefined, setName: string, opts?: {
+            limit?: number;
+        }) => Promise<CredentialAuditEntry[]>;
+        /**
+         * Revoke a credential set so it can no longer be exported or bound.
+         */
+        revokeSet: (orgName: string, repoName: string | undefined, setName: string, opts?: {
+            reason?: string;
+        }) => Promise<CredentialRevokeResult>;
+    };
+    /**
+     * Alias for `credential`.
+     *
+     * @hidden
+     */
+    readonly credentials: {
+        /**
+         * Create a credential set.
+         *
+         * Credential sets are repo-scoped by default. Org-scoped sets can be granted to multiple repositories in the same organization.
+         */
+        createSet: (orgName: string, repoName: string | undefined, name: string, opts?: {
+            scope?: "org" | "repo";
+            description?: string;
+        }) => Promise<CredentialInfo>;
+        /**
+         * List credential sets visible from a repository.
+         */
+        listSets: (orgName: string, repoName?: string) => Promise<CredentialInfo[]>;
+        /**
+         * Get credential set metadata without secret values.
+         */
+        getSet: (orgName: string, repoName: string | undefined, name: string) => Promise<CredentialInfo>;
+        /**
+         * Set or replace one secret key in a credential set.
+         */
+        setKey: (orgName: string, repoName: string | undefined, setName: string, keyName: string, value: string) => Promise<CredentialKeyMutationResult>;
+        /**
+         * Set or replace multiple secret keys in one request.
+         */
+        setKeys: (orgName: string, repoName: string | undefined, setName: string, secrets: Record<string, string>) => Promise<CredentialKeyMutationResult>;
+        /**
+         * Remove one secret key from a credential set.
+         */
+        unsetKey: (orgName: string, repoName: string | undefined, setName: string, keyName: string) => Promise<CredentialKeyMutationResult>;
+        /**
+         * Delete a credential set and its stored secrets.
+         */
+        deleteSet: (orgName: string, repoName: string | undefined, setName: string) => Promise<CredentialDeleteResult>;
+        /**
+         * List audit entries for a credential set.
+         */
+        listAuditLog: (orgName: string, repoName: string | undefined, setName: string, opts?: {
+            limit?: number;
+        }) => Promise<CredentialAuditEntry[]>;
+        /**
+         * Revoke a credential set so it can no longer be exported or bound.
+         */
+        revokeSet: (orgName: string, repoName: string | undefined, setName: string, opts?: {
+            reason?: string;
+        }) => Promise<CredentialRevokeResult>;
+    };
+    /**
+     * Create a WarmHub client.
+     *
+     * Pass either an options object or the legacy `(apiUrl, options)` form. The
+     * options object form is preferred for new code.
+     */
+    constructor(apiUrl?: string, options?: WarmHubClientOptions);
+    constructor(options?: WarmHubClientOptions);
+    /**
+     * Return a new client that shares this client's backend URL and fetch implementation but uses a different access-token provider.
+     * @see https://docs.warmhub.ai/sdk-reference/classes/warmhubclient/#withaccesstoken
+     */
+    withAccessToken(accessToken: AccessTokenProvider): WarmHubClient;
+    /**
+     * Alias for `action`.
+     *
+     * @hidden
+     */
+    readonly actions: {
+        /**
+         * Acquire an exclusive processing lease for a subscription consumer.
+         *
+         * @param holderId Stable identifier for the process claiming the lease.
+         * @param holderType Kind of consumer claiming the lease.
+         */
+        acquireLease: (orgName: string, repoName: string, subscriptionName: string, holderId: string, holderType: "sdk" | "cli", opts?: {
+            graceMs?: number;
+            ttlMs?: number;
+        }) => Promise<ActionLeaseAcquire>;
+        /**
+         * Extend the TTL for an existing processing lease.
+         */
+        heartbeatLease: (orgName: string, repoName: string, subscriptionName: string, holderId: string, ttlMs?: number) => Promise<ActionLeaseOp>;
+        /**
+         * Release an existing processing lease.
+         */
+        releaseLease: (orgName: string, repoName: string, subscriptionName: string, holderId: string) => Promise<ActionLeaseOp>;
+        /**
+         * Claim one action delivery run for processing.
+         */
+        claimDelivery: (orgName: string, repoName: string, runId: string, holderId: string) => Promise<ActionLeaseOp>;
+        /**
+         * Mark one claimed action delivery run as complete.
+         */
+        completeDelivery: (orgName: string, repoName: string, runId: string, holderId: string) => Promise<ActionLeaseOp>;
+        /**
+         * Query the live delivery feed for a subscription.
+         *
+         * Use this for polling or live-log views that need recent delivery status entries.
+         */
+        liveFeed: (orgName: string, repoName: string, subscriptionName: string, opts?: ActionLiveFeedOptions) => Promise<ActionLiveFeed>;
+        /**
+         * List subscription action runs for a repository.
+         *
+         * The result can be filtered by subscription name, status, and start time.
+         */
+        listRuns: (orgName: string, repoName: string, opts?: ActionListRunsOptions) => Promise<ActionRunInfo[]>;
+        /**
+         * List delivery attempts for one action run.
+         */
+        getRunAttempts: (orgName: string, repoName: string, runId: string) => Promise<ActionAttemptInfo[]>;
+        /**
+         * List repo-scoped action notifications.
+         *
+         * Use `since` or `limit` to bound notification-center style reads.
+         */
+        listNotifications: (orgName: string, repoName: string, opts?: ActionListNotificationsOptions) => Promise<ActionNotificationInfo[]>;
+    };
+    private openSse;
+    private fetchWithAuth;
+    private requestResponse;
+    private requestJson;
+    private watchRepoQuery;
+}
+
+export { type AboutOptions, type AboutResult, type AccessTokenProvider, type ActionAttemptInfo, type ActionLeaseAcquire, type ActionLeaseOp, type ActionListNotificationsOptions, type ActionListRunsOptions, type ActionLiveFeed, type ActionLiveFeedOptions, type ActionNotificationInfo, type ActionRunInfo, type AddOp, type AddOperation, type Assertion, CONTENT_FIELD_LIMIT_ERROR, type CollectionAbout, type CollectionTag, type ComponentInfo, type ComponentInstallSystemResult, type ComponentList, type ComponentListOptions, type ComponentView, type CoreErrorKind, type CountOptions, type CountResult, type CredentialAuditEntry, type CredentialDeleteResult, type CredentialGrantResult, type CredentialInfo, type CredentialKeyMutationResult, type CredentialRevokeResult, type CredentialUngrantResult, type CurrentUserInfo, DEFAULT_API_URL, DEFAULT_STREAM_CHUNK_SIZE, type ErrorKind, type FilterOptions, type FilterResult, type FunctionLogMode, type HeadResult, type HistoryResult, type LiveHandle, type LiveRepoEvent, type LiveSubscriptionLogOptions, type LiveThingHeadOptions, type LiveThingHistoryOptions, type LiveWatchResult, MAX_CONTENT_FIELD_BYTES, MAX_STREAM_APPEND_OPERATION_COUNT, type Operation, OperationBuilder, type OperationBuilderClient, type OperationBuilderOp, type OperationBuilderOptions, type OperationSubmitResult, type OrgInfo, type OrgList, type OrgListMembersOptions, type OrgListOptions, type OrgMemberInfo, type OrgMemberList, type OrgRef, type OrgRole, type Page, type PageRequest, PartialStreamSubmissionError, type PingResult, type RefLink, type RefsOptions, type RefsResult, type RenameResult, type RepoConfigureStatsView, type RepoDescribeResult, type RepoInfo, type RepoList, type RepoListOptions, type RepoListPageOptions, type RepoListPageResult, type RepoLocator, type RepoRef, type RepoShapeInstanceCountsView, type RepoSort, type RepoStatsBatchResult, type RepoStatsView, type RepoWithStatsInfo, type RequestEvent, type ResolveWrefResult, type RetractOp, type RetractOperation, type RetryPolicyOptions, type ReviseOp, type ReviseOperation, SDK_VERSION, type SearchOptions, type SearchResult, type Shape, type ShapeChange, type ShapeCreateOptions, type ShapeFields, type ShapeGetOptions, type ShapeHistory, type ShapeHistoryOptions, type ShapeList, type ShapeListOptions, type ShapeRef, type ShapeRemove, type ShapeReviseOptions, type ShapeValidatorResult, type StreamAppendInput, type StreamAppendResult, type StreamContinuationState, type SubscriptionBindCredentialsResult, type SubscriptionCompatCreateInput, type SubscriptionCompatUpdateInput, type SubscriptionInfo, type SubscriptionList, type SubscriptionUnbindCredentialsResult, type SynthesizedRepoContent, type ThingDetail, type ThingGet, type ThingGetManyResult, type ThingGetOptions, type ThingGraphOptions, type ThingGraphResult, type ThingGraphValue, type ThingHead, type ThingHeadOptions, type ThingHeadRequest, type ThingHistory, type ThingHistoryOptions, type ThingItem, type TokenInfo, type TokenResult, type UndeclaredFieldsWarning, type ValidationDiagnostic, type ValidationResult, WarmHubClient, type WarmHubClientOptions, WarmHubError, type WhoamiInfo, type WhoamiScopeEntry, type WireScopeEntry, connectionErrorMessage, contentFieldLimitError, isConnectionError, isRetryable, isWarmHubError, normalizeWref, resolveFunctionLogMode, sanitizeErrorMessage, submitOperationsViaStream, toWarmHubError, validateAgainstShape };