@hasna/skills 0.1.62 → 0.1.64

package/dist/server/database-url.d.ts

@@ -0,0 +1,42 @@
+/** Filename of the default SQLite database inside the skills data directory. */
+export declare const DEFAULT_SQLITE_FILENAME = "server.db";
+/** The token that selects an in-memory SQLite database (SQLite's own spelling). */
+export declare const SQLITE_MEMORY_PATH = ":memory:";
+export type DatabaseTarget = {
+    kind: "postgres";
+    url: string;
+    durable: true;
+    label: string;
+} | {
+    kind: "sqlite";
+    path: string;
+    durable: boolean;
+    label: string;
+} | {
+    kind: "memory";
+    durable: false;
+    label: string;
+};
+/**
+ * Absolute path of the default SQLite database.
+ *
+ * PR #50 moved the *skill corpus* into ~/.hasna/skills/installed/ and left app data at
+ * the app root, matching every sibling Hasna app (mementos keeps mementos.db beside
+ * agents/, accounts keeps accounts.json beside profiles/). The server database is app
+ * data, so it belongs at the root - ~/.hasna/skills/server.db - and explicitly NOT
+ * inside installed/, which now holds exactly one thing: installed skills.
+ *
+ * Resolved through getDataDir() rather than composed from $HOME so that
+ * $HASNA_SKILLS_DIR relocates the database along with the rest of the app's state. The
+ * test preload sets that variable per test, which is also what keeps the suite from
+ * writing a server.db into a developer's real home.
+ */
+export declare function defaultSqlitePath(): string;
+/**
+ * Resolve an operator-supplied database string into a concrete backend choice.
+ *
+ * @throws if the string names a scheme this build has no backend for. Refusing beats
+ * guessing: a typo'd scheme that silently became "SQLite at ./mysql:" would present as
+ * an empty database rather than as a configuration error.
+ */
+export declare function resolveDatabaseTarget(raw?: string | null): DatabaseTarget;

package/dist/server/handlers.d.ts

@@ -0,0 +1,3 @@
+import { ArtifactStorage } from "./artifact-storage.js";
+import type { ServerRunRecord, SkillsProductStore } from "./types.js";
+export declare function executeRun(store: SkillsProductStore, run: ServerRunRecord, storage?: ArtifactStorage): Promise<ServerRunRecord>;

package/dist/server/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+export {};

package/dist/server/migrate.d.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env bun
+import { type DatabaseTarget } from "./database-url.js";
+export interface MigrationResult {
+    backend: DatabaseTarget["kind"];
+    applied: string[];
+}
+/**
+ * Apply pending migrations to whatever backend `databaseUrl` names.
+ *
+ * @param migrationsDir override for the directory holding this dialect's .sql files.
+ * Defaults to the dialect subdirectory of the package's migrations/ folder.
+ */
+export declare function runMigrations(databaseUrl?: string, migrationsDir?: string): Promise<MigrationResult>;

package/dist/server/migrations-dir.d.ts

@@ -0,0 +1,18 @@
+export declare const MIGRATION_DIALECTS: readonly ["postgres", "sqlite"];
+export type MigrationDialect = (typeof MIGRATION_DIALECTS)[number];
+/**
+ * Absolute path of `migrations/`, or null when it cannot be found.
+ *
+ * Searches the callers' likely roots in order: the module's own directory chain (which
+ * covers src/, bin/, dist/, and node_modules installs) and then the working directory
+ * chain (which covers `bun run migrate` invoked from a subdirectory).
+ */
+export declare function findMigrationsRoot(startDirs?: string[]): string | null;
+/**
+ * Absolute path of the migration directory for one dialect.
+ *
+ * @throws when the directory cannot be located, naming the dialect. Throwing beats
+ * returning an empty list: "0 migrations applied" against a fresh database looks like
+ * success right up until the first query fails on a missing table.
+ */
+export declare function resolveMigrationsDir(dialect: MigrationDialect, root?: string | null): string;

package/dist/server/redaction.d.ts

@@ -0,0 +1 @@
+export declare function redactForClient(value: unknown): string;

package/dist/server/registry.d.ts

@@ -0,0 +1,5 @@
+import { type SkillMeta } from "../lib/registry.js";
+export declare function isValidSkillSlug(slug: string): boolean;
+export declare function listServerSkills(): SkillMeta[];
+export declare function getServerSkill(slug: string): SkillMeta | null;
+export declare function getServerSkillMd(slug: string): string | null;

package/dist/server/rows.d.ts

@@ -0,0 +1,24 @@
+import type { ServerArtifact, ServerPin, ServerRunLog, ServerRunRecord, ServerSkillBundle, ServerSkillRecord } from "./types.js";
+export declare function nowIso(): string;
+/**
+ * Coerce a caller-supplied row limit to a non-negative integer.
+ *
+ * The two engines disagree loudly about what a bad limit means. SQLite reads `LIMIT -1`
+ * as *unlimited* and rejects `LIMIT 1.5` as a datatype mismatch; Postgres rejects -1 and
+ * rounds 1.5 up. Left alone, `listRuns(principal, -1)` returned one org's entire history
+ * on SQLite and an error on Postgres - and the SQLite answer is the dangerous direction,
+ * since the argument exists to bound the response. HTTP callers are already clamped in
+ * app.ts; this covers the store used as a library, which is a published seam.
+ */
+export declare function normalizeLimit(limit: number): number;
+export declare function runId(): string;
+export declare function artifactId(): string;
+export declare function rowToRun(row: Record<string, unknown>): ServerRunRecord;
+export declare function rowToLog(row: Record<string, unknown>): ServerRunLog;
+export declare function rowToArtifact(row: Record<string, unknown>): ServerArtifact;
+export declare function rowToSkill(row: Record<string, unknown>): ServerSkillRecord;
+export declare function rowToPin(row: Record<string, unknown>): ServerPin;
+export declare function rowToSkillBundle(row: Record<string, unknown>): ServerSkillBundle;
+export declare function parseJsonObject(value: unknown): Record<string, unknown>;
+export declare function parseJsonArray(value: unknown): string[];
+export declare function dateString(value: unknown): string;

package/dist/server/skills-api.d.ts

@@ -0,0 +1,170 @@
+import { type OwnedBytes } from "../lib/skill-bundle.js";
+import type { SkillMeta } from "../lib/registry-types.js";
+import type { ArtifactStorage } from "./artifact-storage.js";
+import type { SkillsServerConfig } from "./config.js";
+import { type ApiPrincipal, type PublishSkillInput, type ServerPin, type ServerSkillRecord, type SkillsProductStore } from "./types.js";
+/** Wire shape of a pin: the client-facing facts, without the storage columns. */
+export declare function pinPayload(pin: ServerPin): Record<string, unknown>;
+/**
+ * The metadata field of a pin body.
+ *
+ * Absent means an empty object (matching the schema default), present-and-not-an-
+ * object is refused rather than coerced: a client that sends `metadata: "team"`
+ * sent a bug, and storing it as `{}` would make the round-trip silently lose
+ * what the caller wrote. The route calls this on the parsed JSON body before
+ * touching the store, so a malformed body is a 400 and never a row.
+ */
+export declare function pinMetadataField(body: Record<string, unknown>): Record<string, unknown>;
+export declare class SkillRequestError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(status: number, code: string, message: string);
+}
+/** SkillMeta shape for a published row, so a client can treat both kinds alike. */
+export declare function publishedSkillMeta(record: ServerSkillRecord): SkillMeta;
+export declare function publishedPayload(record: ServerSkillRecord): Record<string, unknown>;
+/**
+ * The HTTP ETag for a published row: the revision id, quoted exactly as RFC 9110 wants.
+ * The quotes are load-bearing — a client that echoes the whole header value back as
+ * If-Match must send the quotes too.
+ */
+export declare function revisionEtag(revisionId: string): string;
+/**
+ * Parse an If-Match header value into the revision id it names.
+ *
+ * Accepts the quoted form the server itself issues (RFC 9110) and a bare id for
+ * tolerance. `*` is refused: "any revision" would license exactly the silent overwrite
+ * the optimistic-concurrency guard exists to refuse. Malformed values are a 400
+ * statement about the request, never a fallback to "no guard".
+ */
+export declare function parseIfMatch(value: string | null): string | undefined;
+/**
+ * Resolve a stored row that may be a tombstone (todos d061fcda).
+ *
+ * A tombstoned row answers 410 with the marker while its window is open, so a client's
+ * pull can reconcile (remove the local copy). Once the window has passed the tombstone
+ * is purged and the slug is simply gone (404). Returns "purged" when the caller should
+ * answer 404, a tombstone payload when it should answer 410, or "live" for a live row.
+ *
+ * Purging drops the store's bundle row and, for every purged record, the S3 object
+ * behind it — the same getSkillBundle-then-delete dance the publish/delete paths use,
+ * so an object whose digest another row still references survives.
+ */
+export declare function tombstoneStatus(store: SkillsProductStore, artifactStorage: ArtifactStorage, principal: ApiPrincipal, record: ServerSkillRecord): Promise<"live" | "purged" | Record<string, unknown>>;
+/**
+ * Bundled corpus plus this org's published skills, published winning on a slug collision.
+ *
+ * Same rule as the CLI-side merge in src/lib/registry-merge.ts and for the same reason: an
+ * organization that published `deploy-notes` on their own instance meant to override the
+ * bundled `deploy-notes` there.
+ */
+export declare function listMergedSkills(store: SkillsProductStore, principal: ApiPrincipal): Promise<Record<string, unknown>[]>;
+/**
+ * What a read of one slug resolves to: the org's published row (live or tombstoned) or
+ * nothing. The bundled-corpus fallback is the callers' decision, not this resolver's —
+ * a tombstoned slug must answer 410 even when a bundled skill of the same name exists,
+ * because the caller asked for the skill this instance serves under that slug.
+ */
+export type SkillReadResolution = {
+    kind: "published";
+    record: ServerSkillRecord;
+} | {
+    kind: "tombstone";
+    payload: Record<string, unknown>;
+} | {
+    kind: "absent";
+};
+export declare function resolvePublishedSkill(store: SkillsProductStore, artifactStorage: ArtifactStorage, principal: ApiPrincipal, slug: string): Promise<SkillReadResolution>;
+/**
+ * Distinct tags across the org's registry view: the org's published tags (the
+ * indexed store query over the skills_tags projection, in both backends) plus
+ * the bundled corpus's, which is a fixed in-process set. The route serves the
+ * same universe GET /api/v1/skills serves, so a client can take any tag this
+ * list returns and filter with it. Sorted, de-duplicated, and emptied of blank
+ * entries to match the client contract (non-empty tag names).
+ */
+export declare function listOrgTags(store: SkillsProductStore, principal: ApiPrincipal): Promise<string[]>;
+/**
+ * The merged registry view (bundled + published) filtered to skills carrying an
+ * exact tag. Same merge rules and payloads as listMergedSkills - the tag filter
+ * narrows what GET /api/v1/skills would have returned, it does not switch to a
+ * different universe. The published half comes from the indexed store query;
+ * only the static bundled corpus is filtered in-process, and a bundled skill
+ * whose slug a published row occupies is excluded so published-wins precedence
+ * holds for tag reads exactly as it does for the unfiltered view.
+ */
+export declare function listMergedSkillsByTag(store: SkillsProductStore, principal: ApiPrincipal, tag: string): Promise<Record<string, unknown>[]>;
+/**
+ * The minimal per-skill wire row the tag/sync summary routes serve: the client's
+ * RemoteSkillSummary contract ({ slug, name?, version?, updatedAt? }).
+ */
+export declare function skillSummary(skill: Record<string, unknown>): Record<string, unknown>;
+/**
+ * The principal's pins filtered to slugs whose skill (bundled or published, in
+ * this org's merged view) carries the exact tag. A pin carries no tag of its
+ * own - the filter resolves each pinned slug against the registry view, the
+ * same way the rest of the surface treats a pin as a fact about a skill.
+ *
+ * Published pins come from the indexed store query (skills_tags projection);
+ * the bundled-corpus half is resolved in-process against the static corpus and
+ * excludes slugs a published row occupies, so every pinned slug resolves
+ * through exactly one path (published wins) and no pin can appear twice.
+ */
+export declare function listPinsByTag(store: SkillsProductStore, principal: ApiPrincipal, tag: string): Promise<Record<string, unknown>[]>;
+export declare function getMergedSkill(store: SkillsProductStore, artifactStorage: ArtifactStorage, principal: ApiPrincipal, slug: string): Promise<Record<string, unknown> | null>;
+/**
+ * The SKILL.md document for one slug, or null when nothing is served under it.
+ *
+ * A tombstoned slug returns null here; the caller that needs the 410 marker resolves
+ * the tombstone itself via resolvePublishedSkill before calling.
+ */
+export declare function getMergedSkillMd(store: SkillsProductStore, artifactStorage: ArtifactStorage, principal: ApiPrincipal, slug: string): Promise<string | null>;
+interface ParsedPublish {
+    input: Omit<PublishSkillInput, "principal">;
+    bundleBytes?: OwnedBytes;
+}
+/**
+ * Read a publish request.
+ *
+ * Two accepted encodings, both deliberate:
+ *   - multipart/form-data with a `manifest` JSON part and a `bundle` file part. This is
+ *     the one `skills push` uses. The bundle never passes through readJson(), so the 1 MB
+ *     JSON cap is neither raised nor bypassed - the bundle has its own, larger cap.
+ *   - application/json for a metadata-only publish (an instruction skill with no files).
+ *     Subject to the ordinary JSON cap, because it is an ordinary JSON body.
+ *
+ * On what the size checks here can and cannot do. Content-Length is a claim: a chunked
+ * request need not send one, so the header check is an early-out, never the guarantee.
+ * The real ceiling is Bun.serve's `maxRequestBodySize`, set from the same config value in
+ * app.ts, which refuses at the socket before this function is reached. The checks below
+ * are what remains meaningful once the body is in hand: the per-part limits, and the
+ * refusal of any part this endpoint did not ask for - without which a request could carry
+ * a compliant `manifest`, a compliant `bundle`, and unbounded extra parts that nothing
+ * measured.
+ */
+export declare function parsePublishRequest(request: Request, config: SkillsServerConfig): Promise<ParsedPublish>;
+export declare function storePublishedSkill(store: SkillsProductStore, artifactStorage: ArtifactStorage, principal: ApiPrincipal, parsed: ParsedPublish, expectedRevisionId?: string): Promise<ServerSkillRecord>;
+/**
+ * Tombstone a published skill (todos d061fcda): the row survives with a tombstone
+ * marker for `tombstoneWindowMs`, so reads answer 410 and a pulling client can
+ * reconcile, and the bundle is retained until the purge. The stored object is NOT
+ * discarded here — the tombstoned row still references it; the purge discards it.
+ * Returns the tombstoned record, or null when the org has no row by that slug.
+ */
+export declare function deletePublishedSkill(store: SkillsProductStore, artifactStorage: ArtifactStorage, principal: ApiPrincipal, slug: string, tombstoneWindowMs: number): Promise<ServerSkillRecord | null>;
+/**
+ * Read a published bundle back, refusing to serve bytes that no longer hash to the digest
+ * they were stored under.
+ *
+ * This is what the sha256 column buys. Storage drift - a truncated blob, an S3 object
+ * replaced out of band, a bad restore - is otherwise completely silent: the client
+ * receives a shorter tarball, extraction fails somewhere unrelated, and nothing points at
+ * storage. Verifying on read turns that into one error naming the digest.
+ */
+export declare function readPublishedBundle(store: SkillsProductStore, artifactStorage: ArtifactStorage, principal: ApiPrincipal, slug: string): Promise<{
+    record: ServerSkillRecord;
+    bytes: OwnedBytes;
+}>;
+export declare function assertPublishableSlug(slug: string): void;
+export declare function assertSha256(value: string): void;
+export {};

package/dist/server/sqlite-store.d.ts

@@ -0,0 +1,131 @@
+/**
+ * SQLite implementation of SkillsProductStore.
+ *
+ * This is the zero-config default: a single operator runs `skills-server` with nothing
+ * configured and gets a durable database at ~/.hasna/skills/server.db. Point
+ * HASNA_SKILLS_DATABASE_URL at a postgres:// URL and the same server becomes the shared
+ * multi-worker deployment. The database is an adapter choice, not a product variant -
+ * the schema shape, the org scoping, and the run lifecycle are identical either way.
+ *
+ * Semantics are matched to PostgresSkillsStore method for method, including the places
+ * where Postgres does something arguably odd (updateRun is not org-scoped; it is the
+ * worker's write path and the worker has already been handed the run). Parity is the
+ * requirement; changing Postgres behaviour is not this module's job.
+ */
+import { Database } from "bun:sqlite";
+import type { ApiPrincipal, ClaimRunInput, CreateRunInput, PublishSkillInput, RunTransitionPatch, ServerArtifact, ServerPin, ServerRunLog, ServerRunRecord, ServerSkillBundle, ServerSkillRecord, SkillsProductStore, StoreBackendInfo, UpdateSkillPatch } from "./types.js";
+export interface SqliteStoreOptions {
+    /** Apply pending migrations on open. Default true - it is what makes zero-config work. */
+    migrate?: boolean;
+    /** Override the migrations directory. Tests and embedders only. */
+    migrationsDir?: string;
+    /**
+     * How long a writer waits for another connection's write lock before giving up.
+     *
+     * Not decoration. SQLite serialises writers; without a busy timeout a second worker
+     * process calling claimNextRun() at the same moment gets SQLITE_BUSY immediately and
+     * the claim fails rather than queueing. Five seconds is far longer than a claim
+     * transaction (three statements, no I/O beyond the page cache) can plausibly take.
+     */
+    busyTimeoutMs?: number;
+}
+export declare class SqliteSkillsStore implements SkillsProductStore {
+    readonly backend: StoreBackendInfo;
+    private db;
+    private closed;
+    constructor(path?: string, options?: SqliteStoreOptions);
+    /**
+     * Give rows written before migration 0004 a real content revision id.
+     *
+     * The migration adds revision_id with DEFAULT '', which would make If-Match vacuous
+     * for legacy rows (every stale client matches the same empty string). This replaces
+     * the marker with a content sha, idempotently: new code always writes a full id, so
+     * the marker never reappears. Mirrors PostgresSkillsStore.backfillLegacyRevisions.
+     */
+    private backfillLegacyRevisions;
+    /** Escape hatch for tests and for tooling that needs raw SQL against the same handle. */
+    get database(): Database;
+    close(): Promise<void>;
+    ensureBootstrapApiKey(token: string, principal?: Partial<ApiPrincipal>): Promise<void>;
+    authenticateApiKeyHash(hash: string): Promise<ApiPrincipal | null>;
+    createRun(input: CreateRunInput): Promise<ServerRunRecord>;
+    listRuns(principal: ApiPrincipal, limit: number): Promise<ServerRunRecord[]>;
+    getRun(principal: ApiPrincipal, id: string): Promise<ServerRunRecord | null>;
+    /**
+     * Claim the oldest runnable job for a worker, exactly once.
+     *
+     * Postgres does this with `FOR UPDATE SKIP LOCKED`: the row is locked at SELECT time,
+     * and a competing transaction skips past it to the next candidate. SQLite has no row
+     * locks and no SKIP LOCKED - it has one write lock for the whole database - so the
+     * equivalent guarantee has to be built from what SQLite does have:
+     *
+     *   1. BEGIN IMMEDIATE takes the database's RESERVED write lock up front, rather than
+     *      at the first write the way a deferred transaction does. Two claimers therefore
+     *      serialise from their first statement, not from their UPDATE, which is what
+     *      closes the read-then-write race. A plain BEGIN would let both claimers run
+     *      their SELECT, both see the same row, and one of them fail late (or, in WAL
+     *      mode, succeed - both having decided they own the run).
+     *   2. The UPDATE claims BY ID and re-asserts the status predicate
+     *      (`AND status IN ('queued','retrying')`). A claim is only real if that statement
+     *      reports changes === 1. This makes exclusivity a property of the write itself
+     *      rather than a property of the surrounding transaction, so it holds even if the
+     *      isolation above were ever weakened.
+     *   3. A bounded retry moves to the next candidate when changes === 0, so losing a
+     *      race never reports "queue empty" while runnable work is sitting there.
+     *
+     * Not org-scoped, matching Postgres: a worker serves every org on the instance. The
+     * org boundary is enforced on the read paths a principal can reach.
+     */
+    claimNextRun(input: ClaimRunInput): Promise<ServerRunRecord | null>;
+    private claimOnce;
+    updateRun(id: string, patch: Partial<Pick<ServerRunRecord, "status" | "outputType" | "outputPreview" | "errorCode" | "errorMessage" | "startedAt" | "completedAt">>): Promise<ServerRunRecord | null>;
+    /**
+     * Generation-fenced transition: the WHERE re-asserts the caller's expected
+     * lease_generation, so a write from a worker whose claim was fenced (by a
+     * cancellation, or by a newer claim) reports zero rows and is refused.
+     *
+     * Unlike updateRun, the patch may also move lease_generation - that is how
+     * the cancel service fences the current worker. The fence bump and the
+     * status move land in the same statement, so there is no instant where the
+     * status says cancelled and the generation still admits the old worker.
+     */
+    transitionRun(id: string, patch: RunTransitionPatch, expectedGeneration: number): Promise<ServerRunRecord | null>;
+    appendLog(id: string, orgId: string, level: ServerRunLog["level"], message: string): Promise<ServerRunLog>;
+    listLogs(principal: ApiPrincipal, id: string): Promise<ServerRunLog[]>;
+    addArtifact(artifact: Omit<ServerArtifact, "createdAt">): Promise<ServerArtifact>;
+    listArtifacts(principal: ApiPrincipal, id: string): Promise<ServerArtifact[]>;
+    getArtifact(principal: ApiPrincipal, id: string, artifact: string): Promise<ServerArtifact | null>;
+    publishSkill(input: PublishSkillInput): Promise<ServerSkillRecord>;
+    listSkills(principal: ApiPrincipal): Promise<ServerSkillRecord[]>;
+    getSkill(principal: ApiPrincipal, slug: string): Promise<ServerSkillRecord | null>;
+    updateSkill(principal: ApiPrincipal, slug: string, patch: UpdateSkillPatch, expectedRevisionId?: string): Promise<ServerSkillRecord | null>;
+    deleteSkill(principal: ApiPrincipal, slug: string, tombstoneWindowMs: number): Promise<ServerSkillRecord | null>;
+    purgeExpiredTombstones(principal: ApiPrincipal): Promise<ServerSkillRecord[]>;
+    getSkillBundle(principal: ApiPrincipal, sha256: string): Promise<ServerSkillBundle | null>;
+    pinSkill(principal: ApiPrincipal, slug: string, metadata?: Record<string, unknown>): Promise<ServerPin>;
+    unpinSkill(principal: ApiPrincipal, slug: string): Promise<boolean>;
+    listPins(principal: ApiPrincipal): Promise<ServerPin[]>;
+    listTags(principal: ApiPrincipal): Promise<string[]>;
+    listSkillsByTag(principal: ApiPrincipal, tag: string): Promise<ServerSkillRecord[]>;
+    listPinsByTag(principal: ApiPrincipal, tag: string): Promise<ServerPin[]>;
+    listPublishedSlugs(principal: ApiPrincipal): Promise<string[]>;
+    /**
+     * Drop a bundle no remaining skill in the org points at.
+     *
+     * The reference count is over skills_registry rather than a stored counter: a counter
+     * would be a second source of truth for something one COUNT(*) answers exactly, and a
+     * drifted counter either leaks blobs forever or deletes a bundle still in use.
+     */
+    private collectOrphanBundle;
+    private get;
+    private all;
+    private rollbackQuietly;
+}
+/**
+ * Apply pending migrations/sqlite/*.sql to an open database.
+ *
+ * The applied-version key is the file's basename, identical to the Postgres migrator's,
+ * so moving migrations/0001_*.sql into migrations/postgres/ did not orphan any database
+ * that had already applied it.
+ */
+export declare function applySqliteMigrations(db: Database, migrationsDir?: string): string[];

package/dist/server/store-fixtures.d.ts

@@ -0,0 +1,25 @@
+import type { ApiPrincipal, SkillsProductStore } from "./types.js";
+export declare const TEST_DATABASE_URL_ENV = "HASNA_SKILLS_TEST_DATABASE_URL";
+export interface SeedApiKey {
+    token: string;
+    principal: Partial<ApiPrincipal>;
+}
+export interface StoreFixture {
+    store: SkillsProductStore;
+    /** True when the server must be told it is allowed to run on this store. */
+    allowEphemeralStore: boolean;
+    close(): Promise<void>;
+}
+export interface StoreBackendFixture {
+    name: string;
+    create(seed?: SeedApiKey[]): Promise<StoreFixture>;
+}
+/** Human-readable reasons a backend is absent from the current run. */
+export declare function storeBackendNotices(): string[];
+/**
+ * Every backend testable in this environment.
+ *
+ * Async because Postgres availability can only be established by connecting; a
+ * top-level await in the test file keeps that out of the describe bodies.
+ */
+export declare function resolveStoreBackends(): Promise<StoreBackendFixture[]>;

package/dist/server/store.d.ts

@@ -0,0 +1,170 @@
+import type { ApiPrincipal, ClaimRunInput, CreateRunInput, PublishSkillInput, RunTransitionPatch, ServerArtifact, ServerPin, ServerRunLog, ServerRunRecord, ServerSkillBundle, ServerSkillRecord, SkillsProductStore, StoreBackendInfo, UpdateSkillPatch } from "./types.js";
+import { type SqliteStoreOptions } from "./sqlite-store.js";
+export declare function createArtifactId(): string;
+export interface StoreOptions {
+    databaseUrl?: string;
+    bootstrapApiKey?: string;
+    /** SQLite tuning, forwarded when the resolved target is SQLite. */
+    sqlite?: SqliteStoreOptions;
+}
+/**
+ * Build the store an operator's configuration asks for.
+ *
+ * The old body was `options.databaseUrl ? Postgres : Memory`, which meant that the
+ * single most common way to start this server - run it with nothing set - produced a
+ * process that looked healthy and forgot everything on restart. There is no longer any
+ * input that yields a non-durable store by accident:
+ *
+ *   - a postgres:// URL         -> Postgres, and a failure to reach it is fatal here
+ *   - a sqlite path / file: URL -> SQLite at that path, migrated on open
+ *   - nothing at all            -> SQLite at ~/.hasna/skills/server.db, migrated on open
+ *   - "memory:" or ":memory:"   -> non-durable, and only because it was named
+ *   - anything else             -> throws, naming what is supported
+ */
+export declare function createStore(options?: StoreOptions): Promise<SkillsProductStore>;
+export declare class MemorySkillsStore implements SkillsProductStore {
+    readonly backend: StoreBackendInfo;
+    private apiKeys;
+    private runs;
+    private logs;
+    private artifacts;
+    private idempotency;
+    private skills;
+    private bundles;
+    private pins;
+    constructor(apiKeys?: Array<{
+        token: string;
+        principal?: Partial<ApiPrincipal>;
+    }>);
+    addApiKey(token: string, principal?: Partial<ApiPrincipal>): ApiPrincipal;
+    ensureBootstrapApiKey(token: string, principal?: Partial<ApiPrincipal>): Promise<void>;
+    authenticateApiKeyHash(hash: string): Promise<ApiPrincipal | null>;
+    createRun(input: CreateRunInput): Promise<ServerRunRecord>;
+    listRuns(principal: ApiPrincipal, limit: number): Promise<ServerRunRecord[]>;
+    getRun(principal: ApiPrincipal, runId: string): Promise<ServerRunRecord | null>;
+    /**
+     * Exclusive only by accident: nothing here takes a lock, and it is safe purely
+     * because the read and the write happen in one synchronous turn of a single event
+     * loop. That is not a claiming strategy, it is a property of there being exactly one
+     * process and one Map. It is left as-is because this store is now explicitly
+     * non-durable and test-only - the durable backends implement claiming properly
+     * (Postgres via FOR UPDATE SKIP LOCKED, SQLite via BEGIN IMMEDIATE plus a conditional
+     * claim by id). Do not use this as the model for a new backend.
+     *
+     * startedAt is preserved on re-claim to match both durable backends' COALESCE.
+     */
+    claimNextRun(_input: ClaimRunInput): Promise<ServerRunRecord | null>;
+    updateRun(runId: string, patch: Partial<Pick<ServerRunRecord, "status" | "outputType" | "outputPreview" | "errorCode" | "errorMessage" | "startedAt" | "completedAt">>): Promise<ServerRunRecord | null>;
+    /**
+     * Fenced transition. The memory store's exclusivity is one event-loop turn,
+     * which makes the read-then-check atomic by construction; the generation
+     * predicate is still re-asserted so the semantics match the SQL backends.
+     */
+    transitionRun(runId: string, patch: RunTransitionPatch, expectedGeneration: number): Promise<ServerRunRecord | null>;
+    appendLog(runId: string, orgId: string, level: ServerRunLog["level"], message: string): Promise<ServerRunLog>;
+    listLogs(principal: ApiPrincipal, runId: string): Promise<ServerRunLog[]>;
+    addArtifact(artifact: Omit<ServerArtifact, "createdAt">): Promise<ServerArtifact>;
+    listArtifacts(principal: ApiPrincipal, runId: string): Promise<ServerArtifact[]>;
+    getArtifact(principal: ApiPrincipal, runId: string, id: string): Promise<ServerArtifact | null>;
+    publishSkill(input: PublishSkillInput): Promise<ServerSkillRecord>;
+    listSkills(principal: ApiPrincipal): Promise<ServerSkillRecord[]>;
+    getSkill(principal: ApiPrincipal, slug: string): Promise<ServerSkillRecord | null>;
+    updateSkill(principal: ApiPrincipal, slug: string, patch: UpdateSkillPatch, expectedRevisionId?: string): Promise<ServerSkillRecord | null>;
+    deleteSkill(principal: ApiPrincipal, slug: string, tombstoneWindowMs: number): Promise<ServerSkillRecord | null>;
+    purgeExpiredTombstones(principal: ApiPrincipal): Promise<ServerSkillRecord[]>;
+    getSkillBundle(principal: ApiPrincipal, sha256: string): Promise<ServerSkillBundle | null>;
+    pinSkill(principal: ApiPrincipal, slug: string, metadata?: Record<string, unknown>): Promise<ServerPin>;
+    unpinSkill(principal: ApiPrincipal, slug: string): Promise<boolean>;
+    listPins(principal: ApiPrincipal): Promise<ServerPin[]>;
+    listTags(principal: ApiPrincipal): Promise<string[]>;
+    listSkillsByTag(principal: ApiPrincipal, tag: string): Promise<ServerSkillRecord[]>;
+    listPinsByTag(principal: ApiPrincipal, tag: string): Promise<ServerPin[]>;
+    listPublishedSlugs(principal: ApiPrincipal): Promise<string[]>;
+    private collectOrphanBundle;
+    private patchRun;
+}
+export declare class PostgresSkillsStore implements SkillsProductStore {
+    readonly backend: StoreBackendInfo;
+    private sql;
+    constructor(databaseUrl: string);
+    /**
+     * Bun's SQL client connects lazily, so constructing this store proves nothing about
+     * the database being there. Without an explicit probe, a wrong host or a down
+     * instance produced a server that started, answered /health with ok:true, and 500ed
+     * on the first API call.
+     *
+     * The error deliberately carries no URL: a Postgres URL is a credential, the driver's
+     * own messages sometimes echo it, and this string ends up in logs.
+     */
+    verifyConnectivity(): Promise<void>;
+    /**
+     * Give rows written before migration 0004 a real content revision id.
+     *
+     * The migration adds revision_id with DEFAULT '', which would make If-Match vacuous
+     * for legacy rows (every stale client matches the same empty string). This replaces
+     * the marker with a content sha, idempotently: new code always writes a full id, so
+     * the marker never reappears and the sweep costs one index scan on later opens.
+     */
+    private backfillLegacyRevisions;
+    close(): Promise<void>;
+    ensureBootstrapApiKey(token: string, principal?: Partial<ApiPrincipal>): Promise<void>;
+    authenticateApiKeyHash(hash: string): Promise<ApiPrincipal | null>;
+    /**
+     * Run a callback under an RLS tenant or worker context, on one pooled
+     * connection, for the duration of one transaction only.
+     *
+     * Migration 0003 arms RLS on skills_runs and skills_artifacts: a statement
+     * whose session has no `app.skills_org_id` and no `app.skills_claim_context`
+     * sees zero rows. SET LOCAL (the `true` third argument) confines the setting
+     * to this transaction, which is what keeps one pooled connection from
+     * carrying tenant A's context into tenant B's next request - a session-wide
+     * SET would be exactly the cross-tenant leak RLS exists to prevent.
+     */
+    private withContext;
+    createRun(input: CreateRunInput): Promise<ServerRunRecord>;
+    listRuns(principal: ApiPrincipal, limit: number): Promise<ServerRunRecord[]>;
+    getRun(principal: ApiPrincipal, runId: string): Promise<ServerRunRecord | null>;
+    claimNextRun(input: ClaimRunInput): Promise<ServerRunRecord | null>;
+    updateRun(runId: string, patch: Partial<Pick<ServerRunRecord, "status" | "outputType" | "outputPreview" | "errorCode" | "errorMessage" | "startedAt" | "completedAt">>): Promise<ServerRunRecord | null>;
+    /**
+     * Generation-fenced transition. Same semantics as the SQLite twin: the WHERE
+     * re-asserts lease_generation, and a stale worker gets StaleLeaseGenerationError
+     * instead of silently overwriting a cancelled or re-claimed run.
+     */
+    transitionRun(runId: string, patch: RunTransitionPatch, expectedGeneration: number): Promise<ServerRunRecord | null>;
+    /**
+     * Append a log line, retrying when another writer took the sequence number first.
+     *
+     * This was `SELECT MAX(sequence)+1` and then a separate `INSERT`, with an await in
+     * between. Measured with five concurrent appendLog calls on one run: one succeeded and
+     * four threw `duplicate key value violates unique constraint`, which executeRun's catch
+     * turns into a failed run - a skill killed by its own logging.
+     *
+     * Folding the MAX into the INSERT helps but does not fix it: under READ COMMITTED each
+     * statement takes its own snapshot, so concurrent inserts still compute the same MAX
+     * (measured: 2 of 5 succeeded). SQLite has one writer and needs no retry; Postgres does,
+     * so the loop lives here rather than in shared code. Bounded, and only ever retried for
+     * a uniqueness conflict - any other error propagates on the first attempt.
+     */
+    appendLog(runId: string, orgId: string, level: ServerRunLog["level"], message: string): Promise<ServerRunLog>;
+    listLogs(principal: ApiPrincipal, runId: string): Promise<ServerRunLog[]>;
+    addArtifact(artifact: Omit<ServerArtifact, "createdAt">): Promise<ServerArtifact>;
+    listArtifacts(principal: ApiPrincipal, runId: string): Promise<ServerArtifact[]>;
+    getArtifact(principal: ApiPrincipal, runId: string, artifactId: string): Promise<ServerArtifact | null>;
+    publishSkill(input: PublishSkillInput): Promise<ServerSkillRecord>;
+    listSkills(principal: ApiPrincipal): Promise<ServerSkillRecord[]>;
+    getSkill(principal: ApiPrincipal, slug: string): Promise<ServerSkillRecord | null>;
+    updateSkill(principal: ApiPrincipal, slug: string, patch: UpdateSkillPatch, expectedRevisionId?: string): Promise<ServerSkillRecord | null>;
+    deleteSkill(principal: ApiPrincipal, slug: string, tombstoneWindowMs: number): Promise<ServerSkillRecord | null>;
+    purgeExpiredTombstones(principal: ApiPrincipal): Promise<ServerSkillRecord[]>;
+    getSkillBundle(principal: ApiPrincipal, sha256: string): Promise<ServerSkillBundle | null>;
+    pinSkill(principal: ApiPrincipal, slug: string, metadata?: Record<string, unknown>): Promise<ServerPin>;
+    unpinSkill(principal: ApiPrincipal, slug: string): Promise<boolean>;
+    listPins(principal: ApiPrincipal): Promise<ServerPin[]>;
+    listTags(principal: ApiPrincipal): Promise<string[]>;
+    listSkillsByTag(principal: ApiPrincipal, tag: string): Promise<ServerSkillRecord[]>;
+    listPinsByTag(principal: ApiPrincipal, tag: string): Promise<ServerPin[]>;
+    listPublishedSlugs(principal: ApiPrincipal): Promise<string[]>;
+    /** Drop a bundle no remaining skill in the org points at. See the SQLite twin. */
+    private collectOrphanBundle;
+}