@hasna/skills 0.10.62 → 0.10.64

package/dist/lib/agent-discovery.d.ts

@@ -3,18 +3,35 @@ import { type DiscoveryDirectory } from "./agent-discovery-directories.js";
 import { type ManagedPluginRegistrationWitness } from "./plugin-discovery.js";
 import { type CodexHookDiscoveryRecovery } from "./codex-hook-discovery-recovery.js";
 import { type CodexPluginSkillControl, type CodexPluginSourceInput } from "./codex-plugin-skill-controls.js";
+import { type RetainedReviewArtifact, type ReviewedArtifact } from "./retained-review-artifacts.js";
+import { type CodexSemanticCacheWitness, type CodexSemanticCacheAppOnlyParent } from "./codex-semantic-cache-witness.js";
 export { captureDiscoveryDirectories, type DiscoveryDirectory } from "./agent-discovery-directories.js";
 export interface DiscoverySource {
+    reviewArtifact?: RetainedReviewArtifact;
     path: string;
     sha256: string | null;
-    hashMode?: "bytes" | "path-bytes" | "claude-plugin-manifest-v1" | "claude-plugin-registry" | "claude-marketplace-registry" | "claude-settings-v1" | "claude-settings-v2" | "claude-settings-v3" | "claude-settings-v4" | "claude-marketplace-registry-v2" | "codex-settings-v1" | "codex-settings-v2" | "codex-settings-v3" | "codex-settings-v4" | "sumi-settings-v1" | "claude-marketplace-entry-v1";
+    hashMode?: "bytes" | "path-bytes" | "claude-plugin-manifest-v1" | "claude-plugin-registry" | "claude-marketplace-registry" | "claude-settings-v1" | "claude-settings-v2" | "claude-settings-v3" | "claude-settings-v4" | "claude-marketplace-registry-v2" | "codex-settings-v1" | "codex-settings-v2" | "codex-settings-v3" | "codex-settings-v4" | "codex-settings-v5" | "sumi-settings-v1" | "claude-marketplace-entry-v1";
     managedPlugins?: ManagedPluginRegistrationWitness[];
     format?: "json" | "toml" | "yaml";
     fields?: string[];
     marketplace?: string;
     plugin?: string;
 }
+export interface CodexSemanticCacheDiscovery {
+    schema: "hasna.codex-semantic-cache-discovery.v1";
+    configPath: string;
+    hookRootAlias: {
+        alias: string;
+        target: string;
+    } | null;
+    witness: CodexSemanticCacheWitness;
+    appOnlyParents: CodexSemanticCacheAppOnlyParent[];
+    previousPolicySha256: string;
+    supersededSources: DiscoverySource[];
+    supersededDirectories: DiscoveryDirectory[];
+}
 export interface AgentDiscoveryBinding {
+    codexSemanticCache?: CodexSemanticCacheDiscovery;
     agent: IntegrationAgent;
     roots: string[];
     sources: DiscoverySource[];
@@ -63,6 +80,7 @@ export interface ReviewedDiscoveryInputs {
         agent: IntegrationAgent;
         roots: string[];
         sources: DiscoverySource[];
+        reviewArtifacts?: ReviewedArtifact[];
         directories?: DiscoveryDirectory[];
         pluginHooks: "reviewed-no-skill-injection";
     }>;
@@ -73,7 +91,16 @@ export declare function projectNativeDiscoveryFields(text: string, format: "json
 /** Called only after the owning planner validated discovery and capabilities.
  * New roots must already be body-free; absent roots need the prior typed proof. */
 export declare function captureRetiredCodexDiscovery(binding: AgentDiscoveryBinding, controls: CodexPluginSkillControl[], rules: unknown): AgentDiscoveryBinding;
-export declare function verifyAgentDiscovery(binding: AgentDiscoveryBinding, codexRecovery?: CodexHookDiscoveryRecovery): void;
+/** Only native capability locations covered by the complete typed cache census
+ * qualify. Historical sources remain stored; arbitrary missing files do not. */
+export declare function codexSemanticCacheSourceRole(source: DiscoverySource, cacheRoot: string, parents: readonly string[]): boolean;
+export declare function codexSemanticCacheDirectoryRole(path: string, cacheRoot: string): boolean;
+export declare function assertCodexSemanticCacheHookSafety(cacheRoot: string, parents: readonly string[], configPath: string, hookRootAlias?: CodexSemanticCacheDiscovery["hookRootAlias"]): void;
+export declare function verifyAgentDiscovery(binding: AgentDiscoveryBinding, codexRecovery?: CodexHookDiscoveryRecovery, reviewedRootAliases?: readonly {
+    agent: IntegrationAgent;
+    alias: string;
+    target: string;
+}[]): void;
 export declare function rebindAgentDiscovery(binding: AgentDiscoveryBinding, changes: Map<string, string>): AgentDiscoveryBinding;
 /** Capture full byte witnesses for reviewed source or executable files; never import or execute them. */
 export declare function captureDiscoveryByteSources(paths: string[]): DiscoverySource[];

package/dist/lib/agent-integration.d.ts

@@ -6,6 +6,7 @@ import { type DiscoveryExecutable, type AgentDiscoveryBinding, type ReviewedDisc
 import { type IntegrationAgent } from "./agent-adapters.js";
 import type { CodexHookDiscoveryRecovery } from "./codex-hook-discovery-recovery.js";
 import { type ClaudeCoordinatedHookEvent } from "./claude-settings-witness.js";
+import { type ReviewArtifactChange } from "./retained-review-artifacts.js";
 export type { IntegrationAgent } from "./agent-adapters.js";
 export type ContextHookEvent = "UserPromptSubmit" | "SessionStart" | "SubagentStart";
 export interface AgentRootAlias {
@@ -47,6 +48,13 @@ export interface AgentConfigChange {
     after: string;
 }
 export interface AgentIntegrationPlan {
+    cacheWitnessUpgrade?: CodexSemanticCacheUpgrade;
+    reviewArtifactSources?: Array<{
+        path: string;
+        sha256: string;
+    }>;
+    retainedReviewArtifacts?: ReviewArtifactChange[];
+    reviewArtifactMigration?: ReviewArtifactMigration;
     observedNativeSources?: Array<{
         path: string;
         sha256: string | null;
@@ -89,6 +97,7 @@ export interface AgentIntegrationPlan {
     rootAliases?: AgentRootAlias[];
     managedAgentChecks?: {
         home: string;
+        projectDir?: string;
         agents: IntegrationAgent[];
     };
     retainedReviewChecks?: {
@@ -194,7 +203,7 @@ export declare function planClaudeHookEventsUpdate(options: ClaudeHookUpdateOpti
  */
 export declare function planAgentSettingsWitnessUpgrade(options: {
     agent: "claude" | "codex" | "sumi";
-    targetCodexVersion?: 2 | 3 | 4;
+    targetCodexVersion?: 2 | 3 | 4 | 5;
     targetClaudeVersion?: 3 | 4;
     reviewedPreimage: string;
     home?: string;
@@ -203,6 +212,29 @@ export declare function planAgentSettingsWitnessUpgrade(options: {
     expectedPolicySha256: string;
     expectedSettingsSha256: string;
 }): AgentIntegrationPlan;
+export interface CodexSemanticCacheUpgrade {
+    agent: "codex";
+    appOnlyParents: string[];
+    expectedPolicySha256: string;
+    expectedSettingsSha256: string;
+    expectedCacheWitnessSha256?: string;
+    home?: string;
+    dataDir?: string;
+}
+/** Explicit current capability review. Old aggregate directory digests remain
+ * evidence, not a reconstructed historical tree or a new byte baseline. */
+export declare function planCodexSemanticCacheWitnessUpgrade(options: CodexSemanticCacheUpgrade): AgentIntegrationPlan;
+export interface ReviewArtifactMigration {
+    kind: "codex-native-catalog";
+    sourcePath: string;
+    expectedPolicySha256: string;
+    expectedSourceSha256: string;
+    home?: string;
+    dataDir?: string;
+    projectDir?: string;
+}
+/** Explicit exact-proof migration. Never captures a new catalog or refreshes live inputs. */
+export declare function planReviewedArtifactMigration(options: ReviewArtifactMigration): AgentIntegrationPlan;
 export declare function applyAgentIntegration(plan: AgentIntegrationPlan, options?: CodexCorpusWriteOptions): {
     changed: string[];
     backups: string[];

package/dist/lib/codex-plugin-skill-controls.d.ts

@@ -32,6 +32,15 @@ export interface CodexPluginSourceInput {
     sourceSha256: string;
 }
 type Read = (path: string) => string;
+export interface CodexPluginRootControls {
+    namespace: string;
+    manifestSha256: string;
+    appSha256?: string;
+    mcpSha256?: string;
+}
+/** Reuse the strict package-owned capability parser for an explicitly reviewed
+ * plugin materialization. This does not establish parent or receipt identity. */
+export declare function readCodexPluginRootControls(root: string, read: Read): CodexPluginRootControls;
 export interface CodexPluginCacheDocumentIdentity {
     name: string;
     namespace: string;

package/dist/lib/codex-semantic-cache-witness.d.ts

@@ -0,0 +1,57 @@
+import { type CodexPluginSkillControl } from "./codex-plugin-skill-controls.js";
+export declare const CODEX_SEMANTIC_CACHE_WITNESS_SCHEMA: "hasna.codex-semantic-cache-witness.v1";
+export interface CodexSemanticCacheControl {
+    pluginId: string;
+    namespace: string;
+    pluginParent: string;
+    remotePluginId?: string;
+    receiptSha256?: string;
+    manifestSha256: string;
+    appSha256?: string;
+    mcpSha256?: string;
+}
+export interface CodexSemanticCacheSkill {
+    name: string;
+    pluginId: string;
+    namespace: string;
+    pluginParent: string;
+    disabledRules: string[];
+}
+/** Caller explicitly classifies a remote plugin parent whose only reviewed
+ * capability is its app integration and whose cache contains no Skill docs. */
+export interface CodexSemanticCacheAppOnlyParent {
+    role: "app-only";
+    pluginId: string;
+    namespace: string;
+    pluginParent: string;
+    remotePluginId: string;
+}
+export interface CodexSemanticCacheAppOnlyParentWitness extends CodexSemanticCacheAppOnlyParent {
+    receiptSha256: string;
+    manifestSha256: string;
+    appSha256: string;
+    mcpSha256?: string;
+}
+export interface CodexSemanticCacheWitness {
+    schema: typeof CODEX_SEMANTIC_CACHE_WITNESS_SCHEMA;
+    cacheRoot: string;
+    controls: CodexSemanticCacheControl[];
+    appOnlyParents: CodexSemanticCacheAppOnlyParentWitness[];
+    skills: CodexSemanticCacheSkill[];
+    sha256: string;
+}
+export interface CaptureCodexSemanticCacheWitnessOptions {
+    cacheRoot: string;
+    controls: CodexPluginSkillControl[];
+    /** Explicit package-reviewed parents; absence never infers this role. */
+    appOnlyParents?: CodexSemanticCacheAppOnlyParent[];
+    rules: unknown;
+    /** Package-owned, bounded read used by the existing semantic control review. */
+    read?: (path: string) => string;
+}
+/** Capture the current semantic identity without changing the stored baseline.
+ * Existing package-owned parsers validate documents and capability controls. */
+export declare function captureCodexSemanticCacheWitness(options: CaptureCodexSemanticCacheWitnessOptions): CodexSemanticCacheWitness;
+/** Verify without mutating or replacing the saved witness. Version refreshes
+ * pass only when their complete semantic projection and qualified names match. */
+export declare function assertCodexSemanticCacheWitnessUnchanged(previous: CodexSemanticCacheWitness, current: CodexSemanticCacheWitness): void;

package/dist/lib/codex-settings-witness.d.ts

@@ -46,3 +46,17 @@ export declare function upgradeCodexSettingsWitnessV4(previous: {
     hashMode?: "bytes" | "codex-settings-v1" | "codex-settings-v2" | "codex-settings-v3";
     sha256: string;
 }, reviewedSettingsPath: string): ReturnType<typeof captureCodexSettingsV4>;
+/** Explicit V5 adds only schema-valid root status-line string vectors. */
+export declare function hashCodexSettingsReplacementV5(text: string, budget?: ClaudeSettingsWitnessBudget): string;
+export declare function captureCodexSettingsV5(path: string, budget?: ClaudeSettingsWitnessBudget): {
+    path: string;
+    hashMode: "codex-settings-v5";
+    sha256: string;
+};
+/** A V5 hash never verifies an old pin: prove the preserved original under its
+ * exact original contract before comparing old/current under V5. */
+export declare function upgradeCodexSettingsWitnessV5(previous: {
+    path: string;
+    hashMode?: "bytes" | "codex-settings-v1" | "codex-settings-v2" | "codex-settings-v3" | "codex-settings-v4";
+    sha256: string;
+}, reviewedSettingsPath: string): ReturnType<typeof captureCodexSettingsV5>;

package/dist/lib/retained-review-artifacts.d.ts

@@ -0,0 +1,35 @@
+import type { AgentDiscoveryBinding, DiscoverySource } from "./agent-discovery.js";
+export interface ReviewedArtifact {
+    kind: "codex-native-catalog";
+    path: string;
+    sha256: string;
+}
+export interface RetainedReviewArtifact {
+    version: 1;
+    kind: "codex-native-catalog";
+    storeRoot: string;
+    originalPath: string;
+    sha256: string;
+    catalogSha256: string;
+}
+export interface ReviewArtifactChange {
+    path: string;
+    before: null;
+    after: string;
+    artifact: RetainedReviewArtifact;
+}
+export declare function verifyReviewArtifactOriginal(path: string, expectedSha256: string): void;
+export declare function retainedArtifactPath(metadata: RetainedReviewArtifact): string;
+export declare function validRetainedArtifact(value: unknown): value is RetainedReviewArtifact;
+export declare function verifyRetainedReviewArtifact(source: DiscoverySource, storeRoot?: string): void;
+/** Planning only: preserve source bytes and lineage, but create no storage. */
+export declare function planReviewArtifactRetention(binding: AgentDiscoveryBinding, artifacts: ReviewedArtifact[] | undefined, dataDir: string, home: string): {
+    binding: AgentDiscoveryBinding;
+    changes: ReviewArtifactChange[];
+    observed: Array<{
+        path: string;
+        sha256: string;
+    }>;
+};
+/** Publish only an absent exact-byte artifact; existing immutable bytes are never replaced. */
+export declare function writeReviewArtifactExclusive(change: ReviewArtifactChange): void;

package/dist/runtime-prerequisites.js

@@ -49,7 +49,7 @@ var __require = import.meta.require;
 // src/runtime-prerequisites.ts
 import { isAbsolute as isAbsolute5 } from "path";
 // package.json
-var version = "0.10.62";
+var version = "0.10.64";
 var package_default = {
   name: "@hasna/skills",
   version,
@@ -2642,6 +2642,53 @@ function assertAgentPolicyCollections(policy) {
           requireBound(directory.sha256 === null || typeof directory.sha256 === "string" && /^[a-f0-9]{64}$/.test(directory.sha256));
         }
     }
+    if (value.codexSemanticCache !== undefined) {
+      const proof = record(value.codexSemanticCache, 8), witness = record(proof.witness, 6);
+      requireBound(agent === "codex" && value.agent === "codex" && value.method === "reviewed" && Object.keys(proof).length === 8 && proof.schema === "hasna.codex-semantic-cache-discovery.v1" && typeof proof.previousPolicySha256 === "string" && /^[a-f0-9]{64}$/.test(proof.previousPolicySha256) && Object.keys(witness).length === 6 && witness.schema === "hasna.codex-semantic-cache-witness.v1" && typeof witness.sha256 === "string" && /^[a-f0-9]{64}$/.test(witness.sha256));
+      text(proof.configPath);
+      requireBound(isAbsolute3(proof.configPath) && resolve5(proof.configPath) === proof.configPath && basename3(proof.configPath) === "config.toml");
+      text(witness.cacheRoot);
+      requireBound(isAbsolute3(witness.cacheRoot) && resolve5(witness.cacheRoot) === witness.cacheRoot);
+      if (proof.hookRootAlias !== null) {
+        requireBound(object(proof.hookRootAlias) && Object.keys(proof.hookRootAlias).length === 2);
+        for (const key of ["alias", "target"]) {
+          text(proof.hookRootAlias[key]);
+          requireBound(isAbsolute3(proof.hookRootAlias[key]) && resolve5(proof.hookRootAlias[key]) === proof.hookRootAlias[key]);
+        }
+      }
+      const parents2 = array(proof.appOnlyParents, 4096);
+      for (const parent of parents2) {
+        requireBound(object(parent) && Object.keys(parent).length === 5 && parent.role === "app-only");
+        for (const key of ["pluginId", "namespace", "pluginParent", "remotePluginId"])
+          text(parent[key]);
+        requireBound(isAbsolute3(parent.pluginParent) && resolve5(parent.pluginParent) === parent.pluginParent);
+      }
+      for (const row of [...array(witness.controls, 4096), ...array(witness.appOnlyParents, 4096)]) {
+        requireBound(object(row));
+        for (const key of ["pluginId", "namespace", "pluginParent"])
+          text(row[key]);
+        for (const key of ["manifestSha256", "appSha256", "mcpSha256", "receiptSha256"])
+          if (row[key] !== undefined)
+            requireBound(typeof row[key] === "string" && /^[a-f0-9]{64}$/.test(row[key]));
+      }
+      for (const skill of array(witness.skills, 4096)) {
+        requireBound(object(skill));
+        for (const key of ["name", "pluginId", "namespace", "pluginParent"])
+          text(skill[key]);
+        for (const rule of array(skill.disabledRules, 4096))
+          text(rule);
+      }
+      for (const source of array(proof.supersededSources, AGENT_POLICY_LIMITS.discoverySources)) {
+        requireBound(object(source));
+        text(source.path);
+        requireBound(source.sha256 === null || typeof source.sha256 === "string" && /^[a-f0-9]{64}$/.test(source.sha256));
+      }
+      for (const directory of array(proof.supersededDirectories, AGENT_POLICY_LIMITS.discoveryDirectories)) {
+        requireBound(object(directory));
+        text(directory.path);
+        requireBound(directory.sha256 === null || typeof directory.sha256 === "string" && /^[a-f0-9]{64}$/.test(directory.sha256));
+      }
+    }
     for (const root of array(value.roots, AGENT_POLICY_LIMITS.discoveryRoots))
       text(root);
     for (const source of array(value.sources, AGENT_POLICY_LIMITS.discoverySources)) {
@@ -2649,12 +2696,12 @@ 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-manifest-v1", "claude-plugin-registry", "claude-marketplace-registry", "claude-settings-v1", "claude-settings-v2", "claude-settings-v3", "claude-settings-v4", "claude-marketplace-registry-v2", "codex-settings-v1", "codex-settings-v2", "codex-settings-v3", "codex-settings-v4", "sumi-settings-v1", "claude-marketplace-entry-v1"].includes(source.hashMode) && source.format === undefined && source.fields === undefined && (source.hashMode === "bytes" || source.sha256 !== null));
+        requireBound(["bytes", "path-bytes", "claude-plugin-manifest-v1", "claude-plugin-registry", "claude-marketplace-registry", "claude-settings-v1", "claude-settings-v2", "claude-settings-v3", "claude-settings-v4", "claude-marketplace-registry-v2", "codex-settings-v1", "codex-settings-v2", "codex-settings-v3", "codex-settings-v4", "codex-settings-v5", "sumi-settings-v1", "claude-marketplace-entry-v1"].includes(source.hashMode) && source.format === undefined && source.fields === undefined && (source.hashMode === "bytes" || source.sha256 !== null));
       if (source.hashMode === "claude-plugin-manifest-v1")
         requireBound(agent === "claude" && value.agent === "claude" && ["automatic", "reviewed"].includes(value.method) && !/[\x00-\x1f\x7f]/.test(source.path) && isAbsolute3(source.path) && resolve5(source.path) === source.path && source.path.endsWith(join5(sep, ".claude-plugin", "plugin.json")) && source.managedPlugins === undefined);
       if (source.hashMode === "sumi-settings-v1")
         requireBound(agent === "sumi" && value.agent === "sumi" && value.method === "reviewed" && !/[\x00-\x1f\x7f]/.test(source.path) && isAbsolute3(source.path) && resolve5(source.path) === source.path && basename3(source.path) === "sumi.json");
-      if (source.hashMode === "codex-settings-v1" || source.hashMode === "codex-settings-v2" || (source.hashMode === "codex-settings-v3" || source.hashMode === "codex-settings-v4"))
+      if (source.hashMode === "codex-settings-v1" || source.hashMode === "codex-settings-v2" || (source.hashMode === "codex-settings-v3" || source.hashMode === "codex-settings-v4" || source.hashMode === "codex-settings-v5"))
         requireBound(agent === "codex" && value.agent === "codex" && value.method === "reviewed" && !/[\x00-\x1f\x7f]/.test(source.path) && isAbsolute3(source.path) && resolve5(source.path) === source.path && basename3(source.path) === "config.toml");
       if (source.hashMode === "claude-settings-v1" || source.hashMode === "claude-settings-v2" || (source.hashMode === "claude-settings-v3" || source.hashMode === "claude-settings-v4"))
         requireBound(agent === "claude" && value.agent === "claude" && value.method === "reviewed" && !/[\x00-\x1f\x7f]/.test(source.path) && isAbsolute3(source.path) && resolve5(source.path) === source.path && basename3(source.path) === "settings.json");
@@ -2673,6 +2720,15 @@ function assertAgentPolicyCollections(policy) {
         }
       } else
         requireBound(source.managedPlugins === undefined);
+      if (source.reviewArtifact !== undefined) {
+        const artifact = source.reviewArtifact;
+        requireBound(agent === "codex" && value.method === "reviewed" && source.hashMode === "bytes" && object(artifact) && Object.keys(artifact).length === 6 && Object.keys(artifact).every((key) => ["version", "kind", "storeRoot", "originalPath", "sha256", "catalogSha256"].includes(key)) && artifact.version === 1 && artifact.kind === "codex-native-catalog" && artifact.sha256 === source.sha256 && /^[a-f0-9]{64}$/.test(artifact.catalogSha256));
+        for (const path of [artifact.storeRoot, artifact.originalPath]) {
+          text(path);
+          requireBound(isAbsolute3(path) && resolve5(path) === path);
+        }
+        requireBound(source.path === join5(artifact.storeRoot, "agent-discovery", "artifacts", artifact.sha256, "catalog.json"));
+      }
       if (source.format !== undefined)
         requireBound(["json", "toml", "yaml"].includes(source.format));
       if (source.fields !== undefined)