@hasna/skills 0.9.12 → 0.9.13

package/dist/sdk/index.js

@@ -32373,7 +32373,7 @@ var init_event_sink = __esm(() => {
 // package.json
 var package_default = {
   name: "@hasna/skills",
-  version: "0.9.12",
+  version: "0.9.13",
   description: "Skills library for AI coding agents",
   type: "module",
   bin: {
@@ -37545,10 +37545,10 @@ function assertAgentPolicyCollections(policy) {
       text(source.path);
       requireBound(source.sha256 === null || typeof source.sha256 === "string" && /^[a-f0-9]{64}$/.test(source.sha256));
       if (source.hashMode !== undefined)
-        requireBound(["bytes", "path-bytes", "claude-plugin-registry", "claude-marketplace-registry", "claude-settings-v1"].includes(source.hashMode) && source.format === undefined && source.fields === undefined && (source.hashMode === "bytes" || source.sha256 !== null));
-      if (source.hashMode === "claude-settings-v1")
+        requireBound(["bytes", "path-bytes", "claude-plugin-registry", "claude-marketplace-registry", "claude-settings-v1", "claude-settings-v2", "claude-marketplace-registry-v2"].includes(source.hashMode) && source.format === undefined && source.fields === undefined && (source.hashMode === "bytes" || source.sha256 !== null));
+      if (source.hashMode === "claude-settings-v1" || source.hashMode === "claude-settings-v2")
         requireBound(agent === "claude" && value.agent === "claude" && value.method === "reviewed" && !/[\x00-\x1f\x7f]/.test(source.path) && isAbsolute3(source.path) && resolve3(source.path) === source.path && basename2(source.path) === "settings.json");
-      if (source.hashMode === "claude-marketplace-registry")
+      if (source.hashMode === "claude-marketplace-registry" || source.hashMode === "claude-marketplace-registry-v2")
         requireBound(agent === "claude" && value.agent === "claude" && value.method === "reviewed" && !/[\x00-\x1f\x7f]/.test(source.path) && isAbsolute3(source.path) && resolve3(source.path) === source.path && basename2(source.path) === "known_marketplaces.json");
       if (source.hashMode === "claude-plugin-registry") {
         requireBound(agent === "claude");
@@ -39895,9 +39895,13 @@ function textField(value) {
   need2(value?.kind === "string" && value.value.length > 0 && !/[\x00-\x1f\x7f]/.test(value.value), "contains an invalid recognized field");
   return value.value;
 }
-function normalizeRow(row) {
-  if (!exactKeys2(row, ["source", "installLocation", "lastUpdated"]))
-    return;
+function normalizeRow(row, version = 1) {
+  if (!exactKeys2(row, ["source", "installLocation", "lastUpdated"])) {
+    if (version !== 2 || !exactKeys2(row, ["source", "installLocation", "lastUpdated", "autoUpdate"]))
+      return;
+    const autoUpdate = field(row, "autoUpdate");
+    need2(autoUpdate?.kind === "literal" && (autoUpdate.value === "true" || autoUpdate.value === "false"), "contains an invalid automatic-update preference");
+  }
   const source = field(row, "source");
   if (source?.kind !== "object")
     return;
@@ -39924,6 +39928,13 @@ function captureClaudeMarketplaceRegistry(path, budget = { remaining: 256 * 1024
   const sha2562 = createHash11("sha256").update("hasna.skills.claude-marketplace-registry.v1\x00").update(JSON.stringify(value)).digest("hex");
   return { path, hashMode: "claude-marketplace-registry", sha256: sha2562 };
 }
+function captureClaudeMarketplaceRegistryV2(path, budget = { remaining: 256 * 1024 * 1024 }) {
+  const value = parse5(readRegistry2(path, budget));
+  for (const [, row] of value.entries)
+    normalizeRow(row, 2);
+  const sha2562 = createHash11("sha256").update("hasna.skills.claude-marketplace-registry.v2\x00").update(JSON.stringify(value)).digest("hex");
+  return { path, hashMode: "claude-marketplace-registry-v2", sha256: sha2562 };
+}
 
 // src/lib/claude-settings-witness.ts
 import { createHash as createHash12 } from "crypto";
@@ -40136,9 +40147,33 @@ function assertClaudeStopHookReplacement(before, replacement) {
   }
   need3(JSON.stringify(withoutStop(original)) === JSON.stringify(withoutStop(next)), "Stop update changed settings outside hooks.Stop");
 }
-function settingsDigest(text2) {
+var PERSISTED_EFFORT_LEVELS = new Set(["low", "medium", "high", "xhigh"]);
+function inferencePreference(key, child) {
+  if (key === "skipDangerousModePermissionPrompt") {
+    need3(child.kind === "literal" && (child.value === "true" || child.value === "false"), "contains an invalid dialog acknowledgment");
+    return true;
+  }
+  if (key === "effortLevel") {
+    need3(child.kind === "string" && PERSISTED_EFFORT_LEVELS.has(child.value), "contains an invalid persisted effort level");
+    return true;
+  }
+  if (key !== "modelSettings")
+    return false;
+  need3(child.kind === "object", "requires an object of model preferences");
+  child.entries = child.entries.filter(([model, preferences]) => {
+    if (!BUILTIN_MODEL_SELECTIONS.has(model) || preferences.kind !== "object" || preferences.entries.length !== 1 || preferences.entries[0][0] !== "effortLevel")
+      return true;
+    const effort = preferences.entries[0][1];
+    need3(effort.kind === "string" && PERSISTED_EFFORT_LEVELS.has(effort.value), "contains an invalid persisted model effort level");
+    return false;
+  });
+  return child.entries.length === 0;
+}
+function settingsDigest(text2, version = 1) {
   const value = parse6(text2);
   value.entries = value.entries.filter(([key, child]) => {
+    if (version === 2 && inferencePreference(key, child))
+      return false;
     if (key === "model") {
       need3(child.kind === "string", "contains an invalid model selection");
       return !BUILTIN_MODEL_SELECTIONS.has(child.value);
@@ -40153,7 +40188,7 @@ function settingsDigest(text2) {
     }
     return true;
   });
-  return createHash12("sha256").update("hasna.skills.claude-settings.v1\x00").update(JSON.stringify(canonical3(value))).digest("hex");
+  return createHash12("sha256").update(`hasna.skills.claude-settings.v${version}\x00`).update(JSON.stringify(canonical3(value))).digest("hex");
 }
 function hashClaudeSettingsReplacement(text2, budget) {
   need3(typeof text2 === "string", "requires settings text");
@@ -40165,6 +40200,16 @@ function hashClaudeSettingsReplacement(text2, budget) {
 function captureClaudeSettings(path, budget = { remaining: 256 * 1024 * 1024 }) {
   return { path, hashMode: "claude-settings-v1", sha256: settingsDigest(readSettings(path, budget)) };
 }
+function captureClaudeSettingsV2(path, budget = { remaining: 256 * 1024 * 1024 }) {
+  return { path, hashMode: "claude-settings-v2", sha256: settingsDigest(readSettings(path, budget), 2) };
+}
+function hashClaudeSettingsReplacementV2(text2, budget) {
+  need3(typeof text2 === "string", "requires settings text");
+  const bytes = Buffer.byteLength(text2);
+  need3(bytes <= CLAUDE_SETTINGS_WITNESS_LIMITS.bytes && Number.isSafeInteger(budget.remaining) && budget.remaining >= bytes, "exceeds its byte limit");
+  budget.remaining -= bytes;
+  return settingsDigest(text2, 2);
+}
 
 // src/lib/codex-hook-discovery-recovery.ts
 import { createHash as createHash14 } from "crypto";
@@ -40268,18 +40313,18 @@ function read2(path, changes) {
   return readFileSync12(path, "utf8");
 }
 function projected(source, changes, budget = discoveryByteBudget()) {
-  if (source.hashMode === "claude-settings-v1") {
+  if (source.hashMode === "claude-settings-v1" || source.hashMode === "claude-settings-v2") {
     if (source.format !== undefined || source.fields !== undefined || source.managedPlugins !== undefined || typeof source.sha256 !== "string" || !/^[a-f0-9]{64}$/.test(source.sha256))
       throw new Error("Claude settings witnesses require exact typed metadata");
-    const current = captureClaudeSettings(source.path, budget).sha256;
+    const current = (source.hashMode === "claude-settings-v2" ? captureClaudeSettingsV2 : captureClaudeSettings)(source.path, budget).sha256;
     if (current !== source.sha256)
       throw new Error(`Native discovery input changed; run skills hook install with a fresh discovery review: ${source.path}`);
-    return changes?.has(source.path) ? hashClaudeSettingsReplacement(changes.get(source.path), budget) : current;
+    return changes?.has(source.path) ? (source.hashMode === "claude-settings-v2" ? hashClaudeSettingsReplacementV2 : hashClaudeSettingsReplacement)(changes.get(source.path), budget) : current;
   }
-  if (source.hashMode === "claude-marketplace-registry") {
+  if (source.hashMode === "claude-marketplace-registry" || source.hashMode === "claude-marketplace-registry-v2") {
     if (source.format !== undefined || source.fields !== undefined || source.managedPlugins !== undefined || typeof source.sha256 !== "string" || !/^[a-f0-9]{64}$/.test(source.sha256) || changes?.has(source.path))
       throw new Error("Claude marketplace witnesses require an exact reviewed registry without synthetic changes");
-    const sha2562 = captureClaudeMarketplaceRegistry(source.path, budget).sha256;
+    const sha2562 = (source.hashMode === "claude-marketplace-registry-v2" ? captureClaudeMarketplaceRegistryV2 : captureClaudeMarketplaceRegistry)(source.path, budget).sha256;
     if (sha2562 !== source.sha256)
       throw new Error(`Native discovery input changed; run skills hook install with a fresh discovery review: ${source.path}`);
     return sha2562;
@@ -40336,9 +40381,9 @@ function verifyAgentDiscovery(binding, codexRecovery) {
     safe4(root2);
 }
 function assertMarketplaceBinding(binding, source) {
-  if (source.hashMode === "claude-settings-v1" && (binding.agent !== "claude" || binding.method !== "reviewed" || basename6(source.path) !== "settings.json"))
+  if ((source.hashMode === "claude-settings-v1" || source.hashMode === "claude-settings-v2") && (binding.agent !== "claude" || binding.method !== "reviewed" || basename6(source.path) !== "settings.json"))
     throw new Error("Claude settings witnesses require explicit reviewed Claude configuration");
-  if (source.hashMode === "claude-marketplace-registry" && (binding.agent !== "claude" || binding.method !== "reviewed"))
+  if ((source.hashMode === "claude-marketplace-registry" || source.hashMode === "claude-marketplace-registry-v2") && (binding.agent !== "claude" || binding.method !== "reviewed"))
     throw new Error("Claude marketplace witnesses require explicit reviewed Claude discovery");
 }
 function rebindAgentDiscovery(binding, changes) {
@@ -40479,7 +40524,7 @@ function resolveAgentDiscovery(options) {
     if (review.sources.some((source) => source.format !== undefined || source.fields !== undefined))
       throw new Error("Explicit discovery reviews require full source-file hashes");
     verifyAgentDiscovery(supplied);
-    if (review.sources.some((source) => source.hashMode === "claude-settings-v1" && source.path !== canonical4(configPath)))
+    if (review.sources.some((source) => (source.hashMode === "claude-settings-v1" || source.hashMode === "claude-settings-v2") && source.path !== canonical4(configPath)))
       throw new Error("Semantic settings witnesses must name the configured Claude configuration source");
     if (!review.sources.some((source) => source.path === canonical4(configPath)))
       throw new Error("Discovery review must include the agent configuration source");
@@ -55561,6 +55606,18 @@ function rowToSkill(row) {
     ...row.replacement_slug ? { replacementSlug: String(row.replacement_slug) } : {}
   };
 }
+function rowToPublishedSelectionState(row) {
+  return {
+    slug: String(row.slug),
+    version: String(row.version),
+    current: row.skill_exists ? {
+      lifecycle: row.lifecycle === "archived" ? "archived" : "active",
+      ...row.tombstoned_at ? { tombstonedAt: dateString(row.tombstoned_at) } : {}
+    } : null,
+    versionBundleSha256: typeof row.bundle_sha256 === "string" ? row.bundle_sha256 : null,
+    bundleAvailable: Boolean(row.bundle_available)
+  };
+}
 function rowToPin(row) {
   return {
     orgId: String(row.org_id),
@@ -56335,6 +56392,22 @@ class SqliteSkillsStore {
     const row = this.get("SELECT * FROM skills_versions WHERE org_id = ? AND slug = ? AND version = ? LIMIT 1", [principal.orgId, slug, version2]);
     return row ? rowToSkillVersion(row) : null;
   }
+  async getPublishedSelectionStates(principal, selections2) {
+    if (selections2.length > MAX_PROFILE_SELECTIONS)
+      throw new RangeError("Published selection lookup exceeds the profile selection limit");
+    if (!selections2.length)
+      return [];
+    const requested = JSON.stringify(selections2.map(({ slug, version: version2 }) => ({ slug, version: version2 })));
+    return this.all(`SELECT json_extract(q.value, '$.slug') AS slug, json_extract(q.value, '$.version') AS version,
+         r.slug IS NOT NULL AS skill_exists, r.lifecycle, r.tombstoned_at,
+         v.bundle_sha256, b.sha256 IS NOT NULL AS bundle_available
+       FROM json_each(?) q
+       LEFT JOIN skills_registry r ON r.org_id = ? AND r.slug = json_extract(q.value, '$.slug')
+       LEFT JOIN skills_versions v ON v.org_id = ?
+         AND v.slug = json_extract(q.value, '$.slug') AND v.version = json_extract(q.value, '$.version')
+       LEFT JOIN skills_bundles b ON b.org_id = ? AND b.sha256 = v.bundle_sha256
+       ORDER BY CAST(q.key AS INTEGER)`, [requested, principal.orgId, principal.orgId, principal.orgId]).map(rowToPublishedSelectionState);
+  }
   async pinSkill(principal, slug, metadata = {}) {
     const row = this.get(`INSERT INTO skills_pins (org_id, principal, slug, pinned_at, metadata_json)
        VALUES (?, ?, ?, ?, ?)
@@ -57463,16 +57536,21 @@ function selected(value) {
   return selections2;
 }
 async function validatePublished(store, principal, selections2) {
-  for (const selection2 of selections2) {
-    const current = await store.getSkill(principal, selection2.slug);
+  const states = await store.getPublishedSelectionStates(principal, selections2);
+  if (states.length !== selections2.length)
+    throw new SkillRequestError(503, "SELECTION_UNAVAILABLE", "Selected publication state is unavailable");
+  for (const [index, selection2] of selections2.entries()) {
+    const state2 = states[index];
+    if (!state2 || state2.slug !== selection2.slug || state2.version !== selection2.version)
+      throw new SkillRequestError(503, "SELECTION_UNAVAILABLE", "Selected publication state is unavailable");
+    const current = state2.current;
     if (!current || current.tombstonedAt)
       throw new SkillRequestError(current?.tombstonedAt ? 410 : 404, "SELECTION_UNAVAILABLE", `Selected skill '${selection2.slug}' is unavailable`);
     if (current.lifecycle === "archived")
       throw new SkillRequestError(409, "SELECTION_ARCHIVED", `Selected skill '${selection2.slug}' is archived`);
-    const version2 = await store.getSkillVersion(principal, selection2.slug, selection2.version);
-    if (!version2 || `sha256:${version2.bundleSha256}` !== selection2.bundleDigest)
+    if (!state2.versionBundleSha256 || `sha256:${state2.versionBundleSha256}` !== selection2.bundleDigest)
       throw new SkillRequestError(409, "SELECTION_VERSION_MISMATCH", `Selected version of '${selection2.slug}' does not match its published digest`);
-    if (!await store.getSkillBundle(principal, version2.bundleSha256))
+    if (!state2.bundleAvailable)
       throw new SkillRequestError(503, "SELECTION_BUNDLE_UNAVAILABLE", "Selected bundle is unavailable");
   }
 }
@@ -63361,6 +63439,25 @@ class MemorySkillsStore {
     const found = this.versions.get(versionKey(principal.orgId, slug, version2));
     return found && found.orgId === principal.orgId ? found : null;
   }
+  async getPublishedSelectionStates(principal, selections2) {
+    if (selections2.length > MAX_PROFILE_SELECTIONS)
+      throw new RangeError("Published selection lookup exceeds the profile selection limit");
+    return selections2.map(({ slug, version: version2 }) => {
+      const current = this.skills.get(skillKey(principal.orgId, slug));
+      const selectedVersion = this.versions.get(versionKey(principal.orgId, slug, version2));
+      const bundle2 = selectedVersion && this.bundles.get(skillKey(principal.orgId, selectedVersion.bundleSha256));
+      return {
+        slug,
+        version: version2,
+        current: current?.orgId === principal.orgId ? {
+          lifecycle: current.lifecycle,
+          ...current.tombstonedAt ? { tombstonedAt: current.tombstonedAt } : {}
+        } : null,
+        versionBundleSha256: selectedVersion?.orgId === principal.orgId ? selectedVersion.bundleSha256 : null,
+        bundleAvailable: bundle2?.orgId === principal.orgId
+      };
+    });
+  }
   async listSkills(principal) {
     return Array.from(this.skills.values()).filter((skill) => skill.orgId === principal.orgId && !skill.tombstonedAt).sort((a4, b4) => a4.slug.localeCompare(b4.slug));
   }
@@ -64169,6 +64266,25 @@ class PostgresSkillsStore {
     `;
     return rows[0] ? rowToSkillVersion(rows[0]) : null;
   }
+  async getPublishedSelectionStates(principal, selections2) {
+    if (selections2.length > MAX_PROFILE_SELECTIONS)
+      throw new RangeError("Published selection lookup exceeds the profile selection limit");
+    if (!selections2.length)
+      return [];
+    const requested = JSON.stringify(selections2.map(({ slug, version: version2 }) => ({ slug, version: version2 })));
+    const rows = await this.sql`
+      SELECT q.value->>'slug' AS slug, q.value->>'version' AS version,
+        r.slug IS NOT NULL AS skill_exists, r.lifecycle, r.tombstoned_at,
+        v.bundle_sha256, b.sha256 IS NOT NULL AS bundle_available
+      FROM jsonb_array_elements(${requested}::text::jsonb) WITH ORDINALITY AS q(value, ordinal)
+      LEFT JOIN skills_registry r ON r.org_id = ${principal.orgId} AND r.slug = q.value->>'slug'
+      LEFT JOIN skills_versions v ON v.org_id = ${principal.orgId}
+        AND v.slug = q.value->>'slug' AND v.version = q.value->>'version'
+      LEFT JOIN skills_bundles b ON b.org_id = ${principal.orgId} AND b.sha256 = v.bundle_sha256
+      ORDER BY q.ordinal
+    `;
+    return rows.map(rowToPublishedSelectionState);
+  }
   async pinSkill(principal, slug, metadata = {}) {
     const rows = await this.sql`
       INSERT INTO skills_pins (org_id, principal, slug, pinned_at, metadata_json)

package/dist/server/rows.d.ts

@@ -1,4 +1,4 @@
-import type { ServerSkillVersion, ServerArtifact, ServerPin, ServerRunLog, ServerRunRecord, ServerSkillBundle, ServerSkillRecord } from "./types.js";
+import type { ServerSkillVersion, ServerArtifact, ServerPin, ServerRunLog, ServerRunRecord, ServerSkillBundle, ServerSkillRecord, PublishedSkillSelectionState } 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 rowToPublishedSelectionState(row: Record<string, unknown>): PublishedSkillSelectionState;
 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>;

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, ApiKeyScopeUpdateResult, OperatorScopeEnrollmentInput, OperatorScopeEnrollmentResult, OperatorScopeTargetSnapshot, ServerSkillRecord, SkillLifecyclePatch, SkillsProductStore, StoreBackendInfo, UpdateSkillPatch } from "./types.js";
+import type { ApiPrincipal, ClaimRunInput, CreateRunInput, PublishSkillInput, PublishedSkillSelection, PublishedSkillSelectionState, RunTransitionPatch, ServerArtifact, ServerPin, ServerRunLog, ServerRunRecord, ServerSkillBundle, ServerSkillVersion, ApiKeyScopeUpdateResult, OperatorScopeEnrollmentInput, OperatorScopeEnrollmentResult, OperatorScopeTargetSnapshot, 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;
@@ -113,6 +113,7 @@ export declare class SqliteSkillsStore implements SkillsProductStore {
     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>;
+    getPublishedSelectionStates(principal: ApiPrincipal, selections: readonly PublishedSkillSelection[]): Promise<PublishedSkillSelectionState[]>;
     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,6 +1,6 @@
 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, ApiKeyScopeUpdateResult, OperatorScopeEnrollmentInput, OperatorScopeEnrollmentResult, OperatorScopeTargetSnapshot, SkillsProductStore, StoreBackendInfo, UpdateSkillPatch } from "./types.js";
+import type { ApiPrincipal, ClaimRunInput, CreateRunInput, PublishSkillInput, PublishedSkillSelection, PublishedSkillSelectionState, RunTransitionPatch, ServerArtifact, ServerPin, ServerRunLog, ServerRunRecord, ServerSkillBundle, ServerSkillRecord, ServerSkillVersion, ApiKeyScopeUpdateResult, OperatorScopeEnrollmentInput, OperatorScopeEnrollmentResult, OperatorScopeTargetSnapshot, SkillsProductStore, StoreBackendInfo, UpdateSkillPatch } from "./types.js";
 import { type SkillLifecyclePatch } from "./types.js";
 import { type SqliteStoreOptions } from "./sqlite-store.js";
 export declare function createArtifactId(): string;
@@ -79,6 +79,7 @@ export declare class MemorySkillsStore implements SkillsProductStore {
     publishSkill(input: PublishSkillInput): Promise<ServerSkillRecord>;
     listSkillVersions(principal: ApiPrincipal, slug: string): Promise<ServerSkillVersion[]>;
     getSkillVersion(principal: ApiPrincipal, slug: string, version: string): Promise<ServerSkillVersion | null>;
+    getPublishedSelectionStates(principal: ApiPrincipal, selections: readonly PublishedSkillSelection[]): Promise<PublishedSkillSelectionState[]>;
     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>;
@@ -180,6 +181,7 @@ export declare class PostgresSkillsStore implements SkillsProductStore {
     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>;
+    getPublishedSelectionStates(principal: ApiPrincipal, selections: readonly PublishedSkillSelection[]): Promise<PublishedSkillSelectionState[]>;
     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

@@ -279,6 +279,17 @@ export interface ServerSkillVersion {
     publishedByUserId?: string;
     createdAt: string;
 }
+/** Exact version lookup, independent of the registry's mutable current version. */
+export interface PublishedSkillSelection {
+    slug: string;
+    version: string;
+}
+/** Metadata only: bundle availability means its tenant-owned storage row exists. */
+export interface PublishedSkillSelectionState extends PublishedSkillSelection {
+    current: Pick<ServerSkillRecord, "lifecycle" | "tombstonedAt"> | null;
+    versionBundleSha256: string | null;
+    bundleAvailable: boolean;
+}
 export interface PublishSkillInput {
     /** Internal boot-seed precondition: never revive or replace non-bundled records. */
     seedBundledOnly?: true;
@@ -441,6 +452,13 @@ export interface SkillsProductStore {
     /** 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>;
+    /**
+     * Read at most MAX_PROFILE_SELECTIONS exact selections in one database snapshot,
+     * scoped to the principal's org at every join. Returns one row per input in input
+     * order, including missing selections and duplicates. Never reads bundle bytes or
+     * substitutes the latest version; callers retain lifecycle/digest error policy.
+     */
+    getPublishedSelectionStates(principal: ApiPrincipal, selections: readonly PublishedSkillSelection[]): Promise<PublishedSkillSelectionState[]>;
     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>;

package/docs/plugin-admission.md

@@ -286,3 +286,39 @@ cache history is bounded to 128 entries and an aggregate 256 MiB per witness.
 Primary runtime references: [command sources](https://code.claude.com/docs/en/plugin-marketplaces#command-sources),
 [plugin components](https://code.claude.com/docs/en/plugins-reference), and
 [exact command acceptance](https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md#21271).
+
+### Explicit v2 preference reviews
+
+`captureClaudeSettingsV2(path)` creates a `claude-settings-v2` witness. In
+addition to the v1 display/model selections, it tolerates the documented
+persisted effort values `low`, `medium`, `high`, and `xhigh`, both at the top
+level and in known built-in model entries whose only property is `effortLevel`.
+Custom model entries and entries with any other property remain fully bound.
+The boolean `skipDangerousModePermissionPrompt` is Claude's saved dialog
+acknowledgment; it does not select a permission mode. Permission settings,
+plugins, hooks, environment, ultracode and unknown configuration remain bound.
+Invalid recognized preference types are refused.
+
+`captureClaudeMarketplaceRegistryV2(path)` creates a
+`claude-marketplace-registry-v2` witness. It also recognizes a registry row with
+an optional boolean `autoUpdate`. That boolean remains bound; only a strictly
+validated `lastUpdated` timestamp may vary. A new source or installation path,
+a changed automatic-update policy, or an unknown field still requires review.
+
+Capture either witness through the CLI:
+
+```sh
+skills hook witness --kind claude-settings-v2 --path /canonical/home/.claude/settings.json --json
+skills hook witness --kind claude-marketplace-registry-v2 --path /canonical/home/.claude/plugins/known_marketplaces.json --json
+```
+
+Capture does not install or authorize a review. Compare the current complete
+configuration with its previous review, put the chosen witness in the reviewed
+discovery inputs, and preview `skills hook install --discovery-inputs <file>`
+before applying. Existing byte and v1 witnesses are never silently converted.
+Runtime support for the selected witness version must be installed before
+policy activation. A real hook installation is a configuration change, not a
+preference: its owning installer must coordinate a guarded settings/policy
+update, or it needs a fresh explicit review.
+
+The effort schema follows [Claude's model configuration documentation](https://code.claude.com/docs/en/model-config#adjust-effort-level).

package/package.json

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