@hasna/skills 0.1.72 → 0.2.1

package/dist/sdk/runs.d.ts

@@ -38,23 +38,7 @@ export declare const runAdmissionSchema: z.ZodObject<{
     skill: z.ZodString;
     status: z.ZodLiteral<"admitted">;
     createdAt: z.ZodString;
-}, "strip", z.ZodTypeAny, {
-    status: "admitted";
-    createdAt: string;
-    skill: string;
-    contractVersion: 1;
-    runId: string;
-    leaseGeneration: number;
-    attemptId: string;
-}, {
-    status: "admitted";
-    createdAt: string;
-    skill: string;
-    contractVersion: 1;
-    runId: string;
-    leaseGeneration: number;
-    attemptId: string;
-}>;
+}, z.core.$strip>;
 export type RunAdmission = z.infer<typeof runAdmissionSchema>;
 /** Lease: a worker has claimed the run. */
 export declare const runLeaseSchema: z.ZodObject<{
@@ -64,21 +48,7 @@ export declare const runLeaseSchema: z.ZodObject<{
     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.core.$strip>;
 export type RunLease = z.infer<typeof runLeaseSchema>;
 /** Terminal: the run reached a final state. */
 export declare const runTerminalSchema: z.ZodObject<{
@@ -87,28 +57,17 @@ export declare const runTerminalSchema: z.ZodObject<{
     attemptId: z.ZodString;
     leaseGeneration: z.ZodNumber;
     skill: z.ZodString;
-    status: z.ZodEnum<["succeeded", "failed", "cancelled", "expired"]>;
+    status: z.ZodEnum<{
+        cancelled: "cancelled";
+        failed: "failed";
+        succeeded: "succeeded";
+        expired: "expired";
+    }>;
     completedAt: z.ZodString;
-}, "strip", z.ZodTypeAny, {
-    status: "cancelled" | "failed" | "succeeded" | "expired";
-    skill: string;
-    completedAt: string;
-    contractVersion: 1;
-    runId: string;
-    leaseGeneration: number;
-    attemptId: string;
-}, {
-    status: "cancelled" | "failed" | "succeeded" | "expired";
-    skill: string;
-    completedAt: string;
-    contractVersion: 1;
-    runId: string;
-    leaseGeneration: number;
-    attemptId: string;
-}>;
+}, z.core.$strip>;
 export type RunTerminal = z.infer<typeof runTerminalSchema>;
 /** Any single protocol message, discriminated by `status`. */
-export declare const runProtocolSchema: z.ZodDiscriminatedUnion<"status", [z.ZodObject<{
+export declare const runProtocolSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     contractVersion: z.ZodLiteral<1>;
     runId: z.ZodString;
     attemptId: z.ZodString;
@@ -116,68 +75,27 @@ export declare const runProtocolSchema: z.ZodDiscriminatedUnion<"status", [z.Zod
     skill: z.ZodString;
     status: z.ZodLiteral<"admitted">;
     createdAt: z.ZodString;
-}, "strip", z.ZodTypeAny, {
-    status: "admitted";
-    createdAt: string;
-    skill: string;
-    contractVersion: 1;
-    runId: string;
-    leaseGeneration: number;
-    attemptId: string;
-}, {
-    status: "admitted";
-    createdAt: string;
-    skill: string;
-    contractVersion: 1;
-    runId: string;
-    leaseGeneration: number;
-    attemptId: string;
-}>, z.ZodObject<{
+}, z.core.$strip>, 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<{
+}, z.core.$strip>, 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"]>;
+    status: z.ZodEnum<{
+        cancelled: "cancelled";
+        failed: "failed";
+        succeeded: "succeeded";
+        expired: "expired";
+    }>;
     completedAt: z.ZodString;
-}, "strip", z.ZodTypeAny, {
-    status: "cancelled" | "failed" | "succeeded" | "expired";
-    skill: string;
-    completedAt: string;
-    contractVersion: 1;
-    runId: string;
-    leaseGeneration: number;
-    attemptId: string;
-}, {
-    status: "cancelled" | "failed" | "succeeded" | "expired";
-    skill: string;
-    completedAt: string;
-    contractVersion: 1;
-    runId: string;
-    leaseGeneration: number;
-    attemptId: string;
-}>]>;
+}, z.core.$strip>], "status">;
 export type RunProtocolMessage = z.infer<typeof runProtocolSchema>;
 /** Map the store's status vocabulary onto the protocol lifecycle. */
 export declare function protocolStateOf(status: ServerRunStatus): RunProtocolState;

package/dist/server/app.d.ts

@@ -1,8 +1,11 @@
 import { type GovernanceStore } from "../sdk/governance-store.js";
+import { ArtifactStorage } from "./artifact-storage.js";
 import { type SkillsServerConfig } from "./config.js";
 import { type MemorySkillsStore } from "./store.js";
 import { type SkillsProductStore } from "./types.js";
 export interface SkillsServerOptions {
+    /** Overrides the artifact storage (tests inject an in-memory S3 stand-in). */
+    artifactStorage?: ArtifactStorage;
     config?: Partial<SkillsServerConfig>;
     store?: SkillsProductStore;
     /** Lifecycle ledger and ceiling reads for governance surfaces (cancellation). Defaults to the store's database. */

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

@@ -1,3 +1,4 @@
+import { DeleteObjectCommand, GetObjectCommand, PutObjectCommand } from "@aws-sdk/client-s3";
 import { type OwnedBytes } from "../lib/skill-bundle.js";
 import type { BlobStorageKind, ServerArtifact, ServerRunRecord, ServerSkillBundle } from "./types.js";
 export interface ArtifactBody {
@@ -5,10 +6,18 @@ export interface ArtifactBody {
     bodyText: string;
     contentType: string;
 }
+/** The slice of the AWS client the storage uses; injectable so tests can stand in an in-memory bucket. */
+export interface S3ClientLike {
+    send(command: PutObjectCommand | GetObjectCommand | DeleteObjectCommand): Promise<{
+        Body?: unknown;
+    }>;
+}
 export interface ArtifactStorageOptions {
     bucket?: string;
     prefix?: string;
     region?: string;
+    /** Overrides the real S3 client (tests). Ignored when no bucket is configured. */
+    client?: S3ClientLike;
 }
 export declare class ArtifactStorage {
     private bucket?;
@@ -98,5 +107,34 @@ export declare class ArtifactStorage {
      */
     moveToQuarantine(artifact: ServerArtifact): Promise<string | null>;
     private keyFor;
+    /**
+     * Version-addressed copy of a published bundle plus its manifest (hasna/apps#1630):
+     *   <prefix>/skills/<org>/<slug>/<version>/bundle.tar.gz
+     *   <prefix>/skills/<org>/<slug>/<version>/manifest.json
+     * The content-addressed object under bundles/ stays the read path (dedupe); these keys
+     * are the durable, browsable history and are never deleted by orphan collection.
+     *
+     * RETENTION (hasna/apps#1671): these objects accumulate without bound by design — every
+     * version keeps a full copy — so the bucket lifecycle is the retention story, not the
+     * store. The intended rule (operated in the bucket's lifecycle config, outside this
+     * repository): expire `<prefix>/skills/` objects older than N days per the slot policy,
+     * while `<prefix>/bundles/` (content-addressed, deduped across versions and slugs) is
+     * NEVER expired by lifecycle — only the reference-guarded delete path removes those,
+     * because one object can serve many versions. A busy org that pushes thousands of
+     * versions should pair the lifecycle rule with a documented cap on retained versions
+     * per slug (e.g. the newest K, pruned by a maintenance job that deletes the version row
+     * and its two objects together); row deletion alone would strand the objects.
+     * Returns the placement recorded on the version row; in db mode nothing is written.
+     */
+    putVersionObjects(orgId: string, slug: string, version: string, bytes: OwnedBytes, manifest: Record<string, unknown>, contentType?: string): Promise<{
+        storageKind: BlobStorageKind;
+        storageKey?: string;
+    }>;
+    /** Where putVersionObjects WOULD place a version, without writing: recorded on the row before the objects exist. */
+    versionPlacement(orgId: string, slug: string, version: string): {
+        storageKind: BlobStorageKind;
+        storageKey?: string;
+    };
+    versionKeyFor(orgId: string, slug: string, version: string, file: string): string;
     private bundleKeyFor;
 }

package/dist/server/config.d.ts

@@ -3,6 +3,8 @@ export interface SkillsServerConfig {
     port: number;
     databaseUrl?: string;
     bootstrapApiKey?: string;
+    /** Publish the bundled corpus as versioned skills on boot (default on; set HASNA_SKILLS_SEED_BUNDLED_CORPUS=0 to skip). */
+    seedBundledCorpus: boolean;
     artifactBucket?: string;
     artifactPrefix: string;
     inlineWorker: boolean;

package/dist/server/rows.d.ts

@@ -1,4 +1,4 @@
-import type { ServerArtifact, ServerPin, ServerRunLog, ServerRunRecord, ServerSkillBundle, ServerSkillRecord } from "./types.js";
+import type { ServerSkillVersion, 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.
@@ -22,3 +22,4 @@ export declare function rowToSkillBundle(row: Record<string, unknown>): ServerSk
 export declare function parseJsonObject(value: unknown): Record<string, unknown>;
 export declare function parseJsonArray(value: unknown): string[];
 export declare function dateString(value: unknown): string;
+export declare function rowToSkillVersion(row: Record<string, unknown>): ServerSkillVersion;

package/dist/server/seed-bundled.d.ts

@@ -0,0 +1,20 @@
+import type { ArtifactStorage } from "./artifact-storage.js";
+import type { ApiPrincipal, SkillsProductStore } from "./types.js";
+export interface SeedBundledCorpusOptions {
+    store: SkillsProductStore;
+    artifactStorage: ArtifactStorage;
+    principal: ApiPrincipal;
+    /** Version recorded for every seeded skill. Defaults to the package version. */
+    version?: string;
+    log?: (line: string) => void;
+}
+export interface SeedBundledCorpusResult {
+    version: string;
+    seeded: string[];
+    skipped: string[];
+    failed: Array<{
+        slug: string;
+        error: string;
+    }>;
+}
+export declare function seedBundledCorpus(options: SeedBundledCorpusOptions): Promise<SeedBundledCorpusResult>;

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

@@ -2,7 +2,7 @@ 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";
+import { type ApiPrincipal, type PublishSkillInput, type ServerPin, type ServerSkillRecord, type ServerSkillVersion, 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>;
 /**
@@ -22,7 +22,15 @@ export declare class SkillRequestError extends Error {
 }
 /** 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>;
+/**
+ * SkillMeta shape for a published row, plus a payload-level "alreadyPublished" flag:
+ * true when the accepted publish found the version already recorded with the same
+ * digest (an idempotent re-push), so the CLI can distinguish "published as X" from
+ * "already published as X" (hasna/apps#1671).
+ */
+export declare function publishedPayload(record: ServerSkillRecord, opts?: {
+    alreadyPublished?: boolean;
+}): 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
@@ -143,7 +151,10 @@ interface ParsedPublish {
  * 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>;
+export declare function storePublishedSkill(store: SkillsProductStore, artifactStorage: ArtifactStorage, principal: ApiPrincipal, parsed: ParsedPublish, expectedRevisionId?: string): Promise<{
+    record: ServerSkillRecord;
+    alreadyPublished: boolean;
+}>;
 /**
  * Tombstone a published skill (todos d061fcda): the row survives with a tombstone
  * marker for `tombstoneWindowMs`, so reads answer 410 and a pulling client can
@@ -167,4 +178,21 @@ export declare function readPublishedBundle(store: SkillsProductStore, artifactS
 }>;
 export declare function assertPublishableSlug(slug: string): void;
 export declare function assertSha256(value: string): void;
+/**
+ * Versions surface (hasna/apps#1630).
+ *
+ * GET /api/v1/skills/:slug/versions           -> { slug, current, versions: [...] }
+ * GET /api/v1/skills/:slug/versions/:version  -> one version's manifest
+ * GET /api/v1/skills/:slug/versions/:version/bundle -> the exact bytes of that version
+ *
+ * The registry row is the "current" pointer; a version's bytes come from the
+ * content-addressed bundle store so db-mode instances serve history exactly like S3 ones.
+ */
+export declare function skillVersionPayload(version: ServerSkillVersion, currentSha?: string): Record<string, unknown>;
+export declare function listSkillVersionsPayload(store: SkillsProductStore, principal: ApiPrincipal, slug: string): Promise<Record<string, unknown>>;
+export declare function readSkillVersion(store: SkillsProductStore, principal: ApiPrincipal, slug: string, version: string): Promise<ServerSkillVersion>;
+export declare function readSkillVersionBundle(store: SkillsProductStore, artifactStorage: ArtifactStorage, principal: ApiPrincipal, slug: string, version: string): Promise<{
+    version: ServerSkillVersion;
+    bytes: OwnedBytes;
+}>;
 export {};

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

@@ -13,7 +13,7 @@
  * 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";
+import type { ApiPrincipal, ClaimRunInput, CreateRunInput, PublishSkillInput, RunTransitionPatch, ServerArtifact, ServerPin, ServerRunLog, ServerRunRecord, ServerSkillBundle, ServerSkillVersion, 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;
@@ -102,6 +102,8 @@ export declare class SqliteSkillsStore implements SkillsProductStore {
     deleteSkill(principal: ApiPrincipal, slug: string, tombstoneWindowMs: number): Promise<ServerSkillRecord | null>;
     purgeExpiredTombstones(principal: ApiPrincipal): Promise<ServerSkillRecord[]>;
     getSkillBundle(principal: ApiPrincipal, sha256: string): Promise<ServerSkillBundle | null>;
+    listSkillVersions(principal: ApiPrincipal, slug: string): Promise<ServerSkillVersion[]>;
+    getSkillVersion(principal: ApiPrincipal, slug: string, version: string): Promise<ServerSkillVersion | null>;
     pinSkill(principal: ApiPrincipal, slug: string, metadata?: Record<string, unknown>): Promise<ServerPin>;
     unpinSkill(principal: ApiPrincipal, slug: string): Promise<boolean>;
     listPins(principal: ApiPrincipal): Promise<ServerPin[]>;

package/dist/server/store.d.ts

@@ -1,4 +1,4 @@
-import type { ApiPrincipal, ClaimRunInput, CreateRunInput, PublishSkillInput, RunTransitionPatch, ServerArtifact, ServerPin, ServerRunLog, ServerRunRecord, ServerSkillBundle, ServerSkillRecord, SkillsProductStore, StoreBackendInfo, UpdateSkillPatch } from "./types.js";
+import type { ApiPrincipal, ClaimRunInput, CreateRunInput, PublishSkillInput, RunTransitionPatch, ServerArtifact, ServerPin, ServerRunLog, ServerRunRecord, ServerSkillBundle, ServerSkillRecord, ServerSkillVersion, SkillsProductStore, StoreBackendInfo, UpdateSkillPatch } from "./types.js";
 import { type SqliteStoreOptions } from "./sqlite-store.js";
 export declare function createArtifactId(): string;
 export interface StoreOptions {
@@ -31,6 +31,7 @@ export declare class MemorySkillsStore implements SkillsProductStore {
     private idempotency;
     private skills;
     private bundles;
+    private versions;
     private pins;
     constructor(apiKeys?: Array<{
         token: string;
@@ -67,6 +68,8 @@ export declare class MemorySkillsStore implements SkillsProductStore {
     listArtifacts(principal: ApiPrincipal, runId: string): Promise<ServerArtifact[]>;
     getArtifact(principal: ApiPrincipal, runId: string, id: string): Promise<ServerArtifact | null>;
     publishSkill(input: PublishSkillInput): Promise<ServerSkillRecord>;
+    listSkillVersions(principal: ApiPrincipal, slug: string): Promise<ServerSkillVersion[]>;
+    getSkillVersion(principal: ApiPrincipal, slug: string, version: string): Promise<ServerSkillVersion | null>;
     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>;
@@ -158,6 +161,8 @@ export declare class PostgresSkillsStore implements SkillsProductStore {
     deleteSkill(principal: ApiPrincipal, slug: string, tombstoneWindowMs: number): Promise<ServerSkillRecord | null>;
     purgeExpiredTombstones(principal: ApiPrincipal): Promise<ServerSkillRecord[]>;
     getSkillBundle(principal: ApiPrincipal, sha256: string): Promise<ServerSkillBundle | null>;
+    listSkillVersions(principal: ApiPrincipal, slug: string): Promise<ServerSkillVersion[]>;
+    getSkillVersion(principal: ApiPrincipal, slug: string, version: string): Promise<ServerSkillVersion | null>;
     pinSkill(principal: ApiPrincipal, slug: string, metadata?: Record<string, unknown>): Promise<ServerPin>;
     unpinSkill(principal: ApiPrincipal, slug: string): Promise<boolean>;
     listPins(principal: ApiPrincipal): Promise<ServerPin[]>;

package/dist/server/types.d.ts

@@ -31,6 +31,18 @@ export declare class SkillRevisionConflictError extends Error {
     readonly currentRevisionId: string | null;
     constructor(slug: string, expectedRevisionId: string | null | undefined, currentRevisionId: string | null);
 }
+/**
+ * A publish was refused because (org, slug, version) already exists with a DIFFERENT bundle
+ * digest. Versions are immutable (hasna/apps#1630): the same digest is idempotent, a new
+ * digest needs a new version. Carries the stored digest so the client can say which.
+ */
+export declare class SkillVersionExistsError extends Error {
+    readonly slug: string;
+    readonly version: string;
+    readonly existingSha256: string;
+    readonly attemptedSha256: string;
+    constructor(slug: string, version: string, existingSha256: string, attemptedSha256: string);
+}
 export interface ApiPrincipal {
     apiKeyId: string;
     orgId: string;
@@ -182,6 +194,24 @@ export interface ServerSkillBundle {
     bytes?: OwnedBytes;
     createdAt: string;
 }
+/**
+ * One immutable published version of a skill (hasna/apps#1630). The registry row is the
+ * mutable "current" pointer; these rows are the history: each (org, slug, version) exactly once,
+ * pointing at a content-addressed bundle that orphan collection must keep alive.
+ */
+export interface ServerSkillVersion {
+    orgId: string;
+    slug: string;
+    version: string;
+    bundleSha256: string;
+    bundleByteSize: number;
+    storageKind: BlobStorageKind;
+    storageKey?: string;
+    /** Files (path -> sha256), byte counts and provenance the publisher sent; never secret. */
+    manifest: Record<string, unknown>;
+    publishedByUserId?: string;
+    createdAt: string;
+}
 export interface PublishSkillInput {
     principal: ApiPrincipal;
     slug: string;
@@ -195,6 +225,16 @@ export interface PublishSkillInput {
     skillMd?: string;
     /** Omitted for a metadata-only publish or update. */
     bundle?: Omit<ServerSkillBundle, "orgId" | "createdAt">;
+    /**
+     * Publisher-supplied version manifest (file digests, provenance). Stored verbatim on the
+     * version row when `version` is set; ignored otherwise.
+     */
+    versionManifest?: Record<string, unknown>;
+    /** Version-addressed object key the API wrote (S3 mode); recorded on the version row. */
+    versionStorage?: {
+        storageKind: BlobStorageKind;
+        storageKey?: string;
+    };
     /**
      * Optimistic-concurrency guard (todos d061fcda): the revision_id (ETag) the writer
      * read. A publish against an existing, LIVE row requires the guard to name that row's
@@ -320,6 +360,9 @@ export interface SkillsProductStore {
      */
     purgeExpiredTombstones(principal: ApiPrincipal): Promise<ServerSkillRecord[]>;
     getSkillBundle(principal: ApiPrincipal, sha256: string): Promise<ServerSkillBundle | null>;
+    /** Every published version of a slug, newest first (hasna/apps#1630). */
+    listSkillVersions(principal: ApiPrincipal, slug: string): Promise<ServerSkillVersion[]>;
+    getSkillVersion(principal: ApiPrincipal, slug: string, version: string): Promise<ServerSkillVersion | null>;
     pinSkill(principal: ApiPrincipal, slug: string, metadata?: Record<string, unknown>): Promise<ServerPin>;
     /** False when this principal has no pin by that slug. */
     unpinSkill(principal: ApiPrincipal, slug: string): Promise<boolean>;