@hasna/skills 0.1.63 → 0.1.64

package/dist/server/app.d.ts

@@ -1,6 +1,6 @@
 import { type SkillsServerConfig } from "./config.js";
 import { type MemorySkillsStore } from "./store.js";
-import type { SkillsProductStore } from "./types.js";
+import { type SkillsProductStore } from "./types.js";
 export interface SkillsServerOptions {
     config?: Partial<SkillsServerConfig>;
     store?: SkillsProductStore;

package/dist/server/config.d.ts

@@ -9,8 +9,12 @@ export interface SkillsServerConfig {
     /**
      * 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.
+     * they pulled are the bytes this server decided to serve. Never logged or printed.
+     *
+     * Canonical env name: HASNA_SKILLS_API_SIGNING_KEY — the name the production deploy
+     * mounts (infra-live hasna-app module, infra/apps/skills/prod/main.tf). The legacy
+     * HASNA_SKILLS_SIGNING_KEY is retained as a backwards-compatible alias; the canonical
+     * name wins when both are set. Decision record: todos ee1904ca, plan 8022d27f.
      */
     bundleSigningKey?: string;
     requestBodyLimitBytes: number;
@@ -25,6 +29,12 @@ export interface SkillsServerConfig {
      * body is buffered, and the JSON cap is untouched.
      */
     skillBundleLimitBytes: number;
+    /**
+     * How long a deleted skill answers 410 with a tombstone marker before it is purged
+     * (todos d061fcda). Within the window a client's pull can reconcile (remove its local
+     * copy); after it, the row and its bundle are gone and the slug is an ordinary 404.
+     */
+    tombstoneWindowMs: number;
     publicBaseUrl: string;
     nodeEnv: string;
     /**

package/dist/server/rows.d.ts

@@ -1,4 +1,4 @@
-import type { ServerArtifact, ServerRunLog, ServerRunRecord, ServerSkillBundle, ServerSkillRecord } from "./types.js";
+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.
@@ -17,6 +17,7 @@ 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[];

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

@@ -2,7 +2,19 @@ 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, PublishSkillInput, ServerSkillRecord, SkillsProductStore } from "./types.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;
@@ -11,6 +23,34 @@ 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>;
+/**
+ * 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.
  *
@@ -19,8 +59,66 @@ export declare function publishedPayload(record: ServerSkillRecord): Record<stri
  * bundled `deploy-notes` there.
  */
 export declare function listMergedSkills(store: SkillsProductStore, principal: ApiPrincipal): Promise<Record<string, unknown>[]>;
-export declare function getMergedSkill(store: SkillsProductStore, principal: ApiPrincipal, slug: string): Promise<Record<string, unknown> | null>;
-export declare function getMergedSkillMd(store: SkillsProductStore, principal: ApiPrincipal, slug: string): Promise<string | null>;
+/**
+ * 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;
@@ -45,11 +143,15 @@ 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): Promise<ServerSkillRecord>;
+export declare function storePublishedSkill(store: SkillsProductStore, artifactStorage: ArtifactStorage, principal: ApiPrincipal, parsed: ParsedPublish, expectedRevisionId?: string): Promise<ServerSkillRecord>;
 /**
- * Delete a published skill, and the stored object behind it when nothing else needs it.
+ * 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): Promise<boolean>;
+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.

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, ServerRunLog, ServerRunRecord, ServerSkillBundle, ServerSkillRecord, SkillsProductStore, StoreBackendInfo, UpdateSkillPatch } from "./types.js";
+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;
@@ -34,6 +34,15 @@ export declare class SqliteSkillsStore implements SkillsProductStore {
     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>;
@@ -89,9 +98,17 @@ export declare class SqliteSkillsStore implements SkillsProductStore {
     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): Promise<ServerSkillRecord | null>;
-    deleteSkill(principal: ApiPrincipal, slug: string): Promise<boolean>;
+    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.
      *

package/dist/server/store.d.ts

@@ -1,4 +1,4 @@
-import type { ApiPrincipal, ClaimRunInput, CreateRunInput, PublishSkillInput, RunTransitionPatch, ServerArtifact, ServerRunLog, ServerRunRecord, ServerSkillBundle, ServerSkillRecord, SkillsProductStore, StoreBackendInfo, UpdateSkillPatch } from "./types.js";
+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 {
@@ -31,6 +31,7 @@ export declare class MemorySkillsStore implements SkillsProductStore {
     private idempotency;
     private skills;
     private bundles;
+    private pins;
     constructor(apiKeys?: Array<{
         token: string;
         principal?: Partial<ApiPrincipal>;
@@ -68,9 +69,17 @@ export declare class MemorySkillsStore implements SkillsProductStore {
     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): Promise<ServerSkillRecord | null>;
-    deleteSkill(principal: ApiPrincipal, slug: string): Promise<boolean>;
+    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;
 }
@@ -88,6 +97,15 @@ export declare class PostgresSkillsStore implements SkillsProductStore {
      * 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>;
@@ -136,9 +154,17 @@ export declare class PostgresSkillsStore implements SkillsProductStore {
     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): Promise<ServerSkillRecord | null>;
-    deleteSkill(principal: ApiPrincipal, slug: string): Promise<boolean>;
+    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;
 }

package/dist/server/types.d.ts

@@ -15,6 +15,22 @@ export declare class StaleLeaseGenerationError extends Error {
     readonly status: ServerRunStatus;
     constructor(runId: string, expectedGeneration: number, currentGeneration: number, status: ServerRunStatus);
 }
+/**
+ * A publish or update was refused because it would silently overwrite a newer revision.
+ *
+ * The optimistic-concurrency guard (todos d061fcda): a write to an existing, live row
+ * must carry If-Match naming the current revision_id (the ETag the server issued). A
+ * missing guard, or one naming a different revision, is refused with this error instead
+ * of being applied. `currentRevisionId` is null when the row is absent or tombstoned —
+ * those are the two cases where the guard does not apply — and carries the live
+ * revision otherwise, so the caller can name what the writer was racing against.
+ */
+export declare class SkillRevisionConflictError extends Error {
+    readonly slug: string;
+    readonly expectedRevisionId: string | null | undefined;
+    readonly currentRevisionId: string | null;
+    constructor(slug: string, expectedRevisionId: string | null | undefined, currentRevisionId: string | null);
+}
 export interface ApiPrincipal {
     apiKeyId: string;
     orgId: string;
@@ -112,6 +128,26 @@ export interface ServerSkillRecord {
     publishedByUserId?: string;
     createdAt: string;
     updatedAt: string;
+    /**
+     * Immutable content-addressed revision identity (sha-256 over the published content,
+     * computed in server/revision.ts). Same content -> same id; any content change mints
+     * a new one. This is the ETag every read issues and every guarded write must match.
+     */
+    revisionId: string;
+    /**
+     * Monotonic per-slug write counter. Every publish and every metadata update bumps it,
+     * even when the content hash is unchanged, so "how many writes happened to this slug"
+     * is a number, not a digest comparison.
+     */
+    revisionNumber: number;
+    /**
+     * Present when the slug was deleted within the tombstone window (todos d061fcda).
+     * Reads must answer 410 with the marker so a client's pull can reconcile; the row and
+     * its bundle are purged once tombstonePurgeAfter passes. A re-publish clears both
+     * fields and revives the slug as a fresh revision.
+     */
+    tombstonedAt?: string;
+    tombstonePurgeAfter?: string;
 }
 /**
  * Bundle bytes, addressed by their own digest.
@@ -121,6 +157,21 @@ export interface ServerSkillRecord {
  * split ServerArtifact makes between `bodyText` and `storageKey`, except that a bundle is
  * a gzipped tar and so cannot be a string at any layer.
  */
+/**
+ * A skill the principal pinned on the hosted instance.
+ *
+ * The cloud-side twin of the local `.skills/project.json` pin: metadata-only,
+ * never content. `principal` is the api_keys.id of the API key that pinned
+ * (ApiPrincipal.apiKeyId) - a pin is a fact about a specific principal's
+ * selection, and two API keys in one org each have their own pin set.
+ */
+export interface ServerPin {
+    orgId: string;
+    principal: string;
+    slug: string;
+    pinnedAt: string;
+    metadata: Record<string, unknown>;
+}
 export interface ServerSkillBundle {
     orgId: string;
     sha256: string;
@@ -144,6 +195,15 @@ export interface PublishSkillInput {
     skillMd?: string;
     /** Omitted for a metadata-only publish or update. */
     bundle?: Omit<ServerSkillBundle, "orgId" | "createdAt">;
+    /**
+     * 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
+     * current revision_id; missing or mismatched is a SkillRevisionConflictError, never a
+     * silent overwrite. The guard is not required for a first publish (no row exists) or
+     * against a tombstoned row (nothing live to overwrite - the publish revives the slug
+     * as a fresh revision).
+     */
+    expectedRevisionId?: string;
 }
 /** Metadata-only patch. Never touches the bundle; republish to change bytes. */
 export type UpdateSkillPatch = Partial<Pick<ServerSkillRecord, "displayName" | "description" | "category" | "tags" | "version" | "kind" | "skillMd">>;
@@ -235,8 +295,43 @@ export interface SkillsProductStore {
     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): Promise<ServerSkillRecord | null>;
-    /** False when the org has no skill by that slug. Also drops a bundle nothing else references. */
-    deleteSkill(principal: ApiPrincipal, slug: string): Promise<boolean>;
+    /**
+     * Metadata-only patch, guarded by the same optimistic concurrency as publish: the
+     * row's current revision_id must match `expectedRevisionId` or
+     * SkillRevisionConflictError is thrown (409), never a silent overwrite. The revision
+     * advances on every successful update (new content sha, number + 1). Returns null
+     * 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>;
+    /**
+     * 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
+     * can answer 410 with the marker and a pulling client can reconcile, and the bundle
+     * survives until the purge. Returns the tombstoned record, or null when the org has
+     * no row by that slug. A second delete of an already-tombstoned slug returns the
+     * existing tombstone (idempotent; the window is not extended).
+     */
+    deleteSkill(principal: ApiPrincipal, slug: string, tombstoneWindowMs: number): Promise<ServerSkillRecord | null>;
+    /**
+     * Drop every tombstoned row whose window has expired, collecting the bundles nothing
+     * (live or tombstoned) references. Called on the read paths and by listSkills so the
+     * purge is lazy but does not wait for a slug to be read. Returns the purged records so
+     * the caller can discard their stored objects (S3).
+     */
+    purgeExpiredTombstones(principal: ApiPrincipal): Promise<ServerSkillRecord[]>;
     getSkillBundle(principal: ApiPrincipal, sha256: string): Promise<ServerSkillBundle | 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>;
+    listPins(principal: ApiPrincipal): Promise<ServerPin[]>;
+    listTags(principal: ApiPrincipal): Promise<string[]>;
+    listSkillsByTag(principal: ApiPrincipal, tag: string): Promise<ServerSkillRecord[]>;
+    listPinsByTag(principal: ApiPrincipal, tag: string): Promise<ServerPin[]>;
+    /**
+     * The slugs of the org's live (non-tombstoned) published skills. The tag
+     * routes use this to resolve merged-view precedence: a bundled skill whose
+     * slug a published row occupies must not resurface under a tag filter or in
+     * the tag list. A single-column scan of the (org_id, slug) primary key.
+     */
+    listPublishedSlugs(principal: ApiPrincipal): Promise<string[]>;
 }

package/dist/storage.js

@@ -162,6 +162,11 @@ function normalizeConfigValue(key, value) {
 }
 var DATA_DIR_ENV = "HASNA_SKILLS_DIR";
 var INSTALLED_SKILLS_DIRNAME = "installed";
+var SKILLS_CACHE_DIRNAME = "skills";
+var LAYOUT_MIGRATION_RECORD = ".layout-migration.json";
+function isOwnerLayoutMigrated(appDir) {
+  return existsSync(join(appDir, SKILLS_CACHE_DIRNAME, LAYOUT_MIGRATION_RECORD));
+}
 function getDataDir() {
   const override = process.env[DATA_DIR_ENV];
   if (override) {
@@ -498,7 +503,7 @@ function getSkillsNativeStorageStatus(options = {}) {
   const s3BucketEnv = readStorageEnv(env, "s3Bucket");
   const targetDir = options.targetDir ?? process.cwd();
   return {
-    package: "open-skills",
+    package: "skills",
     tables: [...SKILLS_STORAGE_TABLES],
     env: {
       databaseUrl: SKILLS_NATIVE_STORAGE_ENV.databaseUrl,
@@ -670,7 +675,7 @@ function createSkillsSnapshotSyncRecord(snapshot, options = {}) {
     kind: "local-snapshot",
     id: options.id ?? "project-state",
     updatedAt: snapshot.exportedAt,
-    source: options.source ?? "open-skills",
+    source: options.source ?? "skills",
     payload: snapshot
   };
 }

package/migrations/postgres/0004_hosted_pins.sql

@@ -0,0 +1,28 @@
+-- Hosted pins: the cloud becomes a source of truth for what the user selected.
+--
+-- Today a pin lives only in local project state (.skills/project.json); an
+-- instance has no pins surface, so nothing a user selected is ever visible to
+-- the server, to a second machine, or to another operator of the same org.
+-- This table is that surface.
+--
+-- Row identity is (org_id, principal, slug): one org, one API key, one slug -
+-- a pin is a fact about a specific principal's selection. `principal` stores
+-- the api_keys.id of the API key that pinned (ApiPrincipal.apiKeyId), so two
+-- API keys in the same org each have their own pin set, and two organizations
+-- can pin the same slug without colliding. The task's UNIQUE(org,principal,slug)
+-- is expressed as the composite primary key, which implies the same uniqueness
+-- and is the row's natural identity - there is no separate id to mint.
+--
+-- Pins are metadata-only: slug plus a free-form metadata object. Nothing here
+-- references skills_registry, so a pin may name a skill the org has not
+-- published (a bundled skill, or one that will exist later) without a
+-- foreign-key constraint choosing which of those futures is allowed.
+
+CREATE TABLE IF NOT EXISTS skills_pins (
+  org_id text NOT NULL REFERENCES organizations(id) ON DELETE CASCADE,
+  principal text NOT NULL,
+  slug text NOT NULL,
+  pinned_at timestamptz NOT NULL DEFAULT now(),
+  metadata_json jsonb NOT NULL DEFAULT '{}'::jsonb,
+  PRIMARY KEY (org_id, principal, slug)
+);

package/migrations/postgres/0005_revision_tombstone_registry.sql

@@ -0,0 +1,37 @@
+-- Revision identity, optimistic concurrency, and the tombstone contract for the hosted
+-- registry (todos d061fcda, plan 8022d27f).
+--
+-- Three behaviours this migration makes possible, all in one table because they are
+-- three properties of the same row:
+--
+--   1. IMMUTABLE REVISION IDENTITY. revision_id is a sha-256 over the row's published
+--      content (computed in TypeScript, src/lib/revision.ts) and revision_number is a
+--      monotonic per-slug write counter. Together they let a client prove WHICH revision
+--      it installed and let the server refuse a stale overwrite.
+--
+--   2. OPTIMISTIC CONCURRENCY. publish/update require an If-Match carrying the current
+--      revision_id; a mismatch (or a missing guard against an existing row) returns 409
+--      instead of silently overwriting a newer revision. The guard is enforced in the
+--      store's SQL (WHERE ... revision_id = <expected> on the upsert), never in
+--      read-then-write JS, so two concurrent writers cannot both pass a stale check.
+--
+--   3. TOMBSTONES. delete no longer drops the row: it stamps tombstoned_at +
+--      tombstone_purge_after (delete time + the configured window). Reads within the
+--      window answer 410 with the tombstone marker so a client's pull can reconcile
+--      (remove the local copy); after the window a read or list purges the row and its
+--      bundle. Re-publish over a tombstoned slug revives it as a fresh revision.
+--
+-- The columns are added by ALTER rather than by the 0002 drop-and-recreate pattern:
+-- the registry can hold tenant rows now (publishing shipped in the 0002 change), so a
+-- rebuild would be data loss. Rows that predate this migration get revision_id '' and
+-- revision_number 0; the store backfills a content sha for them on first open, because
+-- an empty revision id would make If-Match vacuous for legacy rows (every stale client
+-- would "match" the same empty string and two concurrent writers could both land).
+--
+-- Hand-written parallel of migrations/sqlite/0005_revision_tombstone_registry.sql; the
+-- dialect differences are the same documented set as 0001-0003 (timestamptz -> text).
+
+ALTER TABLE skills_registry ADD COLUMN revision_id text NOT NULL DEFAULT '';
+ALTER TABLE skills_registry ADD COLUMN revision_number integer NOT NULL DEFAULT 0;
+ALTER TABLE skills_registry ADD COLUMN tombstoned_at timestamptz;
+ALTER TABLE skills_registry ADD COLUMN tombstone_purge_after timestamptz;

package/migrations/postgres/0005_tag_projection.sql

@@ -0,0 +1,36 @@
+-- The hosted tag surface (T7) queries tag membership from this relational
+-- projection of skills_registry.tags_json, in both dialects with one identical
+-- shape. SQLite cannot index json_each() over the JSON column, and Postgres
+-- rows written by the current path hold the array text inside a jsonb scalar
+-- (bun's driver binds a JS string against a ::jsonb cast as a JSON string), so
+-- neither dialect can serve an indexed array-expansion query directly. The
+-- projection turns tag membership into a plain indexed lookup: the PRIMARY KEY
+-- serves (org_id, slug) maintenance and the org_tag index serves (org_id, tag)
+-- filters. The write paths keep it in step; the backfill below covers rows
+-- that predate it.
+-- No composite FK to skills_registry: the schema-parity parser cannot
+-- represent a multi-column FK identically in both dialects, and every write
+-- path here maintains the projection explicitly (publish/update replace its
+-- rows, the tombstone purge removes them with the row), so the constraint
+-- would be redundancy.
+CREATE TABLE skills_tags (
+  org_id text NOT NULL REFERENCES organizations(id) ON DELETE CASCADE,
+  slug text NOT NULL,
+  tag text NOT NULL,
+  PRIMARY KEY (org_id, slug, tag)
+);
+
+CREATE INDEX skills_tags_org_tag_idx ON skills_tags (org_id, tag);
+
+-- Backfill every existing row's tags. tags_json may be a real array or,
+-- because of the jsonb-scalar write path, the array text inside a jsonb
+-- string; both shapes are expanded here.
+INSERT INTO skills_tags (org_id, slug, tag)
+SELECT DISTINCT r.org_id, r.slug, t.tag
+FROM skills_registry r
+CROSS JOIN LATERAL jsonb_array_elements_text(
+  CASE WHEN jsonb_typeof(r.tags_json) = 'array' THEN r.tags_json
+       WHEN jsonb_typeof(r.tags_json) = 'string' THEN (r.tags_json #>> '{}')::jsonb
+       ELSE '[]'::jsonb END
+) AS t(tag)
+WHERE t.tag <> '';

package/migrations/sqlite/0004_hosted_pins.sql

@@ -0,0 +1,21 @@
+-- Hosted pins: the cloud becomes a source of truth for what the user selected.
+--
+-- SQLite dialect of 0004_hosted_pins. Read the Postgres file for the why; the
+-- only differences here are the documented dialect mapping:
+--   * timestamptz -> text holding a UTC ISO-8601 instant (pinned_at).
+--   * jsonb       -> text holding JSON (metadata_json).
+--
+-- No RLS: the tenant fence on this table is the org-scoped predicate in the
+-- store, exactly as it is for skills_registry and skills_bundles. RLS was
+-- armed in 0003 only for the run-output tables, where a worker path writes
+-- outside a tenant context; pins are written and read only by the API under
+-- the requesting principal's org, so there is no context-less writer to fence.
+
+CREATE TABLE IF NOT EXISTS skills_pins (
+  org_id text NOT NULL REFERENCES organizations(id) ON DELETE CASCADE,
+  principal text NOT NULL,
+  slug text NOT NULL,
+  pinned_at text NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+  metadata_json text NOT NULL DEFAULT '{}',
+  PRIMARY KEY (org_id, principal, slug)
+);

package/migrations/sqlite/0005_revision_tombstone_registry.sql

@@ -0,0 +1,18 @@
+-- SQLite dialect of 0005_revision_tombstone_registry.
+--
+-- Hand-written parallel of migrations/postgres/0005_revision_tombstone_registry.sql. Read
+-- that file for why the registry gains revision_id/revision_number (immutable revision
+-- identity), the optimistic-concurrency guard, and the tombstone contract; the rationale
+-- is not repeated here, only the dialect differences are.
+--
+-- Deliberate, shape-preserving dialect differences (same set as 0001):
+--   * timestamptz -> text holding a UTC ISO-8601 instant.
+--
+-- SQLite requires a non-null literal DEFAULT for a NOT NULL ADD COLUMN; the '' default is
+-- the legacy-row marker the store's backfill (src/lib/revision.ts) replaces with a
+-- content sha on first open, exactly as on Postgres.
+
+ALTER TABLE skills_registry ADD COLUMN revision_id text NOT NULL DEFAULT '';
+ALTER TABLE skills_registry ADD COLUMN revision_number integer NOT NULL DEFAULT 0;
+ALTER TABLE skills_registry ADD COLUMN tombstoned_at text;
+ALTER TABLE skills_registry ADD COLUMN tombstone_purge_after text;