@kitsy/cnos 1.9.2 → 1.10.0

package/dist/internal.cjs

@@ -40,6 +40,7 @@ __export(internal_exports, {
   clearAllVaultSessionKeys: () => clearAllVaultSessionKeys,
   clearVaultSessionKey: () => clearVaultSessionKey,
   compareSchemaToGraph: () => compareSchemaToGraph,
+  compareSpecToGraph: () => compareSpecToGraph,
   createRemoteRootCacheKey: () => createRemoteRootCacheKey,
   createSecretVault: () => createSecretVault,
   createSecretVaultProvider: () => createSecretVaultProvider,
@@ -1033,6 +1034,134 @@ function resolveConfigDocumentPath(workspaceRoot, namespace, configPath, profile
   return import_node_path5.default.resolve(namespaceRoot, fileName);
 }
 
+// ../core/src/spec/normalizeSpecRule.ts
+var ALLOWED_TYPES = /* @__PURE__ */ new Set(["string", "number", "boolean", "object", "array"]);
+var SECRET_FORBIDDEN_FIELDS = ["default", "examples", "enum"];
+function hasOwn(target, key) {
+  return Object.prototype.hasOwnProperty.call(target, key);
+}
+function normalizeOptionalString(value, fieldName, logicalKey) {
+  if (value === void 0) {
+    return void 0;
+  }
+  if (typeof value !== "string") {
+    throw new CnosManifestError(`Invalid schema rule for ${logicalKey}: "${fieldName}" must be a string.`);
+  }
+  const nextValue = value.trim();
+  return nextValue.length > 0 ? nextValue : void 0;
+}
+function normalizeStringArray(value, fieldName, logicalKey) {
+  if (value === void 0) {
+    return void 0;
+  }
+  if (!Array.isArray(value)) {
+    throw new CnosManifestError(`Invalid schema rule for ${logicalKey}: "${fieldName}" must be an array.`);
+  }
+  const nextValue = value.map((entry) => {
+    if (typeof entry !== "string") {
+      throw new CnosManifestError(
+        `Invalid schema rule for ${logicalKey}: "${fieldName}" entries must be strings.`
+      );
+    }
+    return entry.trim();
+  }).filter(Boolean);
+  return nextValue.length > 0 ? nextValue : void 0;
+}
+function normalizeUnknownArray(value, fieldName, logicalKey) {
+  if (value === void 0) {
+    return void 0;
+  }
+  if (!Array.isArray(value)) {
+    throw new CnosManifestError(`Invalid schema rule for ${logicalKey}: "${fieldName}" must be an array.`);
+  }
+  return value.length > 0 ? value : void 0;
+}
+function assertValidPatternRegex(pattern, logicalKey) {
+  try {
+    void new RegExp(pattern);
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    throw new CnosManifestError(
+      `Invalid schema rule for ${logicalKey}: "pattern" must be a valid regex (${reason}).`
+    );
+  }
+}
+function assertSecretRuleSafety(logicalKey, rule) {
+  if (!logicalKey.startsWith("secret.")) {
+    return;
+  }
+  const offendingFields = SECRET_FORBIDDEN_FIELDS.filter((field) => hasOwn(rule, field));
+  if (offendingFields.length === 0) {
+    return;
+  }
+  throw new CnosManifestError(
+    `Invalid schema rule for ${logicalKey}: secret specs cannot include ${offendingFields.join(", ")}. Store secret values in the vault, not schema metadata. Remove ${offendingFields.map((field) => `schema.${logicalKey}.${field}`).join(", ")} to continue.`
+  );
+}
+function normalizeSpecRule(logicalKey, rule) {
+  if (!rule || typeof rule !== "object" || Array.isArray(rule)) {
+    throw new CnosManifestError(`Invalid schema rule for ${logicalKey}: expected an object.`);
+  }
+  const candidate = rule;
+  assertSecretRuleSafety(logicalKey, candidate);
+  const normalized = {};
+  if (candidate.type !== void 0) {
+    if (typeof candidate.type !== "string" || !ALLOWED_TYPES.has(candidate.type)) {
+      throw new CnosManifestError(`Invalid schema rule for ${logicalKey}: unsupported type "${String(candidate.type)}".`);
+    }
+    normalized.type = candidate.type;
+  }
+  if (candidate.required !== void 0) {
+    if (typeof candidate.required !== "boolean") {
+      throw new CnosManifestError(`Invalid schema rule for ${logicalKey}: "required" must be a boolean.`);
+    }
+    normalized.required = candidate.required;
+  }
+  if (hasOwn(candidate, "default")) {
+    normalized.default = candidate.default;
+  }
+  const normalizedEnum = normalizeUnknownArray(candidate.enum, "enum", logicalKey);
+  if (normalizedEnum !== void 0) {
+    normalized.enum = normalizedEnum;
+  }
+  const normalizedPattern = normalizeOptionalString(candidate.pattern, "pattern", logicalKey);
+  if (normalizedPattern !== void 0) {
+    assertValidPatternRegex(normalizedPattern, logicalKey);
+    normalized.pattern = normalizedPattern;
+  }
+  const normalizedSummary = normalizeOptionalString(candidate.summary, "summary", logicalKey);
+  if (normalizedSummary !== void 0) {
+    normalized.summary = normalizedSummary;
+  }
+  const normalizedDescription = normalizeOptionalString(candidate.description, "description", logicalKey);
+  if (normalizedDescription !== void 0) {
+    normalized.description = normalizedDescription;
+  }
+  const normalizedExamples = normalizeUnknownArray(candidate.examples, "examples", logicalKey);
+  if (normalizedExamples !== void 0) {
+    normalized.examples = normalizedExamples;
+  }
+  const normalizedUsedBy = normalizeStringArray(candidate.usedBy, "usedBy", logicalKey);
+  if (normalizedUsedBy !== void 0) {
+    normalized.usedBy = normalizedUsedBy;
+  }
+  if (candidate.deprecated !== void 0) {
+    if (typeof candidate.deprecated !== "boolean") {
+      throw new CnosManifestError(`Invalid schema rule for ${logicalKey}: "deprecated" must be a boolean.`);
+    }
+    normalized.deprecated = candidate.deprecated;
+  }
+  const normalizedDeprecationMessage = normalizeOptionalString(
+    candidate.deprecationMessage,
+    "deprecationMessage",
+    logicalKey
+  );
+  if (normalizedDeprecationMessage !== void 0) {
+    normalized.deprecationMessage = normalizedDeprecationMessage;
+  }
+  return normalized;
+}
+
 // ../core/src/manifest/normalizeManifest.ts
 var DEFAULT_RESOLVE_FROM = ["cli.profile", "env.CNOS_PROFILE", "default"];
 var DEFAULT_LOADERS = [
@@ -1231,6 +1360,14 @@ function normalizeVaultAuth(vaultName, provider, auth) {
     ...auth?.config ? { config: auth.config } : {}
   };
 }
+function normalizeSchema(schema) {
+  return Object.fromEntries(
+    Object.entries(schema ?? {}).map(([logicalKey, rule]) => [
+      logicalKey,
+      normalizeSpecRule(logicalKey, rule)
+    ])
+  );
+}
 function normalizeManifest(manifest) {
   const version = manifest.version ?? 1;
   if (version !== 1) {
@@ -1328,7 +1465,7 @@ function normalizeManifest(manifest) {
         }
       }
     },
-    schema: manifest.schema ?? {}
+    schema: normalizeSchema(manifest.schema)
   };
 }
 
@@ -1836,16 +1973,19 @@ async function removeLocalVaultFiles(storeRoot, vault = "default") {
 // ../core/src/secrets/auditLog.ts
 async function appendAuditEvent(event, processEnv = process.env) {
   const auditFile = processEnv.CNOS_AUDIT_FILE ?? import_node_path12.default.join(resolveSecretStoreRoot(processEnv), "audit", "access.log");
-  await (0, import_promises11.mkdir)(import_node_path12.default.dirname(auditFile), { recursive: true });
-  await (0, import_promises11.appendFile)(
-    auditFile,
-    `${JSON.stringify({
-      ts: (/* @__PURE__ */ new Date()).toISOString(),
-      ...event
-    })}
+  try {
+    await (0, import_promises11.mkdir)(import_node_path12.default.dirname(auditFile), { recursive: true });
+    await (0, import_promises11.appendFile)(
+      auditFile,
+      `${JSON.stringify({
+        ts: (/* @__PURE__ */ new Date()).toISOString(),
+        ...event
+      })}
 `,
-    "utf8"
-  );
+      "utf8"
+    );
+  } catch {
+  }
 }
 
 // ../core/src/secrets/providers/environment.ts
@@ -2580,7 +2720,7 @@ async function watchSchema(options = {}) {
   return watcher;
 }
 
-// src/drift/compareSchemaToGraph.ts
+// src/spec/compareSpecToGraph.ts
 function describeValueType(value) {
   if (Array.isArray(value)) {
     return "array";
@@ -2603,6 +2743,17 @@ function matchesType(value, type) {
       return typeof value === type;
   }
 }
+function enumMatches(value, allowed) {
+  const serialized = JSON.stringify(value);
+  return allowed.some((candidate) => JSON.stringify(candidate) === serialized);
+}
+function matchesPattern(pattern, value) {
+  try {
+    return new RegExp(pattern).test(value);
+  } catch {
+    return false;
+  }
+}
 function isSchemaDefault(entry) {
   return entry.winner.metadata?.schemaDefault === true;
 }
@@ -2612,34 +2763,53 @@ function shouldTrackKey(key) {
 function isTransientRuntimeSource(entry) {
   return entry.winner.sourceId === "process-env" || entry.winner.sourceId === "cli-args";
 }
-function compareSchemaToGraph(runtime) {
+function buildSummary(issues) {
+  return {
+    missingRequired: issues.filter((issue) => issue.status === "missing_required").length,
+    undeclared: issues.filter((issue) => issue.status === "undeclared").length,
+    typeMismatch: issues.filter((issue) => issue.status === "type_mismatch").length,
+    enumMismatch: issues.filter((issue) => issue.status === "enum_mismatch").length,
+    patternMismatch: issues.filter((issue) => issue.status === "pattern_mismatch").length,
+    defaultApplied: issues.filter((issue) => issue.status === "default_applied").length,
+    deprecatedInUse: issues.filter((issue) => issue.status === "deprecated_in_use").length
+  };
+}
+function compareSpecToGraph(runtime) {
   const schema = runtime.manifest.schema;
-  const missing = [];
-  const mismatches = [];
-  const defaultsApplied = [];
+  const issues = [];
   for (const [key, rule] of Object.entries(schema).sort(([left], [right]) => left.localeCompare(right))) {
     const entry = runtime.graph.entries.get(key);
+    const summary = rule.summary;
     if (!entry) {
       if (rule.required && rule.default === void 0) {
-        missing.push({
+        issues.push({
           key,
+          status: "missing_required",
           ...rule.type ? {
             expectedType: rule.type
+          } : {},
+          ...summary ? {
+            summary
           } : {}
         });
       }
       continue;
     }
     if (isSchemaDefault(entry)) {
-      defaultsApplied.push({
+      issues.push({
         key,
-        value: entry.value
+        status: "default_applied",
+        value: entry.value,
+        ...summary ? {
+          summary
+        } : {}
       });
     }
     const actualValue = entry.winner.value;
     if (!matchesType(actualValue, rule.type)) {
-      mismatches.push({
+      issues.push({
         key,
+        status: "type_mismatch",
         ...rule.type ? {
           expectedType: rule.type
         } : {},
@@ -2647,26 +2817,113 @@ function compareSchemaToGraph(runtime) {
         value: actualValue,
         ...entry.winner.origin?.file ? {
           sourceFile: entry.winner.origin.file
+        } : {},
+        ...summary ? {
+          summary
+        } : {}
+      });
+    }
+    if (rule.enum && !enumMatches(actualValue, rule.enum)) {
+      issues.push({
+        key,
+        status: "enum_mismatch",
+        value: actualValue,
+        ...summary ? {
+          summary
+        } : {}
+      });
+    }
+    if (rule.pattern) {
+      if (typeof actualValue !== "string" || !matchesPattern(rule.pattern, actualValue)) {
+        issues.push({
+          key,
+          status: "pattern_mismatch",
+          value: actualValue,
+          pattern: rule.pattern,
+          ...summary ? {
+            summary
+          } : {}
+        });
+      }
+    }
+    if (rule.deprecated) {
+      issues.push({
+        key,
+        status: "deprecated_in_use",
+        value: actualValue,
+        ...summary ? {
+          summary
         } : {}
       });
     }
   }
-  const undeclared = Array.from(runtime.graph.entries.values()).filter(
+  const undeclaredIssues = Array.from(runtime.graph.entries.values()).filter(
     (entry) => shouldTrackKey(entry.key) && !schema[entry.key] && !isSchemaDefault(entry) && !isTransientRuntimeSource(entry)
-  ).map((entry) => {
-    const issue = {
-      key: entry.key,
-      value: entry.winner.value,
-      actualType: describeValueType(entry.winner.value)
-    };
-    if (entry.winner.origin?.file) {
-      issue.sourceFile = entry.winner.origin.file;
-    }
-    return issue;
-  }).sort((left, right) => left.key.localeCompare(right.key));
+  ).map((entry) => ({
+    key: entry.key,
+    status: "undeclared",
+    value: entry.winner.value,
+    actualType: describeValueType(entry.winner.value),
+    ...entry.winner.origin?.file ? {
+      sourceFile: entry.winner.origin.file
+    } : {}
+  })).sort((left, right) => left.key.localeCompare(right.key));
+  const allIssues = [...issues, ...undeclaredIssues].sort((left, right) => left.key.localeCompare(right.key));
   return {
     profile: runtime.graph.profile,
     workspace: runtime.graph.workspace.workspaceId,
+    summary: buildSummary(allIssues),
+    issues: allIssues
+  };
+}
+
+// src/drift/compareSchemaToGraph.ts
+function compareSchemaToGraph(runtime) {
+  const report = compareSpecToGraph(runtime);
+  const missing = report.issues.filter((issue) => issue.status === "missing_required").map(
+    (issue) => ({
+      key: issue.key,
+      ...issue.expectedType ? {
+        expectedType: issue.expectedType
+      } : {}
+    })
+  );
+  const undeclared = report.issues.filter((issue) => issue.status === "undeclared").map(
+    (issue) => ({
+      key: issue.key,
+      value: issue.value,
+      ...issue.actualType ? {
+        actualType: issue.actualType
+      } : {},
+      ...issue.sourceFile ? {
+        sourceFile: issue.sourceFile
+      } : {}
+    })
+  );
+  const mismatches = report.issues.filter((issue) => issue.status === "type_mismatch").map(
+    (issue) => ({
+      key: issue.key,
+      ...issue.expectedType ? {
+        expectedType: issue.expectedType
+      } : {},
+      ...issue.actualType ? {
+        actualType: issue.actualType
+      } : {},
+      value: issue.value,
+      ...issue.sourceFile ? {
+        sourceFile: issue.sourceFile
+      } : {}
+    })
+  );
+  const defaultsApplied = report.issues.filter((issue) => issue.status === "default_applied").map(
+    (issue) => ({
+      key: issue.key,
+      value: issue.value
+    })
+  );
+  return {
+    profile: report.profile,
+    workspace: report.workspace,
     missing,
     undeclared,
     mismatches,
@@ -2978,6 +3235,7 @@ async function watchFiles(runtime, root) {
   clearAllVaultSessionKeys,
   clearVaultSessionKey,
   compareSchemaToGraph,
+  compareSpecToGraph,
   createRemoteRootCacheKey,
   createSecretVault,
   createSecretVaultProvider,

package/dist/internal.d.cts

@@ -1,5 +1,5 @@
-import { j as DerivedValue, P as ParsedDerivation, N as NormalizedManifest, n as LoadManifestOptions, o as LoadedManifest, b as LogicalKey, p as NamespaceDefinition, q as VaultDefinition, r as VaultAuthConfig, s as SecretVaultProvider, t as ResolvedRoot, m as NamespaceName, u as RootResolution, v as SecretReference, g as CnosRuntime, w as ValidationSummary, R as ResolvedGraph, S as ServerProjection } from './core-zDTUSVx9.cjs';
-export { l as RuntimeProvider, x as ValidationIssue, y as WorkspaceFile } from './core-zDTUSVx9.cjs';
+import { j as DerivedValue, P as ParsedDerivation, N as NormalizedManifest, n as LoadManifestOptions, o as LoadedManifest, b as LogicalKey, p as NamespaceDefinition, q as VaultDefinition, r as VaultAuthConfig, s as SecretVaultProvider, t as ResolvedRoot, m as NamespaceName, u as RootResolution, v as SecretReference, g as CnosRuntime, w as ValidationSummary, R as ResolvedGraph, S as ServerProjection } from './core-Ud1o2MBn.cjs';
+export { l as RuntimeProvider, x as ValidationIssue, y as WorkspaceFile } from './core-Ud1o2MBn.cjs';
 
 declare class CnosError extends Error {
     constructor(message: string);
@@ -189,6 +189,34 @@ interface CnosWatchHandle {
 }
 declare function watchSchema(options?: WatchSchemaOptions): Promise<CnosWatchHandle>;
 
+type SpecComparisonStatus = 'missing_required' | 'undeclared' | 'type_mismatch' | 'enum_mismatch' | 'pattern_mismatch' | 'default_applied' | 'deprecated_in_use';
+interface SpecComparisonIssue {
+    key: string;
+    status: SpecComparisonStatus;
+    expectedType?: string;
+    actualType?: string;
+    value?: unknown;
+    sourceFile?: string;
+    summary?: string;
+    pattern?: string;
+}
+interface SpecComparisonSummary {
+    missingRequired: number;
+    undeclared: number;
+    typeMismatch: number;
+    enumMismatch: number;
+    patternMismatch: number;
+    defaultApplied: number;
+    deprecatedInUse: number;
+}
+interface SpecComparisonReport {
+    profile: string;
+    workspace: string;
+    summary: SpecComparisonSummary;
+    issues: SpecComparisonIssue[];
+}
+declare function compareSpecToGraph(runtime: CnosRuntime): SpecComparisonReport;
+
 interface DriftIssue {
     key: string;
     expectedType?: string;
@@ -249,4 +277,4 @@ interface WatchTargetSet {
 }
 declare function watchFiles(runtime: CnosRuntime, root?: string): Promise<WatchTargetSet>;
 
-export { CNOS_GRAPH_ENV_VAR, CNOS_PROJECTION_ENV_VAR, CNOS_SECRET_PAYLOAD_ENV_VAR, CNOS_SESSION_KEY_ENV_VAR, CnosAuthenticationError, CnosSecurityError, DerivedValue, ParsedDerivation, type RemoteRootCacheMetadata, type ResolvedVaultDefinition, RootResolution, SecretReference, ValidationSummary, VaultDefinition, applyManifestMappings, clearAllVaultSessionKeys, clearVaultSessionKey, compareSchemaToGraph, createRemoteRootCacheKey, createSecretVault, createSecretVaultProvider, deleteLocalSecret, deriveVaultKey, deserializeRuntimeGraph, deserializeServerProjection, detectLegacyVaultFormat, diffGraphs, ensureProjectionAllowed, flattenObject, formatDriftReport, generateCodegenContent, getNamespaceDefinition, getVaultPassphraseEnvVar, getVaultSessionKeyEnvVar, graphRequiresSecretHydration, isDerivedValue, isImmutableGitRef, isPassphraseEnvRef, isSecretReference, listLocalSecrets, listSecretVaults, loadManifest, normalizeDerivedValue, parseDerivation, parseGitUri, parseYaml, proposeMapping, readKeychain, readLocalSecret, readRemoteRootCacheMetadata, readRuntimeGraphFromEnv, readServerProjectionFromEnv, readVaultMetadata, removeLocalVaultFiles, resolveCnosCacheRoot, resolveCodegenPaths, resolveConfigDocumentPath, resolveConfiguredVaultPassphrase, resolveManifestRoot, resolveRemoteRootCachePaths, resolveRootUri, resolveSecretPassphrase, resolveSecretStoreRoot, resolveSecretVaultFile, resolveVaultAccessKey, resolveVaultAuth, resolveVaultDefinition, rewriteSourceFiles, scanEnvUsage, serializeRuntimeGraph, serializeSecretPayload, serializeServerProjection, stringifyYaml, validateDerivedTargetNamespace, validateParsedDerivation, validateRuntime, watchFiles, watchSchema, writeCodegenOutput, writeKeychain, writeLocalSecret, writeRemoteRootCacheMetadata, writeVaultSessionKey };
+export { CNOS_GRAPH_ENV_VAR, CNOS_PROJECTION_ENV_VAR, CNOS_SECRET_PAYLOAD_ENV_VAR, CNOS_SESSION_KEY_ENV_VAR, CnosAuthenticationError, CnosSecurityError, DerivedValue, ParsedDerivation, type RemoteRootCacheMetadata, type ResolvedVaultDefinition, RootResolution, SecretReference, ValidationSummary, VaultDefinition, applyManifestMappings, clearAllVaultSessionKeys, clearVaultSessionKey, compareSchemaToGraph, compareSpecToGraph, createRemoteRootCacheKey, createSecretVault, createSecretVaultProvider, deleteLocalSecret, deriveVaultKey, deserializeRuntimeGraph, deserializeServerProjection, detectLegacyVaultFormat, diffGraphs, ensureProjectionAllowed, flattenObject, formatDriftReport, generateCodegenContent, getNamespaceDefinition, getVaultPassphraseEnvVar, getVaultSessionKeyEnvVar, graphRequiresSecretHydration, isDerivedValue, isImmutableGitRef, isPassphraseEnvRef, isSecretReference, listLocalSecrets, listSecretVaults, loadManifest, normalizeDerivedValue, parseDerivation, parseGitUri, parseYaml, proposeMapping, readKeychain, readLocalSecret, readRemoteRootCacheMetadata, readRuntimeGraphFromEnv, readServerProjectionFromEnv, readVaultMetadata, removeLocalVaultFiles, resolveCnosCacheRoot, resolveCodegenPaths, resolveConfigDocumentPath, resolveConfiguredVaultPassphrase, resolveManifestRoot, resolveRemoteRootCachePaths, resolveRootUri, resolveSecretPassphrase, resolveSecretStoreRoot, resolveSecretVaultFile, resolveVaultAccessKey, resolveVaultAuth, resolveVaultDefinition, rewriteSourceFiles, scanEnvUsage, serializeRuntimeGraph, serializeSecretPayload, serializeServerProjection, stringifyYaml, validateDerivedTargetNamespace, validateParsedDerivation, validateRuntime, watchFiles, watchSchema, writeCodegenOutput, writeKeychain, writeLocalSecret, writeRemoteRootCacheMetadata, writeVaultSessionKey };

package/dist/internal.d.ts

@@ -1,5 +1,5 @@
-import { j as DerivedValue, P as ParsedDerivation, N as NormalizedManifest, n as LoadManifestOptions, o as LoadedManifest, b as LogicalKey, p as NamespaceDefinition, q as VaultDefinition, r as VaultAuthConfig, s as SecretVaultProvider, t as ResolvedRoot, m as NamespaceName, u as RootResolution, v as SecretReference, g as CnosRuntime, w as ValidationSummary, R as ResolvedGraph, S as ServerProjection } from './core-zDTUSVx9.js';
-export { l as RuntimeProvider, x as ValidationIssue, y as WorkspaceFile } from './core-zDTUSVx9.js';
+import { j as DerivedValue, P as ParsedDerivation, N as NormalizedManifest, n as LoadManifestOptions, o as LoadedManifest, b as LogicalKey, p as NamespaceDefinition, q as VaultDefinition, r as VaultAuthConfig, s as SecretVaultProvider, t as ResolvedRoot, m as NamespaceName, u as RootResolution, v as SecretReference, g as CnosRuntime, w as ValidationSummary, R as ResolvedGraph, S as ServerProjection } from './core-Ud1o2MBn.js';
+export { l as RuntimeProvider, x as ValidationIssue, y as WorkspaceFile } from './core-Ud1o2MBn.js';
 
 declare class CnosError extends Error {
     constructor(message: string);
@@ -189,6 +189,34 @@ interface CnosWatchHandle {
 }
 declare function watchSchema(options?: WatchSchemaOptions): Promise<CnosWatchHandle>;
 
+type SpecComparisonStatus = 'missing_required' | 'undeclared' | 'type_mismatch' | 'enum_mismatch' | 'pattern_mismatch' | 'default_applied' | 'deprecated_in_use';
+interface SpecComparisonIssue {
+    key: string;
+    status: SpecComparisonStatus;
+    expectedType?: string;
+    actualType?: string;
+    value?: unknown;
+    sourceFile?: string;
+    summary?: string;
+    pattern?: string;
+}
+interface SpecComparisonSummary {
+    missingRequired: number;
+    undeclared: number;
+    typeMismatch: number;
+    enumMismatch: number;
+    patternMismatch: number;
+    defaultApplied: number;
+    deprecatedInUse: number;
+}
+interface SpecComparisonReport {
+    profile: string;
+    workspace: string;
+    summary: SpecComparisonSummary;
+    issues: SpecComparisonIssue[];
+}
+declare function compareSpecToGraph(runtime: CnosRuntime): SpecComparisonReport;
+
 interface DriftIssue {
     key: string;
     expectedType?: string;
@@ -249,4 +277,4 @@ interface WatchTargetSet {
 }
 declare function watchFiles(runtime: CnosRuntime, root?: string): Promise<WatchTargetSet>;
 
-export { CNOS_GRAPH_ENV_VAR, CNOS_PROJECTION_ENV_VAR, CNOS_SECRET_PAYLOAD_ENV_VAR, CNOS_SESSION_KEY_ENV_VAR, CnosAuthenticationError, CnosSecurityError, DerivedValue, ParsedDerivation, type RemoteRootCacheMetadata, type ResolvedVaultDefinition, RootResolution, SecretReference, ValidationSummary, VaultDefinition, applyManifestMappings, clearAllVaultSessionKeys, clearVaultSessionKey, compareSchemaToGraph, createRemoteRootCacheKey, createSecretVault, createSecretVaultProvider, deleteLocalSecret, deriveVaultKey, deserializeRuntimeGraph, deserializeServerProjection, detectLegacyVaultFormat, diffGraphs, ensureProjectionAllowed, flattenObject, formatDriftReport, generateCodegenContent, getNamespaceDefinition, getVaultPassphraseEnvVar, getVaultSessionKeyEnvVar, graphRequiresSecretHydration, isDerivedValue, isImmutableGitRef, isPassphraseEnvRef, isSecretReference, listLocalSecrets, listSecretVaults, loadManifest, normalizeDerivedValue, parseDerivation, parseGitUri, parseYaml, proposeMapping, readKeychain, readLocalSecret, readRemoteRootCacheMetadata, readRuntimeGraphFromEnv, readServerProjectionFromEnv, readVaultMetadata, removeLocalVaultFiles, resolveCnosCacheRoot, resolveCodegenPaths, resolveConfigDocumentPath, resolveConfiguredVaultPassphrase, resolveManifestRoot, resolveRemoteRootCachePaths, resolveRootUri, resolveSecretPassphrase, resolveSecretStoreRoot, resolveSecretVaultFile, resolveVaultAccessKey, resolveVaultAuth, resolveVaultDefinition, rewriteSourceFiles, scanEnvUsage, serializeRuntimeGraph, serializeSecretPayload, serializeServerProjection, stringifyYaml, validateDerivedTargetNamespace, validateParsedDerivation, validateRuntime, watchFiles, watchSchema, writeCodegenOutput, writeKeychain, writeLocalSecret, writeRemoteRootCacheMetadata, writeVaultSessionKey };
+export { CNOS_GRAPH_ENV_VAR, CNOS_PROJECTION_ENV_VAR, CNOS_SECRET_PAYLOAD_ENV_VAR, CNOS_SESSION_KEY_ENV_VAR, CnosAuthenticationError, CnosSecurityError, DerivedValue, ParsedDerivation, type RemoteRootCacheMetadata, type ResolvedVaultDefinition, RootResolution, SecretReference, ValidationSummary, VaultDefinition, applyManifestMappings, clearAllVaultSessionKeys, clearVaultSessionKey, compareSchemaToGraph, compareSpecToGraph, createRemoteRootCacheKey, createSecretVault, createSecretVaultProvider, deleteLocalSecret, deriveVaultKey, deserializeRuntimeGraph, deserializeServerProjection, detectLegacyVaultFormat, diffGraphs, ensureProjectionAllowed, flattenObject, formatDriftReport, generateCodegenContent, getNamespaceDefinition, getVaultPassphraseEnvVar, getVaultSessionKeyEnvVar, graphRequiresSecretHydration, isDerivedValue, isImmutableGitRef, isPassphraseEnvRef, isSecretReference, listLocalSecrets, listSecretVaults, loadManifest, normalizeDerivedValue, parseDerivation, parseGitUri, parseYaml, proposeMapping, readKeychain, readLocalSecret, readRemoteRootCacheMetadata, readRuntimeGraphFromEnv, readServerProjectionFromEnv, readVaultMetadata, removeLocalVaultFiles, resolveCnosCacheRoot, resolveCodegenPaths, resolveConfigDocumentPath, resolveConfiguredVaultPassphrase, resolveManifestRoot, resolveRemoteRootCachePaths, resolveRootUri, resolveSecretPassphrase, resolveSecretStoreRoot, resolveSecretVaultFile, resolveVaultAccessKey, resolveVaultAuth, resolveVaultDefinition, rewriteSourceFiles, scanEnvUsage, serializeRuntimeGraph, serializeSecretPayload, serializeServerProjection, stringifyYaml, validateDerivedTargetNamespace, validateParsedDerivation, validateRuntime, watchFiles, watchSchema, writeCodegenOutput, writeKeychain, writeLocalSecret, writeRemoteRootCacheMetadata, writeVaultSessionKey };