File Coverage

blib/lib/Sim/AgentSoar/Node.pm
Criterion Covered Total %
statement 6 15 40.0
branch n/a
condition n/a
subroutine 2 9 22.2
pod 6 7 85.7
total 14 31 45.1


line stmt bran cond sub pod time code
1             package Sim::AgentSoar::Node;
2              
3 1     1   6 use strict;
  1         2  
  1         35  
4 1     1   4 use warnings;
  1         2  
  1         331  
5              
6             our $VERSION = '0.06';
7              
8             sub new
9             {
10 0     0 0   my ($class, %args) = @_;
11              
12             my $self =
13             {
14             id => $args{id},
15             parent => $args{parent},
16             value => $args{value},
17             metric => $args{metric},
18             depth => $args{depth},
19             operator => $args{operator},
20 0           };
21              
22 0           return bless $self, $class;
23             }
24              
25 0     0 1   sub id { $_[0]->{id} }
26 0     0 1   sub parent { $_[0]->{parent} }
27 0     0 1   sub value { $_[0]->{value} }
28 0     0 1   sub metric { $_[0]->{metric} }
29 0     0 1   sub depth { $_[0]->{depth} }
30 0     0 1   sub operator { $_[0]->{operator} }
31              
32             1;
33              
34              
35             =pod
36              
37             =head1 NAME
38              
39             Sim::AgentSoar::Node - Formal search state representation
40              
41             =head1 DESCRIPTION
42              
43             Sim::AgentSoar::Node represents a single state in the explicit search tree
44             managed by C.
45              
46             Each node is an immutable snapshot of the search state at a given depth.
47             It encodes both structural position in the tree and evaluation metadata.
48              
49             =head2 Conceptual Role
50              
51             A Node formalizes the separation between:
52              
53             =over 4
54              
55             =item * Structural recursion (tree topology)
56              
57             =item * Deterministic evaluation (metric)
58              
59             =item * Heuristic action (operator_applied)
60              
61             =back
62              
63             Nodes do not contain behavioral logic. They are purely representational.
64              
65             This design enforces:
66              
67             =over 4
68              
69             =item * Deterministic state tracking
70              
71             =item * Explicit parent-child relationships
72              
73             =item * Transparent reconstruction of solution paths
74              
75             =item * Isolation of heuristic decisions from structural control
76              
77             =back
78              
79             =head2 Fields
80              
81             Each Node instance contains:
82              
83             =over 4
84              
85             =item * id
86              
87             Unique numeric identifier.
88              
89             =item * parent
90              
91             Identifier of the parent node (undef for root).
92              
93             =item * value
94              
95             Domain state value (integer in calibration domain).
96              
97             =item * metric
98              
99             Evaluation score relative to target.
100              
101             =item * depth
102              
103             Depth in search tree.
104              
105             =item * operator
106              
107             Operator applied to reach this node.
108              
109             =back
110              
111             =head2 Research Significance
112              
113             The Node abstraction embodies the explicit search paradigm:
114              
115             AgentSoar is structural, not narrative.
116              
117             Heuristics may influence expansion,
118             but the search state remains fully inspectable and reconstructible.
119              
120             This makes the architecture suitable for:
121              
122             =over 4
123              
124             =item * Empirical evaluation
125              
126             =item * Deterministic replay
127              
128             =item * Controlled architectural evolution
129              
130             =item * Instrumented experimentation
131              
132             =back
133              
134             =head1 AUTHOR
135              
136             Gian Luca Brunetti (2026), gianluca.brunetti@gmail.com
137              
138             =cut