arkgate 3.0.4 → 3.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (42) hide show
  1. package/CHANGELOG.md +82 -1
  2. package/README.md +29 -9
  3. package/bin/ark-check.mjs +69 -54
  4. package/bin/ark-mcp.mjs +267 -26
  5. package/bin/ark.mjs +50 -3
  6. package/bin/lib/adapter-contract.mjs +27 -1
  7. package/bin/lib/agent-gates.mjs +9 -0
  8. package/bin/lib/analysis-engine.mjs +7 -1169
  9. package/bin/lib/ci-and-commands.mjs +4 -0
  10. package/bin/lib/codex-home.mjs +10 -1
  11. package/bin/lib/doctor-plan.mjs +37 -9
  12. package/bin/lib/host-support-matrix.mjs +6 -2
  13. package/bin/lib/install-migrate.mjs +81 -25
  14. package/bin/lib/mcp-adoption.mjs +8 -0
  15. package/bin/lib/policy-delta-io.mjs +161 -0
  16. package/bin/lib/prepare-change.mjs +186 -0
  17. package/bin/lib/remediation.mjs +24 -0
  18. package/bin/lib/skill-install.mjs +302 -22
  19. package/bin/lib/violations.mjs +2 -2
  20. package/bin/lib/weakest-link.mjs +61 -12
  21. package/bin/lib/write-path-capabilities.mjs +70 -2
  22. package/bin/lib/write-path-detect.mjs +18 -11
  23. package/dist/eslint/index.cjs +3 -977
  24. package/dist/eslint/index.js +3 -931
  25. package/dist/index.cjs +6 -1960
  26. package/dist/index.d.cts +152 -5
  27. package/dist/index.d.ts +152 -5
  28. package/dist/index.js +6 -1908
  29. package/docs/agent-guide.md +16 -2
  30. package/docs/ai-gates.md +35 -3
  31. package/docs/configuration.md +44 -0
  32. package/docs/package-surface.md +8 -1
  33. package/docs/threat-model.md +7 -4
  34. package/package.json +6 -5
  35. package/schemas/ark.analysis-result.schema.json +5 -1
  36. package/schemas/ark.change-map.schema.json +77 -0
  37. package/server.json +2 -2
  38. package/templates/skills/ark-upgrade.md +9 -5
  39. package/docs/ark-check-example.json +0 -87
  40. package/docs/demos/03-copilot-autopilot.md +0 -93
  41. package/docs/migrate-from-ark-runtime-kernel.md +0 -174
  42. package/docs/production-hardening.md +0 -100
package/dist/index.d.cts CHANGED
@@ -2,10 +2,10 @@ import { a as ArkConfigRule, b as ArkConfigLayer, A as ArkConfig, c as ArkConfig
2
2
  export { d as ARK_CONFIG_SCHEMA, e as ARK_CONFIG_SCHEMA_VERSION, l as loadArkConfigContract, p as parseArkConfigJson } from './configContract-BxSIwVRo.cjs';
3
3
 
4
4
  /** ArkGate library version — single source of truth. */
5
- declare const version = "3.0.4";
5
+ declare const version = "3.1.0";
6
6
 
7
7
  /** Versioned public result contract shared by every ArkGate enforcement adapter. */
8
- declare const ARK_ANALYSIS_RESULT_SCHEMA_VERSION: "1.0";
8
+ declare const ARK_ANALYSIS_RESULT_SCHEMA_VERSION: "1.1";
9
9
  type AdapterSeverity = 'error' | 'warning';
10
10
  type AdapterViolationInput = {
11
11
  ruleId?: unknown;
@@ -18,7 +18,11 @@ type AdapterViolationInput = {
18
18
  fromLayer?: unknown;
19
19
  toLayer?: unknown;
20
20
  typeOnly?: unknown;
21
+ targetTypeOnlyExports?: unknown;
22
+ namedBindingsTypeOnly?: unknown;
23
+ peerIsolation?: unknown;
21
24
  severity?: unknown;
25
+ nextAction?: unknown;
22
26
  };
23
27
  type AdapterDiagnostic = {
24
28
  ruleId: string;
@@ -35,9 +39,11 @@ type AdapterDiagnostic = {
35
39
  toLayer?: string;
36
40
  typeOnly?: boolean;
37
41
  };
42
+ /** Added in schema 1.1; optional in TypeScript so 1.0 consumer-owned values remain valid. */
43
+ nextAction?: string;
38
44
  };
39
45
  type AdapterResult = {
40
- schemaVersion: typeof ARK_ANALYSIS_RESULT_SCHEMA_VERSION;
46
+ schemaVersion: '1.0' | typeof ARK_ANALYSIS_RESULT_SCHEMA_VERSION;
41
47
  valid: boolean;
42
48
  diagnostics: AdapterDiagnostic[];
43
49
  };
@@ -56,7 +62,7 @@ declare const ARK_ANALYSIS_RESULT_SCHEMA: {
56
62
  readonly required: readonly ["schemaVersion", "valid", "diagnostics"];
57
63
  readonly properties: {
58
64
  readonly schemaVersion: {
59
- readonly const: "1.0";
65
+ readonly const: "1.1";
60
66
  };
61
67
  readonly valid: {
62
68
  readonly type: "boolean";
@@ -116,6 +122,10 @@ declare const ARK_ANALYSIS_RESULT_SCHEMA: {
116
122
  };
117
123
  };
118
124
  };
125
+ readonly nextAction: {
126
+ readonly type: "string";
127
+ readonly minLength: 1;
128
+ };
119
129
  };
120
130
  };
121
131
  };
@@ -481,6 +491,96 @@ declare function deterministicHash(value: string): string;
481
491
  /** Serialize JSON-like values with sorted object keys for reproducible hashes. */
482
492
  declare function stableSerialize(value: unknown): string;
483
493
 
494
+ declare const POLICY_DELTA_SCHEMA_VERSION: "1.0";
495
+ type PolicyDeltaClassification = 'strengthening' | 'neutral' | 'judgment-required' | 'weakening';
496
+ type PolicyDeltaFinding = {
497
+ id: string;
498
+ path: string;
499
+ classification: Exclude<PolicyDeltaClassification, 'neutral'>;
500
+ message: string;
501
+ nextAction?: string;
502
+ before?: unknown;
503
+ after?: unknown;
504
+ };
505
+ type PolicyDelta = {
506
+ schemaVersion: typeof POLICY_DELTA_SCHEMA_VERSION;
507
+ classification: PolicyDeltaClassification;
508
+ findings: PolicyDeltaFinding[];
509
+ };
510
+ type PolicyDeltaAcknowledgement = {
511
+ schemaVersion: typeof POLICY_DELTA_SCHEMA_VERSION;
512
+ basePolicyHash: string;
513
+ candidatePolicyHash: string;
514
+ findingIds: readonly string[];
515
+ reason: string;
516
+ };
517
+ declare function classifyArkPolicyDelta(base: ArkConfig, candidate: ArkConfig): PolicyDelta;
518
+ declare function policyDeltaAcknowledgementMatches(acknowledgement: PolicyDeltaAcknowledgement | undefined, expected: {
519
+ basePolicyHash: string;
520
+ candidatePolicyHash: string;
521
+ findingIds: readonly string[];
522
+ }): boolean;
523
+
524
+ declare const ARK_CHANGE_MAP_SCHEMA_VERSION: "1.0";
525
+ type ArchitectureChangeOperation = 'create' | 'update' | 'delete';
526
+ type ArchitectureChangeMapFile = {
527
+ path: string;
528
+ operation: ArchitectureChangeOperation;
529
+ layer: string;
530
+ };
531
+ type ArchitectureChangeMapDependency = {
532
+ from: string;
533
+ to: string;
534
+ };
535
+ type ArchitectureChangeMap = {
536
+ $schema: string;
537
+ schemaVersion: typeof ARK_CHANGE_MAP_SCHEMA_VERSION;
538
+ files: ArchitectureChangeMapFile[];
539
+ dependencies: ArchitectureChangeMapDependency[];
540
+ };
541
+ type ArchitectureChangeMapContract = {
542
+ map: ArchitectureChangeMap;
543
+ hash: string;
544
+ };
545
+
546
+ type ArchitectureDependency = {
547
+ from: string;
548
+ to: string;
549
+ };
550
+ type ArchitectureActualChange = {
551
+ path: string;
552
+ operation: ArchitectureChangeOperation;
553
+ };
554
+ type ArchitectureConvergenceClassification = 'satisfied' | 'missing' | 'contradictory' | 'unplanned';
555
+ type ArchitectureConvergenceFinding = {
556
+ id: string;
557
+ classification: ArchitectureConvergenceClassification;
558
+ subject: 'file' | 'dependency';
559
+ message: string;
560
+ nextAction?: string;
561
+ path?: string;
562
+ from?: string;
563
+ to?: string;
564
+ expectedOperation?: ArchitectureChangeOperation;
565
+ actualOperation?: ArchitectureChangeOperation | 'added' | 'removed';
566
+ };
567
+ type ArchitectureConvergenceResult = {
568
+ schemaVersion: '1.0';
569
+ readOnly: true;
570
+ changeMapHash: string;
571
+ structurallyConverged: boolean;
572
+ behavioralCompletion: 'not-evaluated';
573
+ summary: Record<ArchitectureConvergenceClassification, number>;
574
+ findings: ArchitectureConvergenceFinding[];
575
+ };
576
+ type AnalyzeArchitectureConvergenceInput = {
577
+ changeMap: ArchitectureChangeMapContract;
578
+ changes: readonly ArchitectureActualChange[];
579
+ baseDependencies: readonly ArchitectureDependency[];
580
+ candidateDependencies: readonly ArchitectureDependency[];
581
+ };
582
+ declare function analyzeArchitectureConvergence(input: AnalyzeArchitectureConvergenceInput): ArchitectureConvergenceResult;
583
+
484
584
  type SemanticDependencyKind = 'import' | 'export' | 'dynamic-import' | 'require';
485
585
  type SemanticDependency = {
486
586
  specifier?: string;
@@ -510,10 +610,29 @@ type AnalyzeProjectInput = {
510
610
  };
511
611
  type AnalyzeChangeInput = AnalyzeProjectInput & {
512
612
  changes: readonly AnalysisFileChange[];
613
+ changeMap?: ArchitectureChangeMapContract;
513
614
  };
514
615
  type AnalysisResult = {
515
616
  ir: AnalysisIr;
516
617
  };
618
+ type AnalyzePolicyDeltaInput = {
619
+ baseConfig: unknown;
620
+ candidateConfig: unknown;
621
+ acknowledgement?: PolicyDeltaAcknowledgement;
622
+ baseSource?: string;
623
+ candidateSource?: string;
624
+ };
625
+ type PolicyDeltaAnalysis = {
626
+ schemaVersion: '1.0';
627
+ basePolicyHash: string;
628
+ candidatePolicyHash: string;
629
+ classification: PolicyDeltaClassification;
630
+ findings: PolicyDeltaFinding[];
631
+ blockingFindingIds: string[];
632
+ requiresAcknowledgement: boolean;
633
+ acknowledged: boolean;
634
+ valid: boolean;
635
+ };
517
636
  type ArchitectureEngineViolation = {
518
637
  ruleId: string;
519
638
  message: string;
@@ -522,6 +641,7 @@ type ArchitectureEngineViolation = {
522
641
  target?: string;
523
642
  fromLayer?: string;
524
643
  toLayer?: string;
644
+ nextAction?: string;
525
645
  [key: string]: unknown;
526
646
  };
527
647
  type ArchitectureEngineEdge = {
@@ -551,6 +671,26 @@ type ArchitectureEngineResult = {
551
671
  warnings: ArchitectureEngineViolation[];
552
672
  safety?: unknown;
553
673
  };
674
+ type PreparedChangeFile = {
675
+ path: string;
676
+ operation: 'create' | 'update' | 'delete';
677
+ beforeContentHash?: string;
678
+ candidateContentHash?: string;
679
+ };
680
+ type ChangePreflightResult = {
681
+ schemaVersion: '1.0';
682
+ valid: boolean;
683
+ readOnly: true;
684
+ policyHash: string;
685
+ compilerOptionsHash: string;
686
+ baseTreeHash: string;
687
+ candidateTreeHash: string;
688
+ changeMapHash?: string;
689
+ convergence?: ArchitectureConvergenceResult;
690
+ changes: PreparedChangeFile[];
691
+ violations: ArchitectureEngineViolation[];
692
+ warnings: ArchitectureEngineViolation[];
693
+ };
554
694
  type CollectAnalysisConfigWarningsInput = {
555
695
  config: ArkConfig;
556
696
  rules: ArkConfig['rules'];
@@ -565,13 +705,20 @@ type CollectAnalysisConfigWarningsInput = {
565
705
  };
566
706
  };
567
707
  declare function loadContract(input: unknown, source?: string): AnalysisContract;
708
+ declare function analyzePolicyDelta(input: AnalyzePolicyDeltaInput): PolicyDeltaAnalysis;
568
709
  declare function analyzeProject(input: AnalyzeProjectInput): AnalysisResult;
569
710
  declare function analyzeChange(input: AnalyzeChangeInput): AnalysisResult;
570
711
  declare function explainViolation(violation: AnalysisViolation): string;
571
712
  declare function detectArchitectureCycles(graph: ReadonlyMap<string, ReadonlySet<string>>): ArchitectureEngineViolation[];
572
713
  /** Canonical graph and layer-policy evaluator shared by library, CLI, and MCP adapters. */
573
714
  declare function evaluateArchitectureGraph(input: EvaluateArchitectureGraphInput): ArchitectureEngineResult;
715
+ /**
716
+ * Evaluate one create/update/delete set as a single in-memory candidate.
717
+ * The function never writes and returns hashes that bind a later host commit to
718
+ * the exact base, policy, compiler options, and candidate contents it checked.
719
+ */
720
+ declare function preflightChange(input: AnalyzeChangeInput): ChangePreflightResult;
574
721
  /** Canonical config diagnostics over repo-relative file paths. */
575
722
  declare function collectAnalysisConfigWarnings(input: CollectAnalysisConfigWarningsInput): ArchitectureEngineViolation[];
576
723
 
577
- export { type AICodeGate, type AICodeGateContext, type AICodeGateOptions, type AICodeGateResult, type AICodeGateViolation, type AIGateExtension, ANALYSIS_IR_SCHEMA_VERSION, ARK_ANALYSIS_RESULT_SCHEMA, ARK_ANALYSIS_RESULT_SCHEMA_VERSION, type AdapterDiagnostic, type AdapterResult, type AdapterSeverity, type AdapterViolationInput, type AnalysisCapabilityUse, type AnalysisCompilerOptions, type AnalysisContract, type AnalysisEvidence, type AnalysisFile, type AnalysisFileChange, type AnalysisFileInput, type AnalysisImportEdge, type AnalysisIr, type AnalysisResult, type AnalysisViolation, type AnalyzeChangeInput, type AnalyzeProjectInput, type ArchitectureEngineEdge, type ArchitectureEngineResult, type ArchitectureEngineViolation, type ArchitectureLayer, type ArchitectureLayerConfig, type ArchitectureProfile, type ArchitectureRule, type ArkCheckConfig, ArkConfig, ArkConfigLoadResult, type CollectAnalysisConfigWarningsInput, type CreateArchitectureProfileFromArkConfigOptions, type CreateArchitectureProfileOptions, type CreateElevenLayerArkConfigOptions, type EvaluateArchitectureGraphInput, type ForbiddenCapabilityUse, type SemanticDependency, type SemanticDependencyKind, analyzeChange, analyzeProject, collectAnalysisConfigWarnings, collectForbiddenCapabilityUses, createAICodeGate, createAdapterResult, createArchitectureProfile, createArchitectureProfileFromArkConfig, createElevenLayerArkConfig, detectArchitectureCycles, deterministicHash, elevenLayerProfile, evaluateArchitectureGraph, explainViolation, extractSemanticDependencies, loadContract, stableSerialize, toAdapterDiagnostic, version };
724
+ export { type AICodeGate, type AICodeGateContext, type AICodeGateOptions, type AICodeGateResult, type AICodeGateViolation, type AIGateExtension, ANALYSIS_IR_SCHEMA_VERSION, ARK_ANALYSIS_RESULT_SCHEMA, ARK_ANALYSIS_RESULT_SCHEMA_VERSION, type AdapterDiagnostic, type AdapterResult, type AdapterSeverity, type AdapterViolationInput, type AnalysisCapabilityUse, type AnalysisCompilerOptions, type AnalysisContract, type AnalysisEvidence, type AnalysisFile, type AnalysisFileChange, type AnalysisFileInput, type AnalysisImportEdge, type AnalysisIr, type AnalysisResult, type AnalysisViolation, type AnalyzeArchitectureConvergenceInput, type AnalyzeChangeInput, type AnalyzePolicyDeltaInput, type AnalyzeProjectInput, type ArchitectureActualChange, type ArchitectureChangeMap, type ArchitectureChangeMapContract, type ArchitectureChangeMapDependency, type ArchitectureChangeMapFile, type ArchitectureChangeOperation, type ArchitectureConvergenceClassification, type ArchitectureConvergenceFinding, type ArchitectureConvergenceResult, type ArchitectureDependency, type ArchitectureEngineEdge, type ArchitectureEngineResult, type ArchitectureEngineViolation, type ArchitectureLayer, type ArchitectureLayerConfig, type ArchitectureProfile, type ArchitectureRule, type ArkCheckConfig, ArkConfig, ArkConfigLoadResult, type ChangePreflightResult, type CollectAnalysisConfigWarningsInput, type CreateArchitectureProfileFromArkConfigOptions, type CreateArchitectureProfileOptions, type CreateElevenLayerArkConfigOptions, type EvaluateArchitectureGraphInput, type ForbiddenCapabilityUse, POLICY_DELTA_SCHEMA_VERSION, type PolicyDelta, type PolicyDeltaAcknowledgement, type PolicyDeltaAnalysis, type PolicyDeltaClassification, type PolicyDeltaFinding, type PreparedChangeFile, type SemanticDependency, type SemanticDependencyKind, analyzeArchitectureConvergence, analyzeChange, analyzePolicyDelta, analyzeProject, classifyArkPolicyDelta, collectAnalysisConfigWarnings, collectForbiddenCapabilityUses, createAICodeGate, createAdapterResult, createArchitectureProfile, createArchitectureProfileFromArkConfig, createElevenLayerArkConfig, detectArchitectureCycles, deterministicHash, elevenLayerProfile, evaluateArchitectureGraph, explainViolation, extractSemanticDependencies, loadContract, policyDeltaAcknowledgementMatches, preflightChange, stableSerialize, toAdapterDiagnostic, version };
package/dist/index.d.ts CHANGED
@@ -2,10 +2,10 @@ import { a as ArkConfigRule, b as ArkConfigLayer, A as ArkConfig, c as ArkConfig
2
2
  export { d as ARK_CONFIG_SCHEMA, e as ARK_CONFIG_SCHEMA_VERSION, l as loadArkConfigContract, p as parseArkConfigJson } from './configContract-BxSIwVRo.js';
3
3
 
4
4
  /** ArkGate library version — single source of truth. */
5
- declare const version = "3.0.4";
5
+ declare const version = "3.1.0";
6
6
 
7
7
  /** Versioned public result contract shared by every ArkGate enforcement adapter. */
8
- declare const ARK_ANALYSIS_RESULT_SCHEMA_VERSION: "1.0";
8
+ declare const ARK_ANALYSIS_RESULT_SCHEMA_VERSION: "1.1";
9
9
  type AdapterSeverity = 'error' | 'warning';
10
10
  type AdapterViolationInput = {
11
11
  ruleId?: unknown;
@@ -18,7 +18,11 @@ type AdapterViolationInput = {
18
18
  fromLayer?: unknown;
19
19
  toLayer?: unknown;
20
20
  typeOnly?: unknown;
21
+ targetTypeOnlyExports?: unknown;
22
+ namedBindingsTypeOnly?: unknown;
23
+ peerIsolation?: unknown;
21
24
  severity?: unknown;
25
+ nextAction?: unknown;
22
26
  };
23
27
  type AdapterDiagnostic = {
24
28
  ruleId: string;
@@ -35,9 +39,11 @@ type AdapterDiagnostic = {
35
39
  toLayer?: string;
36
40
  typeOnly?: boolean;
37
41
  };
42
+ /** Added in schema 1.1; optional in TypeScript so 1.0 consumer-owned values remain valid. */
43
+ nextAction?: string;
38
44
  };
39
45
  type AdapterResult = {
40
- schemaVersion: typeof ARK_ANALYSIS_RESULT_SCHEMA_VERSION;
46
+ schemaVersion: '1.0' | typeof ARK_ANALYSIS_RESULT_SCHEMA_VERSION;
41
47
  valid: boolean;
42
48
  diagnostics: AdapterDiagnostic[];
43
49
  };
@@ -56,7 +62,7 @@ declare const ARK_ANALYSIS_RESULT_SCHEMA: {
56
62
  readonly required: readonly ["schemaVersion", "valid", "diagnostics"];
57
63
  readonly properties: {
58
64
  readonly schemaVersion: {
59
- readonly const: "1.0";
65
+ readonly const: "1.1";
60
66
  };
61
67
  readonly valid: {
62
68
  readonly type: "boolean";
@@ -116,6 +122,10 @@ declare const ARK_ANALYSIS_RESULT_SCHEMA: {
116
122
  };
117
123
  };
118
124
  };
125
+ readonly nextAction: {
126
+ readonly type: "string";
127
+ readonly minLength: 1;
128
+ };
119
129
  };
120
130
  };
121
131
  };
@@ -481,6 +491,96 @@ declare function deterministicHash(value: string): string;
481
491
  /** Serialize JSON-like values with sorted object keys for reproducible hashes. */
482
492
  declare function stableSerialize(value: unknown): string;
483
493
 
494
+ declare const POLICY_DELTA_SCHEMA_VERSION: "1.0";
495
+ type PolicyDeltaClassification = 'strengthening' | 'neutral' | 'judgment-required' | 'weakening';
496
+ type PolicyDeltaFinding = {
497
+ id: string;
498
+ path: string;
499
+ classification: Exclude<PolicyDeltaClassification, 'neutral'>;
500
+ message: string;
501
+ nextAction?: string;
502
+ before?: unknown;
503
+ after?: unknown;
504
+ };
505
+ type PolicyDelta = {
506
+ schemaVersion: typeof POLICY_DELTA_SCHEMA_VERSION;
507
+ classification: PolicyDeltaClassification;
508
+ findings: PolicyDeltaFinding[];
509
+ };
510
+ type PolicyDeltaAcknowledgement = {
511
+ schemaVersion: typeof POLICY_DELTA_SCHEMA_VERSION;
512
+ basePolicyHash: string;
513
+ candidatePolicyHash: string;
514
+ findingIds: readonly string[];
515
+ reason: string;
516
+ };
517
+ declare function classifyArkPolicyDelta(base: ArkConfig, candidate: ArkConfig): PolicyDelta;
518
+ declare function policyDeltaAcknowledgementMatches(acknowledgement: PolicyDeltaAcknowledgement | undefined, expected: {
519
+ basePolicyHash: string;
520
+ candidatePolicyHash: string;
521
+ findingIds: readonly string[];
522
+ }): boolean;
523
+
524
+ declare const ARK_CHANGE_MAP_SCHEMA_VERSION: "1.0";
525
+ type ArchitectureChangeOperation = 'create' | 'update' | 'delete';
526
+ type ArchitectureChangeMapFile = {
527
+ path: string;
528
+ operation: ArchitectureChangeOperation;
529
+ layer: string;
530
+ };
531
+ type ArchitectureChangeMapDependency = {
532
+ from: string;
533
+ to: string;
534
+ };
535
+ type ArchitectureChangeMap = {
536
+ $schema: string;
537
+ schemaVersion: typeof ARK_CHANGE_MAP_SCHEMA_VERSION;
538
+ files: ArchitectureChangeMapFile[];
539
+ dependencies: ArchitectureChangeMapDependency[];
540
+ };
541
+ type ArchitectureChangeMapContract = {
542
+ map: ArchitectureChangeMap;
543
+ hash: string;
544
+ };
545
+
546
+ type ArchitectureDependency = {
547
+ from: string;
548
+ to: string;
549
+ };
550
+ type ArchitectureActualChange = {
551
+ path: string;
552
+ operation: ArchitectureChangeOperation;
553
+ };
554
+ type ArchitectureConvergenceClassification = 'satisfied' | 'missing' | 'contradictory' | 'unplanned';
555
+ type ArchitectureConvergenceFinding = {
556
+ id: string;
557
+ classification: ArchitectureConvergenceClassification;
558
+ subject: 'file' | 'dependency';
559
+ message: string;
560
+ nextAction?: string;
561
+ path?: string;
562
+ from?: string;
563
+ to?: string;
564
+ expectedOperation?: ArchitectureChangeOperation;
565
+ actualOperation?: ArchitectureChangeOperation | 'added' | 'removed';
566
+ };
567
+ type ArchitectureConvergenceResult = {
568
+ schemaVersion: '1.0';
569
+ readOnly: true;
570
+ changeMapHash: string;
571
+ structurallyConverged: boolean;
572
+ behavioralCompletion: 'not-evaluated';
573
+ summary: Record<ArchitectureConvergenceClassification, number>;
574
+ findings: ArchitectureConvergenceFinding[];
575
+ };
576
+ type AnalyzeArchitectureConvergenceInput = {
577
+ changeMap: ArchitectureChangeMapContract;
578
+ changes: readonly ArchitectureActualChange[];
579
+ baseDependencies: readonly ArchitectureDependency[];
580
+ candidateDependencies: readonly ArchitectureDependency[];
581
+ };
582
+ declare function analyzeArchitectureConvergence(input: AnalyzeArchitectureConvergenceInput): ArchitectureConvergenceResult;
583
+
484
584
  type SemanticDependencyKind = 'import' | 'export' | 'dynamic-import' | 'require';
485
585
  type SemanticDependency = {
486
586
  specifier?: string;
@@ -510,10 +610,29 @@ type AnalyzeProjectInput = {
510
610
  };
511
611
  type AnalyzeChangeInput = AnalyzeProjectInput & {
512
612
  changes: readonly AnalysisFileChange[];
613
+ changeMap?: ArchitectureChangeMapContract;
513
614
  };
514
615
  type AnalysisResult = {
515
616
  ir: AnalysisIr;
516
617
  };
618
+ type AnalyzePolicyDeltaInput = {
619
+ baseConfig: unknown;
620
+ candidateConfig: unknown;
621
+ acknowledgement?: PolicyDeltaAcknowledgement;
622
+ baseSource?: string;
623
+ candidateSource?: string;
624
+ };
625
+ type PolicyDeltaAnalysis = {
626
+ schemaVersion: '1.0';
627
+ basePolicyHash: string;
628
+ candidatePolicyHash: string;
629
+ classification: PolicyDeltaClassification;
630
+ findings: PolicyDeltaFinding[];
631
+ blockingFindingIds: string[];
632
+ requiresAcknowledgement: boolean;
633
+ acknowledged: boolean;
634
+ valid: boolean;
635
+ };
517
636
  type ArchitectureEngineViolation = {
518
637
  ruleId: string;
519
638
  message: string;
@@ -522,6 +641,7 @@ type ArchitectureEngineViolation = {
522
641
  target?: string;
523
642
  fromLayer?: string;
524
643
  toLayer?: string;
644
+ nextAction?: string;
525
645
  [key: string]: unknown;
526
646
  };
527
647
  type ArchitectureEngineEdge = {
@@ -551,6 +671,26 @@ type ArchitectureEngineResult = {
551
671
  warnings: ArchitectureEngineViolation[];
552
672
  safety?: unknown;
553
673
  };
674
+ type PreparedChangeFile = {
675
+ path: string;
676
+ operation: 'create' | 'update' | 'delete';
677
+ beforeContentHash?: string;
678
+ candidateContentHash?: string;
679
+ };
680
+ type ChangePreflightResult = {
681
+ schemaVersion: '1.0';
682
+ valid: boolean;
683
+ readOnly: true;
684
+ policyHash: string;
685
+ compilerOptionsHash: string;
686
+ baseTreeHash: string;
687
+ candidateTreeHash: string;
688
+ changeMapHash?: string;
689
+ convergence?: ArchitectureConvergenceResult;
690
+ changes: PreparedChangeFile[];
691
+ violations: ArchitectureEngineViolation[];
692
+ warnings: ArchitectureEngineViolation[];
693
+ };
554
694
  type CollectAnalysisConfigWarningsInput = {
555
695
  config: ArkConfig;
556
696
  rules: ArkConfig['rules'];
@@ -565,13 +705,20 @@ type CollectAnalysisConfigWarningsInput = {
565
705
  };
566
706
  };
567
707
  declare function loadContract(input: unknown, source?: string): AnalysisContract;
708
+ declare function analyzePolicyDelta(input: AnalyzePolicyDeltaInput): PolicyDeltaAnalysis;
568
709
  declare function analyzeProject(input: AnalyzeProjectInput): AnalysisResult;
569
710
  declare function analyzeChange(input: AnalyzeChangeInput): AnalysisResult;
570
711
  declare function explainViolation(violation: AnalysisViolation): string;
571
712
  declare function detectArchitectureCycles(graph: ReadonlyMap<string, ReadonlySet<string>>): ArchitectureEngineViolation[];
572
713
  /** Canonical graph and layer-policy evaluator shared by library, CLI, and MCP adapters. */
573
714
  declare function evaluateArchitectureGraph(input: EvaluateArchitectureGraphInput): ArchitectureEngineResult;
715
+ /**
716
+ * Evaluate one create/update/delete set as a single in-memory candidate.
717
+ * The function never writes and returns hashes that bind a later host commit to
718
+ * the exact base, policy, compiler options, and candidate contents it checked.
719
+ */
720
+ declare function preflightChange(input: AnalyzeChangeInput): ChangePreflightResult;
574
721
  /** Canonical config diagnostics over repo-relative file paths. */
575
722
  declare function collectAnalysisConfigWarnings(input: CollectAnalysisConfigWarningsInput): ArchitectureEngineViolation[];
576
723
 
577
- export { type AICodeGate, type AICodeGateContext, type AICodeGateOptions, type AICodeGateResult, type AICodeGateViolation, type AIGateExtension, ANALYSIS_IR_SCHEMA_VERSION, ARK_ANALYSIS_RESULT_SCHEMA, ARK_ANALYSIS_RESULT_SCHEMA_VERSION, type AdapterDiagnostic, type AdapterResult, type AdapterSeverity, type AdapterViolationInput, type AnalysisCapabilityUse, type AnalysisCompilerOptions, type AnalysisContract, type AnalysisEvidence, type AnalysisFile, type AnalysisFileChange, type AnalysisFileInput, type AnalysisImportEdge, type AnalysisIr, type AnalysisResult, type AnalysisViolation, type AnalyzeChangeInput, type AnalyzeProjectInput, type ArchitectureEngineEdge, type ArchitectureEngineResult, type ArchitectureEngineViolation, type ArchitectureLayer, type ArchitectureLayerConfig, type ArchitectureProfile, type ArchitectureRule, type ArkCheckConfig, ArkConfig, ArkConfigLoadResult, type CollectAnalysisConfigWarningsInput, type CreateArchitectureProfileFromArkConfigOptions, type CreateArchitectureProfileOptions, type CreateElevenLayerArkConfigOptions, type EvaluateArchitectureGraphInput, type ForbiddenCapabilityUse, type SemanticDependency, type SemanticDependencyKind, analyzeChange, analyzeProject, collectAnalysisConfigWarnings, collectForbiddenCapabilityUses, createAICodeGate, createAdapterResult, createArchitectureProfile, createArchitectureProfileFromArkConfig, createElevenLayerArkConfig, detectArchitectureCycles, deterministicHash, elevenLayerProfile, evaluateArchitectureGraph, explainViolation, extractSemanticDependencies, loadContract, stableSerialize, toAdapterDiagnostic, version };
724
+ export { type AICodeGate, type AICodeGateContext, type AICodeGateOptions, type AICodeGateResult, type AICodeGateViolation, type AIGateExtension, ANALYSIS_IR_SCHEMA_VERSION, ARK_ANALYSIS_RESULT_SCHEMA, ARK_ANALYSIS_RESULT_SCHEMA_VERSION, type AdapterDiagnostic, type AdapterResult, type AdapterSeverity, type AdapterViolationInput, type AnalysisCapabilityUse, type AnalysisCompilerOptions, type AnalysisContract, type AnalysisEvidence, type AnalysisFile, type AnalysisFileChange, type AnalysisFileInput, type AnalysisImportEdge, type AnalysisIr, type AnalysisResult, type AnalysisViolation, type AnalyzeArchitectureConvergenceInput, type AnalyzeChangeInput, type AnalyzePolicyDeltaInput, type AnalyzeProjectInput, type ArchitectureActualChange, type ArchitectureChangeMap, type ArchitectureChangeMapContract, type ArchitectureChangeMapDependency, type ArchitectureChangeMapFile, type ArchitectureChangeOperation, type ArchitectureConvergenceClassification, type ArchitectureConvergenceFinding, type ArchitectureConvergenceResult, type ArchitectureDependency, type ArchitectureEngineEdge, type ArchitectureEngineResult, type ArchitectureEngineViolation, type ArchitectureLayer, type ArchitectureLayerConfig, type ArchitectureProfile, type ArchitectureRule, type ArkCheckConfig, ArkConfig, ArkConfigLoadResult, type ChangePreflightResult, type CollectAnalysisConfigWarningsInput, type CreateArchitectureProfileFromArkConfigOptions, type CreateArchitectureProfileOptions, type CreateElevenLayerArkConfigOptions, type EvaluateArchitectureGraphInput, type ForbiddenCapabilityUse, POLICY_DELTA_SCHEMA_VERSION, type PolicyDelta, type PolicyDeltaAcknowledgement, type PolicyDeltaAnalysis, type PolicyDeltaClassification, type PolicyDeltaFinding, type PreparedChangeFile, type SemanticDependency, type SemanticDependencyKind, analyzeArchitectureConvergence, analyzeChange, analyzePolicyDelta, analyzeProject, classifyArkPolicyDelta, collectAnalysisConfigWarnings, collectForbiddenCapabilityUses, createAICodeGate, createAdapterResult, createArchitectureProfile, createArchitectureProfileFromArkConfig, createElevenLayerArkConfig, detectArchitectureCycles, deterministicHash, elevenLayerProfile, evaluateArchitectureGraph, explainViolation, extractSemanticDependencies, loadContract, policyDeltaAcknowledgementMatches, preflightChange, stableSerialize, toAdapterDiagnostic, version };