cadenya 0.13.0 → 0.14.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 (49) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +8 -0
  3. data/README.md +1 -1
  4. data/lib/cadenya/client.rb +2 -2
  5. data/lib/cadenya/models/agents/agent_variation_info.rb +2 -1
  6. data/lib/cadenya/models/agents/variation_add_memory_layer_params.rb +3 -2
  7. data/lib/cadenya/models/agents/variation_memory_layer_assignment.rb +7 -6
  8. data/lib/cadenya/models/bulk_workspace_resources/bulk_workspace_apply_result_data_memory_entry_outcome.rb +2 -2
  9. data/lib/cadenya/models/bulk_workspace_resources/bulk_workspace_apply_result_data_memory_layer_outcome.rb +4 -4
  10. data/lib/cadenya/models/bulk_workspace_resources/bulk_workspace_apply_result_data_variation_memory_layer_outcome.rb +2 -2
  11. data/lib/cadenya/models/memory_layer.rb +4 -4
  12. data/lib/cadenya/models/memory_layer_spec.rb +1 -1
  13. data/lib/cadenya/models/memory_layers/memory_entry.rb +2 -2
  14. data/lib/cadenya/models/memory_read.rb +2 -2
  15. data/lib/cadenya/models/memory_reference.rb +6 -5
  16. data/lib/cadenya/models/objective.rb +14 -16
  17. data/lib/cadenya/models/objective_create_params.rb +14 -16
  18. data/lib/cadenya/models/objective_event_data.rb +2 -2
  19. data/lib/cadenya/models/objective_info.rb +11 -9
  20. data/lib/cadenya/resources/agents/variations.rb +2 -2
  21. data/lib/cadenya/resources/memory_layers/entries.rb +2 -2
  22. data/lib/cadenya/resources/memory_layers.rb +4 -4
  23. data/lib/cadenya/resources/objectives.rb +2 -2
  24. data/lib/cadenya/version.rb +1 -1
  25. data/rbi/cadenya/client.rbi +2 -2
  26. data/rbi/cadenya/models/agents/agent_variation_info.rbi +4 -2
  27. data/rbi/cadenya/models/agents/variation_add_memory_layer_params.rbi +4 -2
  28. data/rbi/cadenya/models/agents/variation_memory_layer_assignment.rbi +10 -8
  29. data/rbi/cadenya/models/bulk_workspace_resources/bulk_workspace_apply_result_data_memory_entry_outcome.rbi +4 -4
  30. data/rbi/cadenya/models/bulk_workspace_resources/bulk_workspace_apply_result_data_memory_layer_outcome.rbi +8 -8
  31. data/rbi/cadenya/models/bulk_workspace_resources/bulk_workspace_apply_result_data_variation_memory_layer_outcome.rbi +4 -4
  32. data/rbi/cadenya/models/memory_layer.rbi +4 -4
  33. data/rbi/cadenya/models/memory_layer_spec.rbi +2 -2
  34. data/rbi/cadenya/models/memory_layers/memory_entry.rbi +2 -2
  35. data/rbi/cadenya/models/memory_read.rbi +2 -2
  36. data/rbi/cadenya/models/memory_reference.rbi +9 -7
  37. data/rbi/cadenya/models/objective.rbi +24 -28
  38. data/rbi/cadenya/models/objective_create_params.rbi +24 -28
  39. data/rbi/cadenya/models/objective_event_data.rbi +4 -4
  40. data/rbi/cadenya/models/objective_info.rbi +16 -12
  41. data/rbi/cadenya/resources/agents/variations.rbi +3 -3
  42. data/rbi/cadenya/resources/memory_layers/entries.rbi +2 -2
  43. data/rbi/cadenya/resources/memory_layers.rbi +4 -4
  44. data/rbi/cadenya/resources/objectives.rbi +11 -13
  45. data/sig/cadenya/models/objective.rbs +5 -5
  46. data/sig/cadenya/models/objective_create_params.rbs +5 -5
  47. data/sig/cadenya/models/objective_info.rbs +4 -4
  48. data/sig/cadenya/resources/objectives.rbs +1 -1
  49. metadata +1 -1
@@ -59,11 +59,11 @@ module Cadenya
59
59
  attr_writer :external_id
60
60
 
61
61
  # MemoryLayer is a named container of memory entries that can be composed into an
62
- # objective's memory stack. Layers are workspace-scoped resources. The layer type
63
- # controls how its entries participate in the agent loop — see MemoryLayerType for
64
- # details.
62
+ # objective's memory cascade. Layers are workspace-scoped resources. The layer
63
+ # type controls how its entries participate in the agent loop — see
64
+ # MemoryLayerType for details.
65
65
  #
66
- # See "Memory stack composition" above for how layers compose at lookup time.
66
+ # See "Memory cascade composition" above for how layers compose at lookup time.
67
67
  sig { returns(T.nilable(Cadenya::MemoryLayer)) }
68
68
  attr_reader :resource
69
69
 
@@ -91,11 +91,11 @@ module Cadenya
91
91
  error: nil,
92
92
  external_id: nil,
93
93
  # MemoryLayer is a named container of memory entries that can be composed into an
94
- # objective's memory stack. Layers are workspace-scoped resources. The layer type
95
- # controls how its entries participate in the agent loop — see MemoryLayerType for
96
- # details.
94
+ # objective's memory cascade. Layers are workspace-scoped resources. The layer
95
+ # type controls how its entries participate in the agent loop — see
96
+ # MemoryLayerType for details.
97
97
  #
98
- # See "Memory stack composition" above for how layers compose at lookup time.
98
+ # See "Memory cascade composition" above for how layers compose at lookup time.
99
99
  resource: nil
100
100
  )
101
101
  end
@@ -53,8 +53,8 @@ module Cadenya
53
53
  attr_writer :error
54
54
 
55
55
  # VariationMemoryLayerAssignment attaches a single MemoryLayer to a variation at a
56
- # given position in the variation's baseline memory stack. A variation has at most
57
- # one assignment per memory_layer_id.
56
+ # given position in the variation's baseline memory cascade. A variation has at
57
+ # most one assignment per memory_layer_id.
58
58
  #
59
59
  # Variations only support whole-layer attachments — entry pinning is an
60
60
  # objective-level capability.
@@ -89,8 +89,8 @@ module Cadenya
89
89
  # [API Design Guide](https://cloud.google.com/apis/design/errors).
90
90
  error: nil,
91
91
  # VariationMemoryLayerAssignment attaches a single MemoryLayer to a variation at a
92
- # given position in the variation's baseline memory stack. A variation has at most
93
- # one assignment per memory_layer_id.
92
+ # given position in the variation's baseline memory cascade. A variation has at
93
+ # most one assignment per memory_layer_id.
94
94
  #
95
95
  # Variations only support whole-layer attachments — entry pinning is an
96
96
  # objective-level capability.
@@ -26,11 +26,11 @@ module Cadenya
26
26
  attr_writer :info
27
27
 
28
28
  # MemoryLayer is a named container of memory entries that can be composed into an
29
- # objective's memory stack. Layers are workspace-scoped resources. The layer type
30
- # controls how its entries participate in the agent loop — see MemoryLayerType for
31
- # details.
29
+ # objective's memory cascade. Layers are workspace-scoped resources. The layer
30
+ # type controls how its entries participate in the agent loop — see
31
+ # MemoryLayerType for details.
32
32
  #
33
- # See "Memory stack composition" above for how layers compose at lookup time.
33
+ # See "Memory cascade composition" above for how layers compose at lookup time.
34
34
  sig do
35
35
  params(
36
36
  metadata: Cadenya::ResourceMetadata::OrHash,
@@ -45,7 +45,7 @@ module Cadenya
45
45
 
46
46
  # Server-set. True for layers managed by the system (e.g., episodic layers created
47
47
  # automatically when an objective uses an episodic_key). System-managed layers
48
- # cannot be assigned to objective stacks via the API and cannot be mutated by
48
+ # cannot be assigned to objective cascades via the API and cannot be mutated by
49
49
  # clients — their lifecycle is controlled entirely by the runtime.
50
50
  sig { returns(T.nilable(T::Boolean)) }
51
51
  attr_reader :system_managed
@@ -79,7 +79,7 @@ module Cadenya
79
79
  expires_at: nil,
80
80
  # Server-set. True for layers managed by the system (e.g., episodic layers created
81
81
  # automatically when an objective uses an episodic_key). System-managed layers
82
- # cannot be assigned to objective stacks via the API and cannot be mutated by
82
+ # cannot be assigned to objective cascades via the API and cannot be mutated by
83
83
  # clients — their lifecycle is controlled entirely by the runtime.
84
84
  system_managed: nil
85
85
  )
@@ -41,8 +41,8 @@ module Cadenya
41
41
  # MemoryEntry is a single keyed value within a MemoryLayer. Entries are addressed
42
42
  # by their key, which follows the S3 object key safe-character convention (see
43
43
  # MemoryEntrySpec.key for the full rule). Keys are unique within a single layer;
44
- # the same key may appear in multiple layers, in which case the LIFO stack-walk
45
- # determines which one wins for a given objective.
44
+ # the same key may appear in multiple layers, in which case the cascade walk
45
+ # determines which one wins for a given objective (most specific layer first).
46
46
  #
47
47
  # MemoryEntry is the summary shape, returned by ListMemoryEntries. It does not
48
48
  # carry the entry body — callers that need the body must fetch the entry
@@ -32,8 +32,8 @@ module Cadenya
32
32
  attr_writer :message
33
33
 
34
34
  # MemoryRead is emitted each time the agent resolves a key against the memory
35
- # stack and loads an entry. Lookups that miss (key not found in any layer) do not
36
- # emit this event.
35
+ # cascade and loads an entry. Lookups that miss (key not found in any layer) do
36
+ # not emit this event.
37
37
  sig do
38
38
  params(
39
39
  memory_entry_id: String,
@@ -8,9 +8,10 @@ module Cadenya
8
8
  T.any(Cadenya::MemoryReference, Cadenya::Internal::AnyHash)
9
9
  end
10
10
 
11
- # When set, pushes only this entry from memory_layer_id onto the stack behaves
12
- # as a single-entry layer (only this key resolves at this position). The entry
13
- # must belong to memory_layer_id; mismatches are rejected with InvalidArgument.
11
+ # When set, inserts only this entry from memory_layer_id into the cascade
12
+ # behaves as a single-entry layer (only this key resolves at this position). The
13
+ # entry must belong to memory_layer_id; mismatches are rejected with
14
+ # InvalidArgument.
14
15
  sig { returns(T.nilable(String)) }
15
16
  attr_reader :memory_entry_id
16
17
 
@@ -24,7 +25,7 @@ module Cadenya
24
25
  attr_writer :memory_layer_id
25
26
 
26
27
  # MemoryReference identifies a memory layer or a specific entry within one, for
27
- # composition into a memory stack. Used on objectives (where entry pinning is
28
+ # composition into a memory cascade. Used on objectives (where entry pinning is
28
29
  # permitted).
29
30
  #
30
31
  # memory*layer_id accepts both the canonical form (memlyr*…) and the external-id
@@ -35,9 +36,10 @@ module Cadenya
35
36
  )
36
37
  end
37
38
  def self.new(
38
- # When set, pushes only this entry from memory_layer_id onto the stack behaves
39
- # as a single-entry layer (only this key resolves at this position). The entry
40
- # must belong to memory_layer_id; mismatches are rejected with InvalidArgument.
39
+ # When set, inserts only this entry from memory_layer_id into the cascade
40
+ # behaves as a single-entry layer (only this key resolves at this position). The
41
+ # entry must belong to memory_layer_id; mismatches are rejected with
42
+ # InvalidArgument.
41
43
  memory_entry_id: nil,
42
44
  memory_layer_id: nil
43
45
  )
@@ -28,28 +28,26 @@ module Cadenya
28
28
  end
29
29
  attr_writer :episodic_memory
30
30
 
31
- # Memory layers/entries to push onto this objective's memory stack on top of the
32
- # baseline stack inherited from the selected variation.
31
+ # Memory layers/entries layered over the baseline cascade inherited from the
32
+ # selected variation — element-level rules over inherited styles, in CSS terms.
33
33
  #
34
- # Array order is push order: the first element sits lower in the objective's
35
- # contribution to the stack; the LAST element ends up on top of the effective
36
- # stack. Entries pinned via memory_entry_id behave as single-entry layers at their
37
- # position.
34
+ # Array order is resolution order: EARLIER elements are more specific and are
35
+ # consulted first. Entries pinned via memory_entry_id behave as single-entry
36
+ # layers at their position.
38
37
  #
39
38
  # System-managed layers (e.g., episodic) cannot be referenced here; they attach
40
- # themselves automatically based on episodic_key.
39
+ # themselves automatically based on the episodic key.
41
40
  #
42
- # Stack size cap: the TOTAL effective stack (variation's memory layers
43
- #
44
- # - this field) must not exceed 10 entries. A request that would produce an
45
- # effective stack larger than 10 is rejected with InvalidArgument.
41
+ # Size cap: the TOTAL effective cascade (this field + the variation's memory layer
42
+ # assignments) must not exceed 10 entries. A request that would produce a larger
43
+ # cascade is rejected with InvalidArgument.
46
44
  sig { returns(T.nilable(T::Array[Cadenya::MemoryReference])) }
47
- attr_reader :memory_stack
45
+ attr_reader :memory_cascade
48
46
 
49
47
  sig do
50
- params(memory_stack: T::Array[Cadenya::MemoryReference::OrHash]).void
48
+ params(memory_cascade: T::Array[Cadenya::MemoryReference::OrHash]).void
51
49
  end
52
- attr_writer :memory_stack
50
+ attr_writer :memory_cascade
53
51
 
54
52
  # Secrets that can be used in the headers for tool calls using the secret
55
53
  # interpolation format.
@@ -136,7 +134,7 @@ module Cadenya
136
134
  data: T::Hash[Symbol, T.anything],
137
135
  episodic_memory: Cadenya::Objective::EpisodicMemory::OrHash,
138
136
  info: Cadenya::ObjectiveInfo::OrHash,
139
- memory_stack: T::Array[Cadenya::MemoryReference::OrHash],
137
+ memory_cascade: T::Array[Cadenya::MemoryReference::OrHash],
140
138
  output: T::Hash[Symbol, T.anything],
141
139
  parent_objective_id: String,
142
140
  secrets: T::Array[Cadenya::ObjectiveSecret::OrHash],
@@ -165,22 +163,20 @@ module Cadenya
165
163
  # ObjectiveInfo provides read-only aggregated statistics about an objective's
166
164
  # execution
167
165
  info: nil,
168
- # Memory layers/entries to push onto this objective's memory stack on top of the
169
- # baseline stack inherited from the selected variation.
166
+ # Memory layers/entries layered over the baseline cascade inherited from the
167
+ # selected variation — element-level rules over inherited styles, in CSS terms.
170
168
  #
171
- # Array order is push order: the first element sits lower in the objective's
172
- # contribution to the stack; the LAST element ends up on top of the effective
173
- # stack. Entries pinned via memory_entry_id behave as single-entry layers at their
174
- # position.
169
+ # Array order is resolution order: EARLIER elements are more specific and are
170
+ # consulted first. Entries pinned via memory_entry_id behave as single-entry
171
+ # layers at their position.
175
172
  #
176
173
  # System-managed layers (e.g., episodic) cannot be referenced here; they attach
177
- # themselves automatically based on episodic_key.
178
- #
179
- # Stack size cap: the TOTAL effective stack (variation's memory layers
174
+ # themselves automatically based on the episodic key.
180
175
  #
181
- # - this field) must not exceed 10 entries. A request that would produce an
182
- # effective stack larger than 10 is rejected with InvalidArgument.
183
- memory_stack: nil,
176
+ # Size cap: the TOTAL effective cascade (this field + the variation's memory layer
177
+ # assignments) must not exceed 10 entries. A request that would produce a larger
178
+ # cascade is rejected with InvalidArgument.
179
+ memory_cascade: nil,
184
180
  # The output of the objective, populated when the objective completes. Will match
185
181
  # the schema of output_json_schema or output_json_inferred. This will only be set
186
182
  # if the state of the objective is set to STATE_FINALIZED
@@ -209,7 +205,7 @@ module Cadenya
209
205
  data: T::Hash[Symbol, T.anything],
210
206
  episodic_memory: Cadenya::Objective::EpisodicMemory,
211
207
  info: Cadenya::ObjectiveInfo,
212
- memory_stack: T::Array[Cadenya::MemoryReference],
208
+ memory_cascade: T::Array[Cadenya::MemoryReference],
213
209
  output: T::Hash[Symbol, T.anything],
214
210
  parent_objective_id: String,
215
211
  secrets: T::Array[Cadenya::ObjectiveSecret],
@@ -45,28 +45,26 @@ module Cadenya
45
45
  sig { params(initial_message: String).void }
46
46
  attr_writer :initial_message
47
47
 
48
- # Memory layers/entries to push onto this objective's memory stack on top of the
49
- # baseline stack inherited from the selected variation.
48
+ # Memory layers/entries layered over the baseline cascade inherited from the
49
+ # selected variation — element-level rules over inherited styles, in CSS terms.
50
50
  #
51
- # Array order is push order: the first element sits lower in the objective's
52
- # contribution to the stack; the LAST element ends up on top of the effective
53
- # stack. Entries pinned via memory_entry_id behave as single-entry layers at their
54
- # position.
51
+ # Array order is resolution order: EARLIER elements are more specific and are
52
+ # consulted first. Entries pinned via memory_entry_id behave as single-entry
53
+ # layers at their position.
55
54
  #
56
55
  # System-managed layers (e.g., episodic) cannot be referenced here; they attach
57
- # themselves automatically based on episodic_key.
56
+ # themselves automatically based on the episodic key.
58
57
  #
59
- # Stack size cap: the TOTAL effective stack (variation's memory layers
60
- #
61
- # - this field) must not exceed 10 entries. A request that would produce an
62
- # effective stack larger than 10 is rejected with InvalidArgument.
58
+ # Size cap: the TOTAL effective cascade (this field + the variation's memory layer
59
+ # assignments) must not exceed 10 entries. A request that would produce a larger
60
+ # cascade is rejected with InvalidArgument.
63
61
  sig { returns(T.nilable(T::Array[Cadenya::MemoryReference])) }
64
- attr_reader :memory_stack
62
+ attr_reader :memory_cascade
65
63
 
66
64
  sig do
67
- params(memory_stack: T::Array[Cadenya::MemoryReference::OrHash]).void
65
+ params(memory_cascade: T::Array[Cadenya::MemoryReference::OrHash]).void
68
66
  end
69
- attr_writer :memory_stack
67
+ attr_writer :memory_cascade
70
68
 
71
69
  # CreateOperationMetadata contains the user-provided fields for creating an
72
70
  # operation. Read-only fields (id, account_id, workspace_id, created_at,
@@ -116,7 +114,7 @@ module Cadenya
116
114
  episodic_memory:
117
115
  Cadenya::ObjectiveCreateParams::EpisodicMemory::OrHash,
118
116
  initial_message: String,
119
- memory_stack: T::Array[Cadenya::MemoryReference::OrHash],
117
+ memory_cascade: T::Array[Cadenya::MemoryReference::OrHash],
120
118
  metadata: Cadenya::CreateOperationMetadata::OrHash,
121
119
  secrets: T::Array[Cadenya::ObjectiveCreateParams::Secret::OrHash],
122
120
  user_data: T::Hash[Symbol, T.anything],
@@ -138,22 +136,20 @@ module Cadenya
138
136
  # this field nor a user_message_template is present, the request is rejected with
139
137
  # InvalidArgument.
140
138
  initial_message: nil,
141
- # Memory layers/entries to push onto this objective's memory stack on top of the
142
- # baseline stack inherited from the selected variation.
139
+ # Memory layers/entries layered over the baseline cascade inherited from the
140
+ # selected variation — element-level rules over inherited styles, in CSS terms.
143
141
  #
144
- # Array order is push order: the first element sits lower in the objective's
145
- # contribution to the stack; the LAST element ends up on top of the effective
146
- # stack. Entries pinned via memory_entry_id behave as single-entry layers at their
147
- # position.
142
+ # Array order is resolution order: EARLIER elements are more specific and are
143
+ # consulted first. Entries pinned via memory_entry_id behave as single-entry
144
+ # layers at their position.
148
145
  #
149
146
  # System-managed layers (e.g., episodic) cannot be referenced here; they attach
150
- # themselves automatically based on episodic_key.
151
- #
152
- # Stack size cap: the TOTAL effective stack (variation's memory layers
147
+ # themselves automatically based on the episodic key.
153
148
  #
154
- # - this field) must not exceed 10 entries. A request that would produce an
155
- # effective stack larger than 10 is rejected with InvalidArgument.
156
- memory_stack: nil,
149
+ # Size cap: the TOTAL effective cascade (this field + the variation's memory layer
150
+ # assignments) must not exceed 10 entries. A request that would produce a larger
151
+ # cascade is rejected with InvalidArgument.
152
+ memory_cascade: nil,
157
153
  # CreateOperationMetadata contains the user-provided fields for creating an
158
154
  # operation. Read-only fields (id, account_id, workspace_id, created_at,
159
155
  # profile_id) are excluded since they are set by the server.
@@ -180,7 +176,7 @@ module Cadenya
180
176
  data: T::Hash[Symbol, T.anything],
181
177
  episodic_memory: Cadenya::ObjectiveCreateParams::EpisodicMemory,
182
178
  initial_message: String,
183
- memory_stack: T::Array[Cadenya::MemoryReference],
179
+ memory_cascade: T::Array[Cadenya::MemoryReference],
184
180
  metadata: Cadenya::CreateOperationMetadata,
185
181
  secrets: T::Array[Cadenya::ObjectiveCreateParams::Secret],
186
182
  user_data: T::Hash[Symbol, T.anything],
@@ -53,8 +53,8 @@ module Cadenya
53
53
  attr_writer :finalized
54
54
 
55
55
  # MemoryRead is emitted each time the agent resolves a key against the memory
56
- # stack and loads an entry. Lookups that miss (key not found in any layer) do not
57
- # emit this event.
56
+ # cascade and loads an entry. Lookups that miss (key not found in any layer) do
57
+ # not emit this event.
58
58
  sig { returns(T.nilable(Cadenya::MemoryRead)) }
59
59
  attr_reader :memory_read
60
60
 
@@ -158,8 +158,8 @@ module Cadenya
158
158
  # compaction, or continuation are permitted.
159
159
  finalized: nil,
160
160
  # MemoryRead is emitted each time the agent resolves a key against the memory
161
- # stack and loads an entry. Lookups that miss (key not found in any layer) do not
162
- # emit this event.
161
+ # cascade and loads an entry. Lookups that miss (key not found in any layer) do
162
+ # not emit this event.
163
163
  memory_read: nil,
164
164
  sub_agent_spawned: nil,
165
165
  sub_agent_updated: nil,
@@ -36,12 +36,14 @@ module Cadenya
36
36
  sig { returns(String) }
37
37
  attr_accessor :current_context_window_id
38
38
 
39
- # The effective memory stack at objective creation time, flattened from the
40
- # variation's baseline plus Objective.memory_stack. Order is push order (last =
41
- # top). Returned on reads so clients can see exactly what stack the objective is
42
- # using without having to re-join variation state.
39
+ # The effective memory cascade at objective creation time: the episodic layer
40
+ # (when present), then Objective.memory_cascade, then the variation's baseline
41
+ # layers by ascending position. Order is resolution order index 0 is the most
42
+ # specific and is consulted first; the first layer containing a key wins. Returned
43
+ # on reads so clients can see exactly what the objective resolves against without
44
+ # re-joining variation state.
43
45
  sig { returns(T::Array[Cadenya::MemoryReference]) }
44
- attr_accessor :effective_memory_stack
46
+ attr_accessor :effective_memory_cascade
45
47
 
46
48
  # Total number of context windows that this objective has generated
47
49
  sig { returns(Integer) }
@@ -76,7 +78,7 @@ module Cadenya
76
78
  agent_variation: Cadenya::ResourceMetadata::OrHash,
77
79
  created_by: Cadenya::Profile::OrHash,
78
80
  current_context_window_id: String,
79
- effective_memory_stack: T::Array[Cadenya::MemoryReference::OrHash],
81
+ effective_memory_cascade: T::Array[Cadenya::MemoryReference::OrHash],
80
82
  total_context_windows: Integer,
81
83
  total_events: Integer,
82
84
  total_input_tokens: Integer,
@@ -97,11 +99,13 @@ module Cadenya
97
99
  # ID of the objective's current (most recent) context window. Hydrated on demand;
98
100
  # empty when the objective has not yet produced a context window.
99
101
  current_context_window_id:,
100
- # The effective memory stack at objective creation time, flattened from the
101
- # variation's baseline plus Objective.memory_stack. Order is push order (last =
102
- # top). Returned on reads so clients can see exactly what stack the objective is
103
- # using without having to re-join variation state.
104
- effective_memory_stack:,
102
+ # The effective memory cascade at objective creation time: the episodic layer
103
+ # (when present), then Objective.memory_cascade, then the variation's baseline
104
+ # layers by ascending position. Order is resolution order index 0 is the most
105
+ # specific and is consulted first; the first layer containing a key wins. Returned
106
+ # on reads so clients can see exactly what the objective resolves against without
107
+ # re-joining variation state.
108
+ effective_memory_cascade:,
105
109
  # Total number of context windows that this objective has generated
106
110
  total_context_windows:,
107
111
  # Total number of events generated during this objective's execution
@@ -125,7 +129,7 @@ module Cadenya
125
129
  agent_variation: Cadenya::ResourceMetadata,
126
130
  created_by: Cadenya::Profile,
127
131
  current_context_window_id: String,
128
- effective_memory_stack: T::Array[Cadenya::MemoryReference],
132
+ effective_memory_cascade: T::Array[Cadenya::MemoryReference],
129
133
  total_context_windows: Integer,
130
134
  total_events: Integer,
131
135
  total_input_tokens: Integer,
@@ -182,7 +182,7 @@ module Cadenya
182
182
  end
183
183
 
184
184
  # Attaches a memory layer to a variation at a given position in the variation's
185
- # baseline memory stack.
185
+ # baseline memory cascade.
186
186
  sig do
187
187
  params(
188
188
  variation_id: String,
@@ -205,8 +205,8 @@ module Cadenya
205
205
  # Body param: Layer to attach. Accepts the canonical `memlyr_…` form or the
206
206
  # `external_id:<value>` form.
207
207
  memory_layer_id: nil,
208
- # Body param: Position in the stack. If omitted, server appends (max existing
209
- # position + 1).
208
+ # Body param: Position in the baseline cascade (lower = more specific). If
209
+ # omitted, the server appends at the most general end (max existing position + 1).
210
210
  position: nil,
211
211
  request_options: {}
212
212
  )
@@ -4,8 +4,8 @@ module Cadenya
4
4
  module Resources
5
5
  class MemoryLayers
6
6
  # Manage memory layers and their entries. Layers are named containers that can be
7
- # composed into an objective's memory stack; entries are the keyed values within a
8
- # layer. System-managed layers (e.g., episodic layers created by the runtime)
7
+ # composed into an objective's memory cascade; entries are the keyed values within
8
+ # a layer. System-managed layers (e.g., episodic layers created by the runtime)
9
9
  # cannot be mutated through this API.
10
10
  class Entries
11
11
  # Creates a new entry in a memory layer. Returns the detail view, including the
@@ -3,13 +3,13 @@
3
3
  module Cadenya
4
4
  module Resources
5
5
  # Manage memory layers and their entries. Layers are named containers that can be
6
- # composed into an objective's memory stack; entries are the keyed values within a
7
- # layer. System-managed layers (e.g., episodic layers created by the runtime)
6
+ # composed into an objective's memory cascade; entries are the keyed values within
7
+ # a layer. System-managed layers (e.g., episodic layers created by the runtime)
8
8
  # cannot be mutated through this API.
9
9
  class MemoryLayers
10
10
  # Manage memory layers and their entries. Layers are named containers that can be
11
- # composed into an objective's memory stack; entries are the keyed values within a
12
- # layer. System-managed layers (e.g., episodic layers created by the runtime)
11
+ # composed into an objective's memory cascade; entries are the keyed values within
12
+ # a layer. System-managed layers (e.g., episodic layers created by the runtime)
13
13
  # cannot be mutated through this API.
14
14
  sig { returns(Cadenya::Resources::MemoryLayers::Entries) }
15
15
  attr_reader :entries
@@ -24,7 +24,7 @@ module Cadenya
24
24
  episodic_memory:
25
25
  Cadenya::ObjectiveCreateParams::EpisodicMemory::OrHash,
26
26
  initial_message: String,
27
- memory_stack: T::Array[Cadenya::MemoryReference::OrHash],
27
+ memory_cascade: T::Array[Cadenya::MemoryReference::OrHash],
28
28
  metadata: Cadenya::CreateOperationMetadata::OrHash,
29
29
  secrets: T::Array[Cadenya::ObjectiveCreateParams::Secret::OrHash],
30
30
  user_data: T::Hash[Symbol, T.anything],
@@ -46,22 +46,20 @@ module Cadenya
46
46
  # this field nor a user_message_template is present, the request is rejected with
47
47
  # InvalidArgument.
48
48
  initial_message: nil,
49
- # Memory layers/entries to push onto this objective's memory stack on top of the
50
- # baseline stack inherited from the selected variation.
49
+ # Memory layers/entries layered over the baseline cascade inherited from the
50
+ # selected variation — element-level rules over inherited styles, in CSS terms.
51
51
  #
52
- # Array order is push order: the first element sits lower in the objective's
53
- # contribution to the stack; the LAST element ends up on top of the effective
54
- # stack. Entries pinned via memory_entry_id behave as single-entry layers at their
55
- # position.
52
+ # Array order is resolution order: EARLIER elements are more specific and are
53
+ # consulted first. Entries pinned via memory_entry_id behave as single-entry
54
+ # layers at their position.
56
55
  #
57
56
  # System-managed layers (e.g., episodic) cannot be referenced here; they attach
58
- # themselves automatically based on episodic_key.
57
+ # themselves automatically based on the episodic key.
59
58
  #
60
- # Stack size cap: the TOTAL effective stack (variation's memory layers
61
- #
62
- # - this field) must not exceed 10 entries. A request that would produce an
63
- # effective stack larger than 10 is rejected with InvalidArgument.
64
- memory_stack: nil,
59
+ # Size cap: the TOTAL effective cascade (this field + the variation's memory layer
60
+ # assignments) must not exceed 10 entries. A request that would produce a larger
61
+ # cascade is rejected with InvalidArgument.
62
+ memory_cascade: nil,
65
63
  # CreateOperationMetadata contains the user-provided fields for creating an
66
64
  # operation. Read-only fields (id, account_id, workspace_id, created_at,
67
65
  # profile_id) are excluded since they are set by the server.
@@ -10,7 +10,7 @@ module Cadenya
10
10
  data: ::Hash[Symbol, top],
11
11
  episodic_memory: Cadenya::Objective::EpisodicMemory,
12
12
  info: Cadenya::ObjectiveInfo,
13
- memory_stack: ::Array[Cadenya::MemoryReference],
13
+ memory_cascade: ::Array[Cadenya::MemoryReference],
14
14
  output: ::Hash[Symbol, top],
15
15
  parent_objective_id: String,
16
16
  secrets: ::Array[Cadenya::ObjectiveSecret],
@@ -29,9 +29,9 @@ module Cadenya
29
29
  Cadenya::Objective::EpisodicMemory
30
30
  ) -> Cadenya::Objective::EpisodicMemory
31
31
 
32
- attr_reader memory_stack: ::Array[Cadenya::MemoryReference]?
32
+ attr_reader memory_cascade: ::Array[Cadenya::MemoryReference]?
33
33
 
34
- def memory_stack=: (
34
+ def memory_cascade=: (
35
35
  ::Array[Cadenya::MemoryReference]
36
36
  ) -> ::Array[Cadenya::MemoryReference]
37
37
 
@@ -80,7 +80,7 @@ module Cadenya
80
80
  ?data: ::Hash[Symbol, top],
81
81
  ?episodic_memory: Cadenya::Objective::EpisodicMemory,
82
82
  ?info: Cadenya::ObjectiveInfo,
83
- ?memory_stack: ::Array[Cadenya::MemoryReference],
83
+ ?memory_cascade: ::Array[Cadenya::MemoryReference],
84
84
  ?output: ::Hash[Symbol, top],
85
85
  ?parent_objective_id: String,
86
86
  ?secrets: ::Array[Cadenya::ObjectiveSecret],
@@ -97,7 +97,7 @@ module Cadenya
97
97
  data: ::Hash[Symbol, top],
98
98
  episodic_memory: Cadenya::Objective::EpisodicMemory,
99
99
  info: Cadenya::ObjectiveInfo,
100
- memory_stack: ::Array[Cadenya::MemoryReference],
100
+ memory_cascade: ::Array[Cadenya::MemoryReference],
101
101
  output: ::Hash[Symbol, top],
102
102
  parent_objective_id: String,
103
103
  secrets: ::Array[Cadenya::ObjectiveSecret],
@@ -7,7 +7,7 @@ module Cadenya
7
7
  data: ::Hash[Symbol, top],
8
8
  episodic_memory: Cadenya::ObjectiveCreateParams::EpisodicMemory,
9
9
  initial_message: String,
10
- memory_stack: ::Array[Cadenya::MemoryReference],
10
+ memory_cascade: ::Array[Cadenya::MemoryReference],
11
11
  metadata: Cadenya::CreateOperationMetadata,
12
12
  secrets: ::Array[Cadenya::ObjectiveCreateParams::Secret],
13
13
  user_data: ::Hash[Symbol, top],
@@ -35,9 +35,9 @@ module Cadenya
35
35
 
36
36
  def initial_message=: (String) -> String
37
37
 
38
- attr_reader memory_stack: ::Array[Cadenya::MemoryReference]?
38
+ attr_reader memory_cascade: ::Array[Cadenya::MemoryReference]?
39
39
 
40
- def memory_stack=: (
40
+ def memory_cascade=: (
41
41
  ::Array[Cadenya::MemoryReference]
42
42
  ) -> ::Array[Cadenya::MemoryReference]
43
43
 
@@ -67,7 +67,7 @@ module Cadenya
67
67
  data: ::Hash[Symbol, top],
68
68
  ?episodic_memory: Cadenya::ObjectiveCreateParams::EpisodicMemory,
69
69
  ?initial_message: String,
70
- ?memory_stack: ::Array[Cadenya::MemoryReference],
70
+ ?memory_cascade: ::Array[Cadenya::MemoryReference],
71
71
  ?metadata: Cadenya::CreateOperationMetadata,
72
72
  ?secrets: ::Array[Cadenya::ObjectiveCreateParams::Secret],
73
73
  ?user_data: ::Hash[Symbol, top],
@@ -81,7 +81,7 @@ module Cadenya
81
81
  data: ::Hash[Symbol, top],
82
82
  episodic_memory: Cadenya::ObjectiveCreateParams::EpisodicMemory,
83
83
  initial_message: String,
84
- memory_stack: ::Array[Cadenya::MemoryReference],
84
+ memory_cascade: ::Array[Cadenya::MemoryReference],
85
85
  metadata: Cadenya::CreateOperationMetadata,
86
86
  secrets: ::Array[Cadenya::ObjectiveCreateParams::Secret],
87
87
  user_data: ::Hash[Symbol, top],
@@ -6,7 +6,7 @@ module Cadenya
6
6
  agent_variation: Cadenya::ResourceMetadata,
7
7
  created_by: Cadenya::Profile,
8
8
  current_context_window_id: String,
9
- effective_memory_stack: ::Array[Cadenya::MemoryReference],
9
+ effective_memory_cascade: ::Array[Cadenya::MemoryReference],
10
10
  total_context_windows: Integer,
11
11
  total_events: Integer,
12
12
  total_input_tokens: Integer,
@@ -24,7 +24,7 @@ module Cadenya
24
24
 
25
25
  attr_accessor current_context_window_id: String
26
26
 
27
- attr_accessor effective_memory_stack: ::Array[Cadenya::MemoryReference]
27
+ attr_accessor effective_memory_cascade: ::Array[Cadenya::MemoryReference]
28
28
 
29
29
  attr_accessor total_context_windows: Integer
30
30
 
@@ -43,7 +43,7 @@ module Cadenya
43
43
  agent_variation: Cadenya::ResourceMetadata,
44
44
  created_by: Cadenya::Profile,
45
45
  current_context_window_id: String,
46
- effective_memory_stack: ::Array[Cadenya::MemoryReference],
46
+ effective_memory_cascade: ::Array[Cadenya::MemoryReference],
47
47
  total_context_windows: Integer,
48
48
  total_events: Integer,
49
49
  total_input_tokens: Integer,
@@ -57,7 +57,7 @@ module Cadenya
57
57
  agent_variation: Cadenya::ResourceMetadata,
58
58
  created_by: Cadenya::Profile,
59
59
  current_context_window_id: String,
60
- effective_memory_stack: ::Array[Cadenya::MemoryReference],
60
+ effective_memory_cascade: ::Array[Cadenya::MemoryReference],
61
61
  total_context_windows: Integer,
62
62
  total_events: Integer,
63
63
  total_input_tokens: Integer,