@hasna/skills 0.1.62 → 0.1.63

package/dist/sdk/offline.d.ts

@@ -0,0 +1,16 @@
+export interface OfflineGateOptions {
+    /** The configured API origin; present means "this client is hosted". */
+    apiUrl?: string;
+    /** True when the skill is present in the verified local cache. */
+    isCached: (skill: string) => boolean | Promise<boolean>;
+    /** True when the skill's contract requires network. */
+    isNetworkRequired?: (skill: string) => boolean | Promise<boolean>;
+}
+export interface OfflineGate {
+    /**
+     * Decide whether a run may execute locally. Throws GovernanceError with the
+     * exact code (REMOTE_REQUIRED | SKILL_UNAVAILABLE_OFFLINE) when it may not.
+     */
+    assertCanRunLocal(skill: string): Promise<void>;
+}
+export declare function createOfflineGate(options: OfflineGateOptions): OfflineGate;

package/dist/sdk/outputs.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Outputs governance: default-private visibility, pre-persistence redaction,
+ * hard size limits, finite TTLs, and immutable deletion receipts.
+ *
+ * The writer is the one gate every artifact passes at write time: visibility is
+ * stamped from the governance default, redaction runs BEFORE the bytes are
+ * stored, the per-output and per-run-total caps are checked before the row is
+ * written, and expiresAt is computed from the configured TTL. The expiry sweep
+ * is the retention half: artifacts whose expiresAt is in the past are deleted
+ * (row + object) and every deletion lands one append-only receipt.
+ */
+import type { ArtifactBody, ObjectStore } from "./storage.js";
+import type { GovernanceStore, LifecycleReceipt } from "./governance-store.js";
+import { type OutputGovernanceConfig } from "./governance.js";
+import type { ServerArtifact, ServerRunRecord, SkillsProductStore } from "../server/types.js";
+/**
+ * The object half of the artifact lifecycle: the storage seam's read/write
+ * surface plus the two operations governance needs and the base seam does not
+ * declare - object deletion (expiry sweep) and the quarantine move
+ * (cancellation). ArtifactStorage implements all of them; a db-only embedder
+ * omits the optional ones and rows-only governance still works.
+ */
+export interface RunObjectStore extends ObjectStore {
+    deleteObject?(artifact: ServerArtifact): Promise<void>;
+    moveToQuarantine?(artifact: ServerArtifact): Promise<string | null>;
+    quarantineKeyFor(tenantId: string, runId: string, artifactId: string): string;
+}
+export interface GovernedArtifactWriter {
+    write(run: ServerRunRecord, meta: Omit<ServerArtifact, "createdAt" | "storageKind" | "storageKey" | "bodyText">, body: ArtifactBody): Promise<ServerArtifact>;
+}
+export interface OutputGovernanceOptions {
+    store: SkillsProductStore;
+    governanceStore: GovernanceStore;
+    storage?: RunObjectStore;
+    config?: OutputGovernanceConfig;
+    /** Explicit override of the default visibility for this writer. */
+    visibility?: "private" | "public";
+}
+/**
+ * Apply the configured redaction patterns to run output before it is stored.
+ *
+ * The hook is pure and exported so the same patterns can guard logs and run
+ * records that never pass through the artifact writer.
+ */
+export declare function redactRunOutput(value: unknown, patterns?: RegExp[]): string;
+/** Expiry timestamp for an artifact written now under the given TTL. Absent only when the TTL is undefined. */
+export declare function expiresAtFor(createdAt: string, ttlSeconds: number | undefined): string | undefined;
+/**
+ * The write-time gate. Every enforcement happens before the row exists:
+ *
+ *   1. redact the body text (before storage),
+ *   2. refuse an output above the per-output cap,
+ *   3. refuse a run whose accumulated outputs would exceed the per-run cap,
+ *   4. stamp visibility (private by default) and expiresAt (createdAt + TTL),
+ *   5. materialize (db column or S3 object) and persist.
+ */
+export declare function createGovernedArtifactWriter(options: OutputGovernanceOptions): GovernedArtifactWriter;
+/**
+ * The retention sweep: delete every artifact whose expiresAt is in the past.
+ *
+ * Row deletion and object deletion both happen; the object is removed first so
+ * an object with no row cannot outlive the row (a row with no object is only a
+ * metadata entry, the safe direction). One append-only receipt records what was
+ * deleted, when, and on whose request. Receipts have no update or delete path.
+ */
+export declare function expireArtifacts(options: {
+    governanceStore: GovernanceStore;
+    storage?: RunObjectStore;
+    requestedBy: string;
+    now?: string;
+}): Promise<LifecycleReceipt[]>;

package/dist/sdk/registry.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Registry + version service seam.
+ *
+ * The registry half wraps the shipped server registry (src/server/registry.ts): the
+ * merged catalog, slug resolution, and SKILL.md docs. The version service is the seam
+ * for skills_registry versioning — the `version` column a published record carries, and
+ * the contract sibling work (hasna.skill.v1, skill-hash) builds on.
+ */
+import type { SkillMeta } from "../lib/registry-types.js";
+import { getServerSkill, getServerSkillMd, isValidSkillSlug, listServerSkills } from "../server/registry.js";
+import type { ServerSkillRecord } from "../server/types.js";
+/** The registry an embedder resolves skills against. */
+export interface RegistryService {
+    list(): SkillMeta[];
+    get(slug: string): SkillMeta | null;
+    getSkillMd(slug: string): string | null;
+    isValidSlug(slug: string): boolean;
+}
+/** Current implementation: the bundled registry served by the shipped server. */
+export declare const bundledRegistry: RegistryService;
+/** Resolves the effective version of a published skill record. */
+export interface RegistryVersionService {
+    resolveVersion(record: Pick<ServerSkillRecord, "version">): string | undefined;
+}
+/** Current implementation: the version column carried by the published record. */
+export declare const currentVersionService: RegistryVersionService;
+export { getServerSkill, getServerSkillMd, isValidSkillSlug, listServerSkills };
+export type { SkillMeta };

package/dist/sdk/runs.d.ts

@@ -0,0 +1,229 @@
+/**
+ * Run protocol + atomic run services seam.
+ *
+ * The protocol declares the wire contract for skill runs: the lifecycle states
+ * (admitted / leased / running / terminal), run_id, attempt_id, and lease_generation.
+ * The zod schemas validate both admission and terminal payloads against
+ * contractVersion 1 — the same version the shipped server emits on /api/v1/runs.
+ *
+ * The run services half is the atomic engine: admission, claim/lease, and transition.
+ * The current implementation wraps the store's own atomic transitions (Postgres
+ * `FOR UPDATE SKIP LOCKED`, SQLite `BEGIN IMMEDIATE` plus a conditional claim) — no
+ * business logic is duplicated here.
+ */
+import { z } from "zod";
+import { REMOTE_SKILL_RUN_CONTRACT_VERSION, normalizeRemoteSkillRunContract, type RemoteSkillRunContract } from "../lib/remote-run-contract.js";
+import type { ApiPrincipal, CreateRunInput, ServerRunRecord, ServerRunStatus, SkillsProductStore } from "../server/types.js";
+import type { OfflineGate } from "./offline.js";
+import type { RunEventEmitter } from "./events.js";
+import type { SpendService } from "./spend.js";
+import type { RunQuota } from "./governance.js";
+/** Wire version shared by every run payload this SDK produces or consumes. */
+export declare const RUN_PROTOCOL_VERSION: 1;
+/** Lifecycle states of the run protocol (admitted → leased → running → terminal). */
+export declare const RUN_PROTOCOL_STATES: readonly ["admitted", "leased", "running", "terminal"];
+export type RunProtocolState = (typeof RUN_PROTOCOL_STATES)[number];
+/** Stable run identifier (`run_id`). */
+export type RunId = string;
+/** Attempt identifier (`attempt_id`). */
+export type AttemptId = string;
+/** Fencing token for a claim (`lease_generation`). */
+export type LeaseGeneration = number;
+/** Admission: a run is accepted into the queue. */
+export declare const runAdmissionSchema: z.ZodObject<{
+    contractVersion: z.ZodLiteral<1>;
+    runId: z.ZodString;
+    attemptId: z.ZodString;
+    leaseGeneration: z.ZodNumber;
+    skill: z.ZodString;
+    status: z.ZodLiteral<"admitted">;
+    createdAt: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    createdAt: string;
+    status: "admitted";
+    skill: string;
+    contractVersion: 1;
+    runId: string;
+    leaseGeneration: number;
+    attemptId: string;
+}, {
+    createdAt: string;
+    status: "admitted";
+    skill: string;
+    contractVersion: 1;
+    runId: string;
+    leaseGeneration: number;
+    attemptId: string;
+}>;
+export type RunAdmission = z.infer<typeof runAdmissionSchema>;
+/** Lease: a worker has claimed the run. */
+export declare const runLeaseSchema: z.ZodObject<{
+    contractVersion: z.ZodLiteral<1>;
+    runId: z.ZodString;
+    attemptId: z.ZodString;
+    leaseGeneration: z.ZodNumber;
+    workerId: z.ZodString;
+    status: z.ZodLiteral<"leased">;
+}, "strip", z.ZodTypeAny, {
+    status: "leased";
+    contractVersion: 1;
+    runId: string;
+    leaseGeneration: number;
+    attemptId: string;
+    workerId: string;
+}, {
+    status: "leased";
+    contractVersion: 1;
+    runId: string;
+    leaseGeneration: number;
+    attemptId: string;
+    workerId: string;
+}>;
+export type RunLease = z.infer<typeof runLeaseSchema>;
+/** Terminal: the run reached a final state. */
+export declare const runTerminalSchema: z.ZodObject<{
+    contractVersion: z.ZodLiteral<1>;
+    runId: z.ZodString;
+    attemptId: z.ZodString;
+    leaseGeneration: z.ZodNumber;
+    skill: z.ZodString;
+    status: z.ZodEnum<["succeeded", "failed", "cancelled", "expired"]>;
+    completedAt: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    status: "failed" | "succeeded" | "cancelled" | "expired";
+    skill: string;
+    completedAt: string;
+    contractVersion: 1;
+    runId: string;
+    leaseGeneration: number;
+    attemptId: string;
+}, {
+    status: "failed" | "succeeded" | "cancelled" | "expired";
+    skill: string;
+    completedAt: string;
+    contractVersion: 1;
+    runId: string;
+    leaseGeneration: number;
+    attemptId: string;
+}>;
+export type RunTerminal = z.infer<typeof runTerminalSchema>;
+/** Any single protocol message, discriminated by `status`. */
+export declare const runProtocolSchema: z.ZodDiscriminatedUnion<"status", [z.ZodObject<{
+    contractVersion: z.ZodLiteral<1>;
+    runId: z.ZodString;
+    attemptId: z.ZodString;
+    leaseGeneration: z.ZodNumber;
+    skill: z.ZodString;
+    status: z.ZodLiteral<"admitted">;
+    createdAt: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    createdAt: string;
+    status: "admitted";
+    skill: string;
+    contractVersion: 1;
+    runId: string;
+    leaseGeneration: number;
+    attemptId: string;
+}, {
+    createdAt: string;
+    status: "admitted";
+    skill: string;
+    contractVersion: 1;
+    runId: string;
+    leaseGeneration: number;
+    attemptId: string;
+}>, z.ZodObject<{
+    contractVersion: z.ZodLiteral<1>;
+    runId: z.ZodString;
+    attemptId: z.ZodString;
+    leaseGeneration: z.ZodNumber;
+    workerId: z.ZodString;
+    status: z.ZodLiteral<"leased">;
+}, "strip", z.ZodTypeAny, {
+    status: "leased";
+    contractVersion: 1;
+    runId: string;
+    leaseGeneration: number;
+    attemptId: string;
+    workerId: string;
+}, {
+    status: "leased";
+    contractVersion: 1;
+    runId: string;
+    leaseGeneration: number;
+    attemptId: string;
+    workerId: string;
+}>, z.ZodObject<{
+    contractVersion: z.ZodLiteral<1>;
+    runId: z.ZodString;
+    attemptId: z.ZodString;
+    leaseGeneration: z.ZodNumber;
+    skill: z.ZodString;
+    status: z.ZodEnum<["succeeded", "failed", "cancelled", "expired"]>;
+    completedAt: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    status: "failed" | "succeeded" | "cancelled" | "expired";
+    skill: string;
+    completedAt: string;
+    contractVersion: 1;
+    runId: string;
+    leaseGeneration: number;
+    attemptId: string;
+}, {
+    status: "failed" | "succeeded" | "cancelled" | "expired";
+    skill: string;
+    completedAt: string;
+    contractVersion: 1;
+    runId: string;
+    leaseGeneration: number;
+    attemptId: string;
+}>]>;
+export type RunProtocolMessage = z.infer<typeof runProtocolSchema>;
+/** Map the store's status vocabulary onto the protocol lifecycle. */
+export declare function protocolStateOf(status: ServerRunStatus): RunProtocolState;
+/** The current engine is single-attempt: the attempt id is the run id. */
+export declare function attemptIdOf(run: Pick<ServerRunRecord, "id">): AttemptId;
+/** The current engine keeps the generation the claim actually stamped. */
+export declare function leaseGenerationOf(run: Pick<ServerRunRecord, "leaseGeneration">): LeaseGeneration;
+/** One atomic status transition on a run. */
+export type RunTransition = Partial<Pick<ServerRunRecord, "status" | "outputType" | "outputPreview" | "errorCode" | "errorMessage" | "startedAt" | "completedAt">>;
+/** Atomic run services: admission, lease/claim, transition, and read. */
+export interface RunService {
+    admit(input: CreateRunInput): Promise<ServerRunRecord>;
+    leaseNext(workerId: string): Promise<ServerRunRecord | null>;
+    transition(runId: string, patch: RunTransition): Promise<ServerRunRecord | null>;
+    get(principal: ApiPrincipal, runId: string): Promise<ServerRunRecord | null>;
+}
+export interface RunServiceOptions {
+    store: SkillsProductStore;
+    /**
+     * Optional governance wiring. When present, admit() runs the full admission
+     * chain before a run enters the queue: the offline gate first (fail closed),
+     * then the spend ceilings (RUN_BUDGET_EXHAUSTED on refusal), then the run is
+     * created, reserved against, and announced. Absent, admit() is exactly what
+     * it always was - the embedder opts in to the controls.
+     */
+    governance?: RunServiceGovernance;
+}
+export interface RunServiceGovernance {
+    offline?: OfflineGate;
+    spend?: SpendService;
+    events?: RunEventEmitter;
+    /** Resource envelope this run requests, checked against the org ceilings. */
+    quota?: RunQuota;
+    /** Estimated cost in cents, reserved before dispatch. */
+    estimatedCents?: number;
+}
+/** Current implementation: the store's own atomic transitions, plus the optional admission chain. */
+export declare function createRunService({ store, governance }: RunServiceOptions): RunService;
+/**
+ * Settle a terminal run: reconcile its credit reservation against the actual
+ * cost and emit the terminal lifecycle event. The reservation is released
+ * (actual 0) or charged (actual > 0); unused reservations never linger.
+ */
+export declare function settleRun(store: SkillsProductStore, options: {
+    spend?: SpendService;
+    events?: RunEventEmitter;
+}, run: ServerRunRecord, actualCents?: number): Promise<void>;
+export { REMOTE_SKILL_RUN_CONTRACT_VERSION, normalizeRemoteSkillRunContract };
+export type { RemoteSkillRunContract };

package/dist/sdk/server.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Server seam: router + handler types, and thin server factories over the shipped HTTP
+ * API implementation (src/server/app.ts).
+ *
+ * The routing logic itself is untouched: createSkillsFetchHandler() owns the /api/v1
+ * dispatcher and every durability guard. This module is the contract an embedder (the
+ * SaaS control plane) builds against, and it re-exports the implementation.
+ */
+import { assertDurableStore, assertDurableTarget, createSkillsFetchHandler, skillsServeLimits, startSkillsServer, type SkillsServerOptions } from "../server/app.js";
+import { resolveServerConfig, type SkillsServerConfig } from "../server/config.js";
+import type { ApiPrincipal } from "../server/types.js";
+/** A request handler: the unit the HTTP layer executes. */
+export type SkillsRequestHandler = (request: Request) => Promise<Response>;
+/** One additional route, matched exactly on method + pathname before the base handler. */
+export interface SkillsRoute {
+    method: string;
+    pathname: string;
+    handler: SkillsRequestHandler;
+}
+/**
+ * Build the shipped API server as a plain fetch handler.
+ *
+ * Thin wrapper over createSkillsFetchHandler() — same store, same guards, same routes.
+ */
+export declare function createServer(options?: SkillsServerOptions): Promise<SkillsRequestHandler>;
+/**
+ * Register additional routes in front of a base handler.
+ *
+ * Consulted before the base handler on exact method + pathname match; anything else
+ * falls through to the shipped dispatcher. This is composition, not a rewrite of the
+ * router.
+ */
+export declare function registerRoutes(base: SkillsRequestHandler, routes: SkillsRoute[]): SkillsRequestHandler;
+export { assertDurableStore, assertDurableTarget, createSkillsFetchHandler, skillsServeLimits, startSkillsServer, resolveServerConfig, };
+export type { ApiPrincipal, SkillsServerConfig, SkillsServerOptions };

package/dist/sdk/spend.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Spend governance: credit reservations and org ceilings, enforced at admission.
+ *
+ * The flow: admit() checks every ceiling BEFORE a run enters the queue
+ * (per-run resource envelope, org concurrency, org monthly total) and refuses
+ * with RUN_BUDGET_EXHAUSTED when one is exhausted - the exact error the
+ * negative fixture asserts. reserve() then sets aside the estimate, keyed to
+ * the run, before dispatch. reconcile() runs once at terminal state: the
+ * actual cost is charged (status "charged") or, when nothing was used, the
+ * reservation is released ("released") - the unused half never lingers.
+ *
+ * All numbers are cents; a ceiling is a finite integer, never an open-ended
+ * budget.
+ */
+import type { ApiPrincipal } from "../server/types.js";
+import { type RunQuota, type SpendCeilings } from "./governance.js";
+import type { CreditReservation, GovernanceStore } from "./governance-store.js";
+export interface SpendAdmissionInput {
+    principal: ApiPrincipal;
+    slug: string;
+    quota?: RunQuota;
+    estimatedCents?: number;
+    now?: Date;
+}
+export interface SpendService {
+    /** Enforce the org's ceilings; throw RUN_BUDGET_EXHAUSTED with the exact ceiling named. */
+    admit(input: SpendAdmissionInput): Promise<void>;
+    /** Reserve credits for a run before dispatch. Returns the reservation id. */
+    reserve(tenantId: string, runId: string, estimatedCents: number): Promise<CreditReservation>;
+    /** Reconcile at terminal state: charge the actual cost, or release the unused reservation. */
+    reconcile(tenantId: string, runId: string, actualCents: number): Promise<CreditReservation | null>;
+}
+export declare function createSpendService(options: {
+    governanceStore: GovernanceStore;
+    ceilings?: SpendCeilings;
+}): SpendService;

package/dist/sdk/storage.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Storage + object-store seam.
+ *
+ * The relational half is the store interface (SkillsProductStore) and the shipped
+ * backends: Postgres via a postgres:// URL, SQLite via a path or file URL (the
+ * zero-config default), and the explicitly-named in-memory store. The object-store half
+ * is where artifact and bundle bytes live: the database column or S3, selected by
+ * ArtifactStorage's bucket option.
+ */
+import { ArtifactStorage, type ArtifactBody, type ArtifactStorageOptions } from "../server/artifact-storage.js";
+import { resolveDatabaseTarget, type DatabaseTarget } from "../server/database-url.js";
+import { SqliteSkillsStore, type SqliteStoreOptions } from "../server/sqlite-store.js";
+import { MemorySkillsStore, PostgresSkillsStore, createStore, type StoreOptions } from "../server/store.js";
+import type { BlobStorageKind, ServerArtifact, ServerRunRecord, ServerSkillBundle, SkillsProductStore, StoreBackendInfo } from "../server/types.js";
+export type { ArtifactBody, ArtifactStorageOptions, BlobStorageKind, DatabaseTarget, ServerArtifact, ServerRunRecord, ServerSkillBundle, SkillsProductStore, SqliteStoreOptions, StoreBackendInfo, StoreOptions, };
+/** Object-store seam: where run artifacts and skill bundles live. */
+export interface ObjectStore {
+    readonly usesS3: boolean;
+    materialize(run: ServerRunRecord, artifact: Omit<ServerArtifact, "createdAt" | "storageKind" | "storageKey" | "bodyText">, body: ArtifactBody): Promise<Omit<ServerArtifact, "createdAt">>;
+    readText(artifact: ServerArtifact): Promise<string | null>;
+    deleteBundle(orgId: string, sha256: string): Promise<void>;
+}
+/** Compile-time proof the shipped implementation satisfies the seam. */
+export declare const artifactStorageSeam: new (options?: ArtifactStorageOptions) => ObjectStore;
+export { ArtifactStorage, MemorySkillsStore, PostgresSkillsStore, SqliteSkillsStore, createStore, resolveDatabaseTarget, };

package/dist/server/app.d.ts

@@ -0,0 +1,42 @@
+import { type SkillsServerConfig } from "./config.js";
+import { type MemorySkillsStore } from "./store.js";
+import type { SkillsProductStore } from "./types.js";
+export interface SkillsServerOptions {
+    config?: Partial<SkillsServerConfig>;
+    store?: SkillsProductStore;
+}
+/**
+ * Refuse to serve traffic from storage that will not survive a restart.
+ *
+ * /health answering `ok: true` from a process backed by a Map is worse than a crash: it
+ * satisfies every load balancer, container orchestrator, and smoke test we have, right
+ * up until the process restarts and every run, log, and artifact is gone. Failing at
+ * startup puts the problem where an operator will see it.
+ *
+ * A store that declares no backend is assumed durable - see StoreBackendInfo. This
+ * guard's job is to make our own defaults safe, not to audit somebody else's store.
+ */
+export declare function assertDurableStore(store: SkillsProductStore, config: Pick<SkillsServerConfig, "allowEphemeralStore">): void;
+/** The same refusal, expressed against a resolved target so it can run before anything opens. */
+export declare function assertDurableTarget(target: {
+    durable: boolean;
+    label: string;
+}, config: Pick<SkillsServerConfig, "allowEphemeralStore">): void;
+export declare function createSkillsFetchHandler(options?: SkillsServerOptions): Promise<(request: Request) => Promise<Response>>;
+export declare function startSkillsServer(options?: SkillsServerOptions): Promise<Bun.Server<undefined>>;
+/**
+ * Socket-level body ceiling, derived from the same setting the publish route enforces.
+ *
+ * Without this the configured bundle limit was only ever advisory: Bun.serve defaults to
+ * 128 MB, a chunked request sends no Content-Length for the early check to read, and
+ * `request.formData()` materialises the whole body before any per-part check can run. So
+ * a 25 MB configured cap admitted 128 MB of buffered request per connection. This refuses
+ * it at the socket, before any of that is allocated.
+ *
+ * Exported so an embedder calling Bun.serve() with our fetch handler gets the same
+ * ceiling instead of silently inheriting the default.
+ */
+export declare function skillsServeLimits(config: Pick<SkillsServerConfig, "skillBundleLimitBytes" | "requestBodyLimitBytes">): {
+    maxRequestBodySize: number;
+};
+export type { MemorySkillsStore };

package/dist/server/artifact-storage.d.ts

@@ -0,0 +1,102 @@
+import { type OwnedBytes } from "../lib/skill-bundle.js";
+import type { BlobStorageKind, ServerArtifact, ServerRunRecord, ServerSkillBundle } from "./types.js";
+export interface ArtifactBody {
+    relativePath: string;
+    bodyText: string;
+    contentType: string;
+}
+export interface ArtifactStorageOptions {
+    bucket?: string;
+    prefix?: string;
+    region?: string;
+}
+export declare class ArtifactStorage {
+    private bucket?;
+    private prefix;
+    private s3?;
+    constructor(options?: ArtifactStorageOptions);
+    get usesS3(): boolean;
+    /**
+     * Object key for a run artifact: `<prefix>/<tenantId>/<runId>/<relativePath>`.
+     * The tenant segment is structural, never optional - a bucket policy or a
+     * lifecycle rule can key on it, and two tenants can never share a key even
+     * when a run id were ever reused. `relativePath` is caller-supplied, so it is
+     * sanitised: leading slashes and `..` segments are removed, and anything that
+     * survives the sanitisation is what lands in the key.
+     */
+    objectKeyFor(tenantId: string, runId: string, relativePath: string): string;
+    /**
+     * Object key for a quarantined partial artifact: a sibling namespace under the
+     * same prefix, so one bucket policy covers both and the quarantine is visible
+     * in the object listing without any metadata join. Deliberately keyed by
+     * artifact id, not by the original relative path: the point of the move is
+     * that the artifact's original location no longer resolves.
+     */
+    quarantineKeyFor(tenantId: string, runId: string, artifactId: string): string;
+    materialize(run: ServerRunRecord, artifact: Omit<ServerArtifact, "createdAt" | "storageKind" | "storageKey" | "bodyText">, body: ArtifactBody): Promise<Omit<ServerArtifact, "createdAt">>;
+    readText(artifact: ServerArtifact): Promise<string | null>;
+    /**
+     * Place a skill bundle's bytes, returning where they went.
+     *
+     * Deliberately a second method on the same class rather than a second class: an
+     * operator configures one bucket and one prefix, and a bundle that silently went
+     * somewhere else than the run artifacts would be the kind of thing discovered during a
+     * restore. The key is content-addressed - the digest is the whole name - so unlike
+     * keyFor() there is no caller-supplied path component to sanitise, only a digest to
+     * refuse if it is not one.
+     *
+     * Binary throughout. `materialize()` above takes `bodyText: string` because a run
+     * artifact is a document; a skill bundle is a gzipped tar and there is no point in the
+     * pipeline where turning it into a string would be lossless.
+     */
+    putBundle(orgId: string, sha256: string, bytes: OwnedBytes, contentType?: string): Promise<{
+        storageKind: BlobStorageKind;
+        storageKey?: string;
+        bytes?: OwnedBytes;
+    }>;
+    /**
+     * Read a bundle back.
+     *
+     * Returns null when the bytes cannot be produced - an S3-backed row on a server with no
+     * bucket configured, or a row whose blob column is empty. Null is distinguishable from
+     * an empty bundle by the caller, which knows the recorded byteSize.
+     */
+    readBundle(bundle: ServerSkillBundle): Promise<OwnedBytes | null>;
+    /**
+     * Remove a bundle's object, if it had one.
+     *
+     * The store collects the *row* when nothing references a digest any more, but a row is
+     * only half of an S3-backed bundle. Without this the object stayed in the bucket after
+     * the user deleted the skill - unreachable, because the key lived in the row that is
+     * now gone, and therefore also uncollectable. That is a retention problem, not a leak
+     * you can clean up later.
+     *
+     * A no-op when nothing is configured, which is why the caller can invoke it
+     * unconditionally.
+     */
+    deleteBundle(orgId: string, sha256: string): Promise<void>;
+    /**
+     * Remove an artifact object, if it had one.
+     *
+     * The counterpart of deleteBundle for run artifacts: the row deletion is the
+     * governance store's job, but an S3-backed artifact is only gone when the
+     * object is gone. A no-op when nothing is configured, which is why the caller
+     * can invoke it unconditionally.
+     */
+    deleteObject(artifact: ServerArtifact): Promise<void>;
+    /**
+     * Move an artifact's object into the quarantine namespace.
+     *
+     * Cancellation quarantines partial artifacts before the run is marked
+     * cancelled, so a cancelled run's half-written outputs are neither served
+     * nor silently deleted: they sit under `.../quarantine/<tenant>/<run>/<id>`
+     * and are recorded in a quarantine receipt.
+     *
+     * Returns the new key, or null for a database-backed artifact (its body has
+     * no object to move; the row is marked by the receipt alone). A no-op for
+     * an artifact that has no storage key at all.
+     */
+    moveToQuarantine(artifact: ServerArtifact): Promise<string | null>;
+    private keyFor;
+    private bundleKeyFor;
+}

package/dist/server/auth.d.ts

@@ -0,0 +1,5 @@
+import type { ApiPrincipal, SkillsProductStore } from "./types.js";
+export declare function hashApiKey(token: string): string;
+export declare function bearerToken(request: Request): string | null;
+export declare function authenticateRequest(store: SkillsProductStore, request: Request): Promise<ApiPrincipal | null>;
+export declare function publicPrincipal(partial?: Partial<ApiPrincipal>): ApiPrincipal;

package/dist/server/config.d.ts

@@ -0,0 +1,40 @@
+export interface SkillsServerConfig {
+    host: string;
+    port: number;
+    databaseUrl?: string;
+    bootstrapApiKey?: string;
+    artifactBucket?: string;
+    artifactPrefix: string;
+    inlineWorker: boolean;
+    /**
+     * HMAC key for signing served skill bundles. When set, the bundle endpoint adds
+     * X-Skill-Bundle-Signature so clients holding the same key can verify that the bytes
+     * they pulled are the bytes this server decided to serve. Read from
+     * HASNA_SKILLS_SIGNING_KEY; never logged or printed.
+     */
+    bundleSigningKey?: string;
+    requestBodyLimitBytes: number;
+    /**
+     * Cap for a skill bundle upload, separate from requestBodyLimitBytes on purpose.
+     *
+     * requestBodyLimitBytes is 1 MB and guards JSON request bodies, where a megabyte of
+     * JSON is already pathological. A real skill with a references/ folder goes past that
+     * routinely, so publishing needed either a raised general cap - which would also have
+     * raised the ceiling on every JSON endpoint, quietly - or its own. This is the "its
+     * own": POST /api/v1/skills is the only route that reads it, it is checked before the
+     * body is buffered, and the JSON cap is untouched.
+     */
+    skillBundleLimitBytes: number;
+    publicBaseUrl: string;
+    nodeEnv: string;
+    /**
+     * Allow starting on a store that declares itself non-durable.
+     *
+     * Off by default, because "started fine, lost everything on restart" is the failure
+     * this whole change exists to remove. Tests and throwaway demos that genuinely want
+     * an in-process store set HASNA_SKILLS_ALLOW_EPHEMERAL_STORE=1 and own the
+     * consequence; nobody gets there by forgetting to configure a database.
+     */
+    allowEphemeralStore: boolean;
+}
+export declare function resolveServerConfig(env?: Record<string, string | undefined>): SkillsServerConfig;