@hasna/skills 0.8.12 → 0.9.1

package/dist/server/runtime-policy.d.ts

@@ -1,5 +1,6 @@
 import type { EcsDispatcherConfig } from "../sdk/execution/dispatchers/ecs.js";
 import type { FrozenAdmission, AttemptRecord } from "../sdk/execution/types.js";
+import { type PureReviewedBundle } from "./runtime-pure-contract.js";
 export declare const RUNTIME_MAX_INPUT_BYTES = 100000;
 export declare const RUNTIME_MAX_BUNDLE_BYTES = 1000000;
 export declare const RUNTIME_MAX_ARTIFACT_BYTES = 2000000;
@@ -9,11 +10,12 @@ export interface RuntimeConfig extends EcsDispatcherConfig {
     imageDigest: string;
     apiOrigin: string;
     /** Only independently reviewed exact bundles enter this first credential-free lane. */
-    reviewedBundles: {
+    reviewedBundles: ({
         slug: "pdf-generate";
         version: string;
         sha256: string;
-    }[];
+        executionContract?: never;
+    } | PureReviewedBundle)[];
 }
 export declare function readRuntimeConfig(env?: Record<string, string | undefined>): RuntimeConfig | null;
 export declare function runtimeInput(value: unknown): {

package/dist/server/runtime-pure-contract.d.ts

@@ -0,0 +1,51 @@
+/** Trusted pure interface; publishing a skill never grants admission to it. */
+import { type SkillBundleEntry } from "../lib/skill-bundle.js";
+import type { FrozenAdmission, PureExecutionContract } from "../sdk/execution/types.js";
+export declare const PURE_DESCRIPTOR: Readonly<{
+    id: "regex-test.v1";
+    runtime: "bun";
+    adapter: "skills-input-json.v1";
+    input: Readonly<{
+        patternBytes: 512;
+        textBytes: 4096;
+        totalBytes: 8192;
+        flags: "dgimsuvy";
+    }>;
+    output: "regex-matches.v1";
+    secrets: "none";
+    egress: "deny";
+    maxDurationMs: 5000;
+    maxMemoryMb: 512;
+    maxCpuUnits: 256;
+    stdoutBytes: 16384;
+    stderrBytes: 8192;
+    artifactsBytes: 0;
+}>;
+export declare const PURE_DESCRIPTOR_DIGEST: string;
+export declare const PURE_LIMITS: Readonly<{
+    maxDurationMs: 5000;
+    maxMemoryMb: 512;
+    maxCpuUnits: 256;
+    maxArtifactsBytes: 0;
+    maxConcurrency: 1;
+}>;
+export interface PureInput {
+    pattern: string;
+    text: string;
+    flags: string;
+}
+export interface PureReviewedBundle {
+    slug: string;
+    version: string;
+    sha256: string;
+    tenantId: string;
+    imageDigest: string;
+    executionContract: PureExecutionContract;
+}
+/** JSON.parse alone silently discards duplicate keys, including escaped spellings. */
+export declare function uniqueJson(text: string): unknown;
+export declare function pureInput(value: unknown): PureInput;
+export declare function assertPureContract(value: unknown): asserts value is PureExecutionContract;
+export declare function assertPureAdmission(a: FrozenAdmission): PureExecutionContract;
+export declare function inspectPureBundle(bytes: Uint8Array, contract: PureExecutionContract): Promise<SkillBundleEntry[]>;
+export declare function validatePureOutput(stdout: string, input: PureInput): void;

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

@@ -22,6 +22,10 @@ export interface RuntimeJob {
     input?: {
         content: string;
         title?: string;
+    } | {
+        pattern: string;
+        text: string;
+        flags: string;
     };
     bundleBase64?: string;
     result?: RuntimeResult;

package/dist/server/runtime-worker.d.ts

@@ -1,5 +1,6 @@
 #!/usr/bin/env bun
 import type { FrozenAdmission } from "../sdk/execution/types.js";
+import { type PureInput } from "./runtime-pure-contract.js";
 import type { RuntimeResult } from "./runtime-store.js";
 export interface RuntimeWork {
     admission: FrozenAdmission;
@@ -7,7 +8,7 @@ export interface RuntimeWork {
     input: {
         content: string;
         title?: string;
-    };
+    } | PureInput;
 }
 export interface SupervisorOptions {
     executable?: string;

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

@@ -2,6 +2,7 @@ import type { Database } from "bun:sqlite";
 import type { ApiPrincipal } from "./types.js";
 import type { SkillProfile, SkillSelection, StationSkillState, StationSkillStateInput } from "../types/skill-selection.js";
 export interface SkillSelectionStore {
+    profilesReferencingSkill(principal: ApiPrincipal, slug: string): Promise<string[]>;
     getProfile(principal: ApiPrincipal, id: string): Promise<SkillProfile | null>;
     /** null expected revision means create-only; null result means CAS conflict. */
     saveProfile(principal: ApiPrincipal, id: string, selections: SkillSelection[], expected: string | null): Promise<SkillProfile | null>;
@@ -15,6 +16,7 @@ export declare class MemorySkillSelectionStore implements SkillSelectionStore {
     private states;
     private key;
     getProfile(p: ApiPrincipal, id: string): Promise<SkillProfile | null>;
+    profilesReferencingSkill(p: ApiPrincipal, slug: string): Promise<string[]>;
     saveProfile(p: ApiPrincipal, id: string, selected: SkillSelection[], expected: string | null): Promise<SkillProfile | null>;
     getStationState(p: ApiPrincipal, id: string): Promise<StationSkillState | null>;
     saveStationState(p: ApiPrincipal, id: string, input: StationSkillStateInput): Promise<StationSkillState | null>;
@@ -22,15 +24,21 @@ export declare class MemorySkillSelectionStore implements SkillSelectionStore {
 export declare class SqliteSkillSelectionStore implements SkillSelectionStore {
     private db;
     constructor(db: Database);
+    profilesReferencingSkill(p: ApiPrincipal, slug: string): Promise<string[]>;
     getProfile(p: ApiPrincipal, id: string): Promise<SkillProfile | null>;
     saveProfile(p: ApiPrincipal, id: string, selected: SkillSelection[], expected: string | null): Promise<SkillProfile | null>;
     getStationState(p: ApiPrincipal, id: string): Promise<StationSkillState | null>;
     saveStationState(p: ApiPrincipal, id: string, input: StationSkillStateInput): Promise<StationSkillState | null>;
 }
 type Sql = (strings: TemplateStringsArray, ...values: unknown[]) => Promise<Row[]>;
+type SqlTransaction = Sql;
+interface SqlWithTransaction extends Sql {
+    begin<T>(fn: (tx: SqlTransaction) => Promise<T>): Promise<T>;
+}
 export declare class PostgresSkillSelectionStore implements SkillSelectionStore {
     private sql;
-    constructor(sql: Sql);
+    constructor(sql: SqlWithTransaction);
+    profilesReferencingSkill(p: ApiPrincipal, slug: string): Promise<string[]>;
     getProfile(p: ApiPrincipal, id: string): Promise<SkillProfile | null>;
     saveProfile(p: ApiPrincipal, id: string, selected: SkillSelection[], expected: string | null): Promise<SkillProfile | null>;
     getStationState(p: ApiPrincipal, id: string): Promise<StationSkillState | null>;

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 ServerSkillVersion, type SkillsProductStore } from "./types.js";
+import { type ApiPrincipal, type PublishSkillInput, type ServerPin, type ServerSkillRecord, type ServerSkillVersion, type SkillLifecyclePatch, 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>;
 /**
@@ -20,6 +20,7 @@ export declare class SkillRequestError extends Error {
     readonly code: string;
     constructor(status: number, code: string, message: string);
 }
+export declare function skillLifecyclePatch(body: Record<string, unknown>): SkillLifecyclePatch;
 /** SkillMeta shape for a published row, so a client can treat both kinds alike. */
 export declare function publishedSkillMeta(record: ServerSkillRecord): SkillMeta;
 /**

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

@@ -15,7 +15,7 @@ import { SqliteExecutionGrantStore } from "./execution-grant-store.js";
  */
 import { Database } from "bun:sqlite";
 import { SqliteSkillSelectionStore } from "./selection-store.js";
-import type { ApiPrincipal, ClaimRunInput, CreateRunInput, PublishSkillInput, RunTransitionPatch, ServerArtifact, ServerPin, ServerRunLog, ServerRunRecord, ServerSkillBundle, ServerSkillVersion, ServerSkillRecord, SkillsProductStore, StoreBackendInfo, UpdateSkillPatch } from "./types.js";
+import type { ApiPrincipal, ClaimRunInput, CreateRunInput, PublishSkillInput, RunTransitionPatch, ServerArtifact, ServerPin, ServerRunLog, ServerRunRecord, ServerSkillBundle, ServerSkillVersion, ApiKeyScopeUpdateResult, ServerSkillRecord, SkillLifecyclePatch, 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;
@@ -52,6 +52,7 @@ export declare class SqliteSkillsStore implements SkillsProductStore {
     close(): Promise<void>;
     ensureBootstrapApiKey(token: string, principal?: Partial<ApiPrincipal>): Promise<void>;
     authenticateApiKeyHash(hash: string): Promise<ApiPrincipal | null>;
+    updateApiKeyScopes(actor: ApiPrincipal, keyId: string, expectedScopes: string[], addScopes: string[]): Promise<ApiKeyScopeUpdateResult>;
     createRun(input: CreateRunInput): Promise<ServerRunRecord>;
     listRuns(principal: ApiPrincipal, limit: number): Promise<ServerRunRecord[]>;
     getRun(principal: ApiPrincipal, id: string): Promise<ServerRunRecord | null>;
@@ -102,6 +103,8 @@ export declare class SqliteSkillsStore implements SkillsProductStore {
     publishSkill(input: PublishSkillInput): Promise<ServerSkillRecord>;
     listSkills(principal: ApiPrincipal): Promise<ServerSkillRecord[]>;
     getSkill(principal: ApiPrincipal, slug: string): Promise<ServerSkillRecord | null>;
+    setSkillLifecycle(principal: ApiPrincipal, slug: string, patch: SkillLifecyclePatch, expectedRevisionId?: string): Promise<ServerSkillRecord | null>;
+    private getSkillSync;
     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[]>;

package/dist/server/store.d.ts

@@ -1,6 +1,7 @@
 import { MemoryExecutionGrantStore, PostgresExecutionGrantStore } from "./execution-grant-store.js";
 import { MemorySkillSelectionStore, PostgresSkillSelectionStore } from "./selection-store.js";
-import type { ApiPrincipal, ClaimRunInput, CreateRunInput, PublishSkillInput, RunTransitionPatch, ServerArtifact, ServerPin, ServerRunLog, ServerRunRecord, ServerSkillBundle, ServerSkillRecord, ServerSkillVersion, SkillsProductStore, StoreBackendInfo, UpdateSkillPatch } from "./types.js";
+import type { ApiPrincipal, ClaimRunInput, CreateRunInput, PublishSkillInput, RunTransitionPatch, ServerArtifact, ServerPin, ServerRunLog, ServerRunRecord, ServerSkillBundle, ServerSkillRecord, ServerSkillVersion, ApiKeyScopeUpdateResult, SkillsProductStore, StoreBackendInfo, UpdateSkillPatch } from "./types.js";
+import { type SkillLifecyclePatch } from "./types.js";
 import { type SqliteStoreOptions } from "./sqlite-store.js";
 export declare function createArtifactId(): string;
 export interface StoreOptions {
@@ -44,6 +45,7 @@ export declare class MemorySkillsStore implements SkillsProductStore {
     addApiKey(token: string, principal?: Partial<ApiPrincipal>): ApiPrincipal;
     ensureBootstrapApiKey(token: string, principal?: Partial<ApiPrincipal>): Promise<void>;
     authenticateApiKeyHash(hash: string): Promise<ApiPrincipal | null>;
+    updateApiKeyScopes(actor: ApiPrincipal, keyId: string, expectedScopes: string[], addScopes: string[]): Promise<ApiKeyScopeUpdateResult>;
     createRun(input: CreateRunInput): Promise<ServerRunRecord>;
     listRuns(principal: ApiPrincipal, limit: number): Promise<ServerRunRecord[]>;
     getRun(principal: ApiPrincipal, runId: string): Promise<ServerRunRecord | null>;
@@ -76,6 +78,7 @@ export declare class MemorySkillsStore implements SkillsProductStore {
     getSkillVersion(principal: ApiPrincipal, slug: string, version: string): Promise<ServerSkillVersion | null>;
     listSkills(principal: ApiPrincipal): Promise<ServerSkillRecord[]>;
     getSkill(principal: ApiPrincipal, slug: string): Promise<ServerSkillRecord | null>;
+    setSkillLifecycle(principal: ApiPrincipal, slug: string, patch: SkillLifecyclePatch, expectedRevisionId?: 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[]>;
@@ -118,6 +121,7 @@ export declare class PostgresSkillsStore implements SkillsProductStore {
     close(): Promise<void>;
     ensureBootstrapApiKey(token: string, principal?: Partial<ApiPrincipal>): Promise<void>;
     authenticateApiKeyHash(hash: string): Promise<ApiPrincipal | null>;
+    updateApiKeyScopes(actor: ApiPrincipal, keyId: string, expectedScopes: string[], addScopes: string[]): Promise<ApiKeyScopeUpdateResult>;
     /**
      * Run a callback under an RLS tenant or worker context, on one pooled
      * connection, for the duration of one transaction only.
@@ -163,6 +167,7 @@ export declare class PostgresSkillsStore implements SkillsProductStore {
     publishSkill(input: PublishSkillInput): Promise<ServerSkillRecord>;
     listSkills(principal: ApiPrincipal): Promise<ServerSkillRecord[]>;
     getSkill(principal: ApiPrincipal, slug: string): Promise<ServerSkillRecord | null>;
+    setSkillLifecycle(principal: ApiPrincipal, slug: string, patch: SkillLifecyclePatch, expectedRevisionId?: 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[]>;

package/dist/server/types.d.ts

@@ -45,6 +45,11 @@ export declare class SkillVersionExistsError extends Error {
     readonly attemptedSha256: string;
     constructor(slug: string, version: string, existingSha256: string, attemptedSha256: string);
 }
+export declare class SkillLifecycleConflictError extends Error {
+    readonly slug: string;
+    readonly profiles: string[];
+    constructor(slug: string, profiles: string[]);
+}
 export interface ApiPrincipal {
     apiKeyId: string;
     orgId: string;
@@ -55,6 +60,15 @@ export interface ApiPrincipal {
     role: string;
     scopes: string[];
 }
+export type ApiKeyScopeUpdateResult = {
+    kind: "updated";
+    scopes: string[];
+} | {
+    kind: "not_found";
+} | {
+    kind: "stale";
+    scopes: string[];
+};
 export interface ServerRunRecord {
     id: string;
     orgId: string;
@@ -162,6 +176,16 @@ export interface ServerSkillRecord {
      */
     tombstonedAt?: string;
     tombstonePurgeAfter?: string;
+    /** Catalog lifecycle state. Archived rows retain versions and bundles for explicit reads. */
+    lifecycle: "active" | "archived";
+    archivedAt?: string;
+    archiveReason?: string;
+    replacementSlug?: string;
+}
+export interface SkillLifecyclePatch {
+    lifecycle: "active" | "archived";
+    reason?: string;
+    replacementSlug?: string;
 }
 /**
  * Bundle bytes, addressed by their own digest.
@@ -313,6 +337,8 @@ export interface SkillsProductStore {
      */
     verifyConnectivity?(): Promise<void>;
     authenticateApiKeyHash(hash: string): Promise<ApiPrincipal | null>;
+    /** Guarded metadata-only scope admission for an existing key. */
+    updateApiKeyScopes?(actor: ApiPrincipal, keyId: string, expectedScopes: string[], addScopes: string[]): Promise<ApiKeyScopeUpdateResult>;
     ensureBootstrapApiKey?(token: string, principal?: Partial<ApiPrincipal>): Promise<void>;
     createRun(input: CreateRunInput): Promise<ServerRunRecord>;
     listRuns(principal: ApiPrincipal, limit: number): Promise<ServerRunRecord[]>;
@@ -350,6 +376,7 @@ export interface SkillsProductStore {
      * when the org has no skill by that slug, or when the row is tombstoned.
      */
     updateSkill(principal: ApiPrincipal, slug: string, patch: UpdateSkillPatch, expectedRevisionId?: string): Promise<ServerSkillRecord | null>;
+    setSkillLifecycle(principal: ApiPrincipal, slug: string, patch: SkillLifecyclePatch, expectedRevisionId?: string): Promise<ServerSkillRecord | null>;
     /**
      * Tombstone a skill instead of hard-deleting it (todos d061fcda): the row is stamped
      * tombstoned_at + tombstone_purge_after (now + tombstoneWindowMs) and kept, so reads

package/migrations/postgres/0010_skill_archive_lifecycle.sql

@@ -0,0 +1,5 @@
+ALTER TABLE skills_registry ADD COLUMN lifecycle text NOT NULL DEFAULT 'active' CHECK (lifecycle IN ('active','archived'));
+ALTER TABLE skills_registry ADD COLUMN archived_at timestamptz;
+ALTER TABLE skills_registry ADD COLUMN archive_reason text;
+ALTER TABLE skills_registry ADD COLUMN replacement_slug text;
+CREATE INDEX IF NOT EXISTS skills_registry_org_lifecycle_idx ON skills_registry (org_id, lifecycle, slug);

package/migrations/sqlite/0010_skill_archive_lifecycle.sql

@@ -0,0 +1,5 @@
+ALTER TABLE skills_registry ADD COLUMN lifecycle text NOT NULL DEFAULT 'active' CHECK (lifecycle IN ('active','archived'));
+ALTER TABLE skills_registry ADD COLUMN archived_at text;
+ALTER TABLE skills_registry ADD COLUMN archive_reason text;
+ALTER TABLE skills_registry ADD COLUMN replacement_slug text;
+CREATE INDEX IF NOT EXISTS skills_registry_org_lifecycle_idx ON skills_registry (org_id, lifecycle, slug);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/skills",
-  "version": "0.8.12",
+  "version": "0.9.1",
   "description": "Skills library for AI coding agents",
   "type": "module",
   "bin": {