@hasna/skills 0.10.63 → 0.10.64

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

@@ -4,19 +4,34 @@ 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[];
@@ -76,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

@@ -48,6 +48,7 @@ export interface AgentConfigChange {
     after: string;
 }
 export interface AgentIntegrationPlan {
+    cacheWitnessUpgrade?: CodexSemanticCacheUpgrade;
     reviewArtifactSources?: Array<{
         path: string;
         sha256: string;
@@ -202,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;
@@ -211,6 +212,18 @@ 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;

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/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.63";
+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");