@hasna/skills 0.1.62 → 0.1.63

package/dist/sdk/execution/storage.d.ts

@@ -0,0 +1,158 @@
+/**
+ * Execution storage adapter: where runs, attempts, transitions, and receipts
+ * live. The interface is the contract; the memory and SQLite backends are the
+ * shipped implementations. Every state change a dispatcher or state machine
+ * makes is recorded here — nothing is held only in a process.
+ */
+import type { AttemptReceipt, AttemptRecord, ClaimResult, ExecutionRunRow, ExecutionRunStatus, FrozenAdmission, RunTransitionRecord, TerminalRunStatus } from "./types.js";
+export type { AttemptReceipt, AttemptRecord, ClaimResult, ExecutionRunRow, ExecutionRunStatus, FrozenAdmission, RunTransitionRecord };
+export interface CreateAttemptInput {
+    runId: string;
+    attemptNumber: number;
+}
+export interface ClaimAttemptInput {
+    runId: string;
+    attemptId: string;
+    workerId: string;
+    /** The generation the claimant believes is current. */
+    expectedLeaseGeneration: number;
+}
+/** Result of persisting an attempt launch intent. */
+export type LaunchIntentResult = {
+    ok: true;
+    attempt: AttemptRecord;
+} | {
+    ok: false;
+    reason: "NO_SUCH_ATTEMPT" | "ATTEMPT_TERMINAL" | "RUN_TERMINAL" | "RUN_CANCELLED";
+};
+export interface RunExecutionStore {
+    readonly durable: boolean;
+    admit(admission: FrozenAdmission): Promise<ExecutionRunRow>;
+    getRun(runId: string): Promise<ExecutionRunRow | null>;
+    getRunByKey(tenantId: string, idempotencyKey: string): Promise<ExecutionRunRow | null>;
+    getRunByDigests(input: {
+        tenantId: string;
+        skillId: string;
+        skillVersion: string;
+        bundleDigest: string;
+        inputDigest: string;
+    }): Promise<ExecutionRunRow | null>;
+    listAttempts(runId: string): Promise<AttemptRecord[]>;
+    createAttempt(input: CreateAttemptInput): Promise<AttemptRecord>;
+    claimAttempt(input: ClaimAttemptInput): Promise<ClaimResult>;
+    recordLaunchIntent(input: {
+        runId: string;
+        attemptId: string;
+        clientToken: string;
+        requestDigest: string;
+        startedBy: string;
+    }): Promise<LaunchIntentResult>;
+    recordLaunchState(input: {
+        runId: string;
+        attemptId: string;
+        launchState: AttemptRecord["launchState"];
+        taskId?: string | null;
+    }): Promise<AttemptRecord | null>;
+    recordTransition(transition: RunTransitionRecord): Promise<void>;
+    markAttemptTerminal(runId: string, attemptId: string): Promise<AttemptRecord | null>;
+    writeReceipt(receipt: AttemptReceipt): Promise<AttemptReceipt>;
+    getReceipt(runId: string, attemptId: string): Promise<AttemptReceipt | null>;
+    finalizeRun(runId: string, status: TerminalRunStatus, receiptId: string): Promise<ExecutionRunRow | null>;
+    setRunStatus(runId: string, status: ExecutionRunStatus): Promise<ExecutionRunRow | null>;
+    close?(): Promise<void>;
+}
+declare function newRunId(): string;
+export { newRunId };
+/**
+ * In-memory implementation. Single-process only: the read-then-write claim
+ * path is atomic only because the event loop cannot interleave two synchronous
+ * turns. The SQLite backend is the durable twin; this one exists for tests and
+ * for embedders that deliberately keep the queue in-process.
+ */
+export declare class MemoryRunExecutionStore implements RunExecutionStore {
+    readonly durable = false;
+    private runs;
+    private byKey;
+    private byDigests;
+    private attempts;
+    private transitions;
+    private receipts;
+    admit(admission: FrozenAdmission): Promise<ExecutionRunRow>;
+    getRun(runId: string): Promise<ExecutionRunRow | null>;
+    getRunByKey(tenantId: string, idempotencyKey: string): Promise<ExecutionRunRow | null>;
+    getRunByDigests(input: {
+        tenantId: string;
+        skillId: string;
+        skillVersion: string;
+        bundleDigest: string;
+        inputDigest: string;
+    }): Promise<ExecutionRunRow | null>;
+    listAttempts(runId: string): Promise<AttemptRecord[]>;
+    createAttempt(input: CreateAttemptInput): Promise<AttemptRecord>;
+    claimAttempt(input: ClaimAttemptInput): Promise<ClaimResult>;
+    recordLaunchIntent(input: {
+        runId: string;
+        attemptId: string;
+        clientToken: string;
+        requestDigest: string;
+        startedBy: string;
+    }): Promise<LaunchIntentResult>;
+    recordLaunchState(input: {
+        runId: string;
+        attemptId: string;
+        launchState: AttemptRecord["launchState"];
+        taskId?: string | null;
+    }): Promise<AttemptRecord | null>;
+    recordTransition(transition: RunTransitionRecord): Promise<void>;
+    markAttemptTerminal(runId: string, attemptId: string): Promise<AttemptRecord | null>;
+    writeReceipt(receipt: AttemptReceipt): Promise<AttemptReceipt>;
+    getReceipt(runId: string, attemptId: string): Promise<AttemptReceipt | null>;
+    finalizeRun(runId: string, status: TerminalRunStatus, receiptId: string): Promise<ExecutionRunRow | null>;
+    setRunStatus(runId: string, status: ExecutionRunStatus): Promise<ExecutionRunRow | null>;
+}
+/**
+ * SQLite backend. `:memory:` is supported for tests; a path gives the durable
+ * twin. All writes go through a single connection, so the CAS claim and the
+ * launch-intent write are atomic by construction — the same property the
+ * postgres backend must provide through row locking.
+ */
+export declare class SqliteRunExecutionStore implements RunExecutionStore {
+    readonly durable = true;
+    private db;
+    constructor(path?: string);
+    admit(admission: FrozenAdmission): Promise<ExecutionRunRow>;
+    getRun(runId: string): Promise<ExecutionRunRow | null>;
+    getRunByKey(tenantId: string, idempotencyKey: string): Promise<ExecutionRunRow | null>;
+    getRunByDigests(input: {
+        tenantId: string;
+        skillId: string;
+        skillVersion: string;
+        bundleDigest: string;
+        inputDigest: string;
+    }): Promise<ExecutionRunRow | null>;
+    listAttempts(runId: string): Promise<AttemptRecord[]>;
+    createAttempt(input: CreateAttemptInput): Promise<AttemptRecord>;
+    claimAttempt(input: ClaimAttemptInput): Promise<ClaimResult>;
+    recordLaunchIntent(input: {
+        runId: string;
+        attemptId: string;
+        clientToken: string;
+        requestDigest: string;
+        startedBy: string;
+    }): Promise<LaunchIntentResult>;
+    recordLaunchState(input: {
+        runId: string;
+        attemptId: string;
+        launchState: AttemptRecord["launchState"];
+        taskId?: string | null;
+    }): Promise<AttemptRecord | null>;
+    recordTransition(transition: RunTransitionRecord): Promise<void>;
+    markAttemptTerminal(runId: string, attemptId: string): Promise<AttemptRecord | null>;
+    writeReceipt(receipt: AttemptReceipt): Promise<AttemptReceipt>;
+    getReceipt(runId: string, attemptId: string): Promise<AttemptReceipt | null>;
+    finalizeRun(runId: string, status: TerminalRunStatus, receiptId: string): Promise<ExecutionRunRow | null>;
+    setRunStatus(runId: string, status: ExecutionRunStatus): Promise<ExecutionRunRow | null>;
+    close(): Promise<void>;
+    private readRun;
+    private readAttempt;
+}

package/dist/sdk/execution/types.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Core types for the cloud-run execution machinery.
+ *
+ * A run is admitted once under a stable `run_id`, with every input that must
+ * not change between attempts frozen into the admission record: tenant, skill
+ * id + version, canonical bundle digest, runtime-image digest, input digest,
+ * and the policy + limits the run is executed under. Retries keep the run_id
+ * and increment the attempt_id and lease_generation.
+ */
+/** Protocol version shared with the sibling sdk run protocol. */
+export declare const EXECUTION_PROTOCOL_VERSION: 1;
+/** Lifecycle states of the execution state machine. */
+export type ExecutionRunStatus = "admitted" | "leased" | "running" | "succeeded" | "failed" | "cancelled";
+/** Terminal states of the state machine. */
+export type TerminalRunStatus = "succeeded" | "failed" | "cancelled";
+/** States a run may still move out of. */
+export type ActiveRunStatus = "admitted" | "leased" | "running";
+/** RunTimes allowed by the image profile registry. */
+export type RuntimeName = "bun" | "node" | "python3";
+export interface RunPolicy {
+    /** deny-by-default egress; "allowlist" opens a bounded broker route. */
+    egress: "deny" | "allowlist";
+    /** Hosts reachable when egress is "allowlist". */
+    egressAllowlist: string[];
+    /** Network byte cap applied on the allowlisted broker route. */
+    networkByteCap: number;
+}
+export interface RunLimits {
+    maxDurationMs: number;
+    maxMemoryMb: number;
+    /** ECS CPU units (256 = 0.25 vCPU). */
+    maxCpuUnits: number;
+    maxArtifactsBytes: number;
+    maxConcurrency: number;
+}
+/** Everything frozen at admission under one stable run_id. */
+export interface FrozenAdmission {
+    contractVersion: number;
+    runId: string;
+    tenantId: string;
+    skillId: string;
+    skillVersion: string;
+    /** Canonical sha256 of the skill bundle, fetched by digest at run time. */
+    bundleDigest: string;
+    /** Pinned runtime-image digest resolved from the image profile registry. */
+    runtimeImageDigest: string;
+    /** Prebuilt dependency layer tag, when the manifest's system_deps are allowlisted. */
+    dependencyLayerTag: string | null;
+    /** sha256 of the canonical serialization of the run input. */
+    inputDigest: string;
+    runtime: RuntimeName;
+    policy: RunPolicy;
+    limits: RunLimits;
+    idempotencyKey: string;
+    createdAt: string;
+}
+/** A claim attempt, with its fencing token. */
+export interface AttemptRecord {
+    runId: string;
+    /** Stable per-attempt id; retries keep run_id and mint a new attempt id. */
+    attemptId: string;
+    attemptNumber: number;
+    /** Fencing counter; every successful CAS claim increments it by one. */
+    leaseGeneration: number;
+    workerId: string | null;
+    claimedAt: string | null;
+    status: AttemptStatus;
+    /** Deterministic ECS clientToken derived from (run_id, attempt_id). */
+    clientToken: string | null;
+    /** Immutable digest of the frozen request this attempt launches. */
+    requestDigest: string | null;
+    /** ECS task arn, once the launch is confirmed. */
+    taskId: string | null;
+    launchState: AttemptLaunchState;
+    /** Started-by token used to reconcile an ambiguous launch. */
+    startedBy: string | null;
+}
+export type AttemptStatus = "pending" | "leased" | "terminal";
+export type AttemptLaunchState = "unlaunched" | "launching" | "ambiguous" | "absent" | "launched" | "terminal";
+/** Why a CAS claim was refused. */
+export type ClaimFailure = "NO_SUCH_ATTEMPT" | "STALE_GENERATION" | "ATTEMPT_TERMINAL" | "RUN_TERMINAL" | "RUN_CANCELLED";
+export type ClaimResult = {
+    ok: true;
+    attempt: AttemptRecord;
+    leaseGeneration: number;
+} | {
+    ok: false;
+    reason: ClaimFailure;
+};
+/** One recorded state transition, appended through the storage adapter. */
+export interface RunTransitionRecord {
+    runId: string;
+    attemptId: string | null;
+    from: ExecutionRunStatus;
+    to: ExecutionRunStatus;
+    at: string;
+}
+/** Immutable per-attempt receipt. Written once at launch, finalized once. */
+export interface AttemptReceipt {
+    runId: string;
+    attemptId: string;
+    leaseGeneration: number;
+    clientToken: string;
+    requestDigest: string;
+    startedBy: string;
+    taskId: string | null;
+    launchedAt: string;
+    completedAt: string | null;
+    runtimeImageDigest: string;
+    bundleDigest: string;
+    dependencyLayerTag: string | null;
+    policy: RunPolicy;
+    limits: RunLimits;
+    exitCode: number | null;
+    status: TerminalRunStatus | null;
+    artifactPointers: string[];
+    logPointers: string[];
+    costCents: number | null;
+}
+export interface ExecutionRunRow {
+    admission: FrozenAdmission;
+    status: ExecutionRunStatus;
+    currentAttemptId: string | null;
+    terminalReceiptId: string | null;
+    updatedAt: string;
+}
+export declare function isTerminalStatus(status: ExecutionRunStatus): status is TerminalRunStatus;
+export declare function isActiveStatus(status: ExecutionRunStatus): status is ActiveRunStatus;
+/** Canonical serialization: stable key order, stable separators, no whitespace. */
+export declare function canonicalJson(value: unknown): string;

package/dist/sdk/executor.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Executor seam: what actually runs a claimed skill run.
+ *
+ * The interface is the contract an embedder supplies an executor against. The current
+ * implementation is the provider-free deterministic handler the shipped worker runs
+ * (src/server/handlers.ts) — same logs, same artifacts, same terminal transitions.
+ */
+import { ArtifactStorage } from "../server/artifact-storage.js";
+import { executeRun } from "../server/handlers.js";
+import type { ServerRunRecord, SkillsProductStore } from "../server/types.js";
+/** Executes one claimed run to a terminal state. */
+export interface RunExecutor {
+    execute(store: SkillsProductStore, run: ServerRunRecord, storage?: ArtifactStorage): Promise<ServerRunRecord>;
+}
+/** Current implementation: the shipped deterministic handler, unchanged. */
+export declare const localRunExecutor: RunExecutor;
+export { executeRun };

package/dist/sdk/governance-store.d.ts

@@ -0,0 +1,156 @@
+/**
+ * GovernanceStore: the append-only lifecycle ledger + spend ledger behind the
+ * governance services.
+ *
+ * Deliberately a SEPARATE seam from SkillsProductStore: the product seam is a
+ * published contract third parties implement, and bolting receipt/reservation
+ * methods onto it would make every implementation carry controls only the
+ * hosted path needs. This seam owns four things:
+ *
+ *   - skills_lifecycle_receipts: append-only. There is no update or delete
+ *     surface here - a receipt is a fact that happened.
+ *   - skills_credit_reservations: reserve before dispatch, reconcile once at
+ *     terminal state.
+ *   - artifact row deletion / quarantine key rewrite, so the expiry sweep and
+ *     cancellation can retire rows without growing the product seam.
+ *   - ceiling reads: active run count and monthly spend per org.
+ */
+import { Database } from "bun:sqlite";
+import type { ServerArtifact } from "../server/types.js";
+export type ReceiptKind = "delete" | "quarantine" | "cancel";
+export interface LifecycleReceipt {
+    id: string;
+    kind: ReceiptKind;
+    orgId: string;
+    runId: string;
+    artifactId?: string;
+    /** Stable, non-secret identity of the requester: a principal email, an api key id, a worker id. */
+    requestedBy: string;
+    metadata: Record<string, unknown>;
+    createdAt: string;
+}
+export type ReservationStatus = "reserved" | "charged" | "released";
+export interface CreditReservation {
+    id: string;
+    orgId: string;
+    runId: string;
+    estimatedCents: number;
+    actualCents?: number;
+    status: ReservationStatus;
+    createdAt: string;
+    reconciledAt?: string;
+}
+export interface GovernanceStore {
+    readonly backend: string;
+    close?(): Promise<void>;
+    appendReceipt(receipt: Omit<LifecycleReceipt, "id" | "createdAt">): Promise<LifecycleReceipt>;
+    listReceipts(orgId: string, runId: string): Promise<LifecycleReceipt[]>;
+    createReservation(input: {
+        orgId: string;
+        runId: string;
+        estimatedCents: number;
+    }): Promise<CreditReservation>;
+    reservationsForRun(orgId: string, runId: string): Promise<CreditReservation[]>;
+    reconcileReservation(reservationId: string, actualCents: number, status: "charged" | "released"): Promise<CreditReservation | null>;
+    /** Sum of cost_cents of runs created in the given calendar month (YYYY-MM), plus un-reconciled reservations. */
+    monthlySpendCents(orgId: string, monthPrefix: string): Promise<number>;
+    /** Runs currently admitted (queued/running/cancelling), the concurrency ceiling's subject. */
+    activeRunCount(orgId: string): Promise<number>;
+    /** Artifacts whose expires_at is at or before `nowIso`, the expiry sweep's subjects. */
+    listExpiredArtifacts(nowIso: string): Promise<ServerArtifact[]>;
+    /** Permanently remove an artifact row. The object deletion is the storage's job. */
+    deleteArtifactRow(artifactId: string, orgId: string): Promise<boolean>;
+    /** Rewrite an artifact's storage key (quarantine move); row and object move together. */
+    updateArtifactStorageKey(artifactId: string, orgId: string, storageKey: string): Promise<boolean>;
+}
+export declare function receiptId(): string;
+export declare function reservationId(): string;
+/** In-memory governance store: parity for tests, non-durable like its product twin. */
+export declare class MemoryGovernanceStore implements GovernanceStore {
+    readonly backend = "memory";
+    private receipts;
+    private reservations;
+    private artifacts;
+    private runs;
+    constructor(seed?: {
+        runs?: Array<{
+            orgId: string;
+            costCents: number;
+            status: string;
+            createdAt: string;
+        }>;
+    });
+    appendReceipt(receipt: Omit<LifecycleReceipt, "id" | "createdAt">): Promise<LifecycleReceipt>;
+    listReceipts(orgId: string, runId: string): Promise<LifecycleReceipt[]>;
+    createReservation(input: {
+        orgId: string;
+        runId: string;
+        estimatedCents: number;
+    }): Promise<CreditReservation>;
+    reservationsForRun(orgId: string, runId: string): Promise<CreditReservation[]>;
+    reconcileReservation(reservationId: string, actualCents: number, status: "charged" | "released"): Promise<CreditReservation | null>;
+    monthlySpendCents(orgId: string, monthPrefix: string): Promise<number>;
+    activeRunCount(orgId: string): Promise<number>;
+    listExpiredArtifacts(at: string): Promise<ServerArtifact[]>;
+    deleteArtifactRow(artifactId: string, orgId: string): Promise<boolean>;
+    updateArtifactStorageKey(artifactId: string, orgId: string, storageKey: string): Promise<boolean>;
+    /** Test hook: seed artifacts and runs directly. */
+    seedArtifacts(artifacts: ServerArtifact[]): void;
+    seedRuns(runs: Array<{
+        orgId: string;
+        costCents: number;
+        status: string;
+        createdAt: string;
+    }>): void;
+}
+/** SQLite governance store: a second connection to the same database file, WAL-safe. */
+export declare class SqliteGovernanceStore implements GovernanceStore {
+    readonly backend = "sqlite";
+    private db;
+    private closed;
+    constructor(path?: string, options?: {
+        migrate?: boolean;
+    });
+    close(): Promise<void>;
+    get database(): Database;
+    appendReceipt(receipt: Omit<LifecycleReceipt, "id" | "createdAt">): Promise<LifecycleReceipt>;
+    listReceipts(orgId: string, runId: string): Promise<LifecycleReceipt[]>;
+    createReservation(input: {
+        orgId: string;
+        runId: string;
+        estimatedCents: number;
+    }): Promise<CreditReservation>;
+    reservationsForRun(orgId: string, runId: string): Promise<CreditReservation[]>;
+    reconcileReservation(reservationId: string, actualCents: number, status: "charged" | "released"): Promise<CreditReservation | null>;
+    monthlySpendCents(orgId: string, monthPrefix: string): Promise<number>;
+    activeRunCount(orgId: string): Promise<number>;
+    listExpiredArtifacts(at: string): Promise<ServerArtifact[]>;
+    deleteArtifactRow(artifactId: string, orgId: string): Promise<boolean>;
+    updateArtifactStorageKey(artifactId: string, orgId: string, storageKey: string): Promise<boolean>;
+    private reservationFrom;
+}
+/** Postgres governance store. Same semantics as the SQLite twin; tenant context via set_config. */
+export declare class PostgresGovernanceStore implements GovernanceStore {
+    readonly backend = "postgres";
+    private sql;
+    constructor(databaseUrl: string);
+    close(): Promise<void>;
+    private withContext;
+    appendReceipt(receipt: Omit<LifecycleReceipt, "id" | "createdAt">): Promise<LifecycleReceipt>;
+    listReceipts(orgId: string, runId: string): Promise<LifecycleReceipt[]>;
+    createReservation(input: {
+        orgId: string;
+        runId: string;
+        estimatedCents: number;
+    }): Promise<CreditReservation>;
+    reservationsForRun(orgId: string, runId: string): Promise<CreditReservation[]>;
+    reconcileReservation(reservationId: string, actualCents: number, status: "charged" | "released"): Promise<CreditReservation | null>;
+    monthlySpendCents(orgId: string, monthPrefix: string): Promise<number>;
+    activeRunCount(orgId: string): Promise<number>;
+    listExpiredArtifacts(at: string): Promise<ServerArtifact[]>;
+    deleteArtifactRow(artifactId: string, orgId: string): Promise<boolean>;
+    updateArtifactStorageKey(artifactId: string, orgId: string, storageKey: string): Promise<boolean>;
+    private reservationFrom;
+}
+/** Open the governance store matching a database target: sqlite (default) or postgres. */
+export declare function createGovernanceStore(databaseUrl?: string): Promise<GovernanceStore>;

package/dist/sdk/governance.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Run outputs governance: shared types, defaults, and errors.
+ *
+ * Every control here is FINITE and enforceable: a visibility flag persisted at
+ * write time (never inferred at read), hard byte limits checked before
+ * persistence, expiry timestamps computed from a configured TTL and swept by
+ * the expiry service, and ceilings checked at admission. The defaults are the
+ * sane starting point the plan calls for (10MB per output, 100MB per run,
+ * 30-day TTLs, $50/month ceiling); an embedder overrides them explicitly and
+ * every override is still a finite number.
+ */
+import type { ServerRunRecord } from "../server/types.js";
+/** Output visibility. Runs' outputs are PRIVATE by default; "public" is an explicit opt-in. */
+export type OutputVisibility = "private" | "public";
+/** Resource envelope a run requests at admission, checked against ceilings. */
+export interface RunQuota {
+    /** vCPU, fractional allowed. */
+    cpu: number;
+    memoryMB: number;
+    durationSeconds: number;
+    networkMB: number;
+    artifactBytes: number;
+}
+export interface OutputGovernanceConfig {
+    /** Visibility stamped on every artifact at write time. Default "private". */
+    defaultVisibility?: OutputVisibility;
+    /**
+     * Pre-persistence redaction patterns applied to run output before it is
+     * stored. Configurable; the default is the shipped credential patterns.
+     */
+    redactPatterns?: RegExp[];
+    /** Hard per-output byte cap. Default 10MB. */
+    perOutputBytes?: number;
+    /** Hard per-run total byte cap (all outputs of one run). Default 100MB. */
+    perRunTotalBytes?: number;
+    /**
+     * Finite retention in seconds. Every artifact gets expiresAt =
+     * createdAt + ttl at write time. Default 30 days.
+     */
+    artifactTtlSeconds?: number;
+}
+export interface SpendCeilings {
+    /** Per-run resource envelope; any quota above it is refused at admission. */
+    perRun: RunQuota;
+    /** Max concurrently admitted (queued/running/cancelling) runs per org. */
+    concurrency: number;
+    /** Max estimated spend per org per calendar month, in cents. Default $50. */
+    monthlyTotalCents: number;
+}
+export declare const DEFAULT_OUTPUT_GOVERNANCE: Required<OutputGovernanceConfig>;
+export declare const DEFAULT_RUN_QUOTA: RunQuota;
+export declare const DEFAULT_SPEND_CEILINGS: SpendCeilings;
+/** Machine-readable governance failure codes. Tests assert on these exactly. */
+export declare const GOVERNANCE_ERROR_CODES: {
+    /** An output exceeded the per-output byte cap at write time. */
+    readonly ARTIFACT_LIMIT_EXCEEDED: "ARTIFACT_LIMIT_EXCEEDED";
+    /** A run's accumulated outputs exceeded the per-run byte cap at write time. */
+    readonly RUN_ARTIFACT_TOTAL_EXCEEDED: "RUN_ARTIFACT_TOTAL_EXCEEDED";
+    /** Admission refused: a spend ceiling (per-run, concurrency, or monthly) is exhausted. */
+    readonly RUN_BUDGET_EXHAUSTED: "RUN_BUDGET_EXHAUSTED";
+    /** A fenced transition carried a stale lease_generation. */
+    readonly STALE_LEASE_GENERATION: "STALE_LEASE_GENERATION";
+    /** Cancellation was requested on a store that cannot fence generations. */
+    readonly FENCING_UNSUPPORTED: "FENCING_UNSUPPORTED";
+    /** An event payload carried content that must never enter @hasna/events. */
+    readonly EVENT_PAYLOAD_REJECTED: "EVENT_PAYLOAD_REJECTED";
+    /** Offline local run refused: the skill is not in the verified cache. */
+    readonly SKILL_UNAVAILABLE_OFFLINE: "SKILL_UNAVAILABLE_OFFLINE";
+    /** A remote run was attempted locally; the client never silently falls back. */
+    readonly REMOTE_REQUIRED: "REMOTE_REQUIRED";
+};
+export type GovernanceErrorCode = (typeof GOVERNANCE_ERROR_CODES)[keyof typeof GOVERNANCE_ERROR_CODES];
+/** Every governance failure is one typed error with a stable code. */
+export declare class GovernanceError extends Error {
+    readonly code: GovernanceErrorCode;
+    /** The ceiling or gate that refused, e.g. "monthly", "cpu", "ARTIFACT_LIMIT_EXCEEDED". */
+    readonly gate: string;
+    /** Present when the code is RUN_BUDGET_EXHAUSTED: which ceiling exhausted. */
+    readonly ceiling?: string;
+    constructor(code: GovernanceErrorCode, message: string, options?: {
+        gate?: string;
+        ceiling?: string;
+    });
+}
+/** Stable identity for a run's lifecycle: the pointers every receipt and event carries. */
+export interface RunPointers {
+    runId: string;
+    attemptId: string;
+    leaseGeneration: number;
+    correlationId?: string;
+}
+export declare function runPointersOf(run: Pick<ServerRunRecord, "id" | "correlationId" | "leaseGeneration">): RunPointers;

package/dist/sdk/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @hasna/skills/sdk — the import surface for embedding the skills service.
+ *
+ * Server/router, registry + version service, run protocol + atomic run services,
+ * dispatcher adapters, executor, storage/object-store seams, the cloud-run
+ * execution lane (admission, CAS leases, ECS reconciliation), and the run
+ * governance controls (privacy, retention, tenancy, cancellation, events,
+ * spend ceilings, offline fail-closed). Every module re-exports the shipped
+ * implementation with the interface as the contract; nothing here duplicates
+ * business logic. The SaaS control plane imports this package directly and
+ * never spawns the server binaries.
+ */
+export * from "./server.js";
+export * from "./registry.js";
+export * from "./runs.js";
+export * from "./dispatcher.js";
+export * from "./executor.js";
+export * from "./storage.js";
+export * from "./governance.js";
+export * from "./governance-store.js";
+export * from "./outputs.js";
+export * from "./cancel.js";
+export * from "./events.js";
+export * from "./spend.js";
+export * from "./offline.js";
+export * from "./execution/index.js";