Skip to content

Commit 2fabcda

Browse files
VincentVilletVincentVillet
committed
[ADD] multiple-usage-journeys-per-pattern tasks.
1 parent 1d61608 commit 2fabcda

4 files changed

Lines changed: 261 additions & 15 deletions

File tree

‎efootprint/core/usage/job.py‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -21,11 +21,9 @@
2121
if TYPE_CHECKING:
2222
from efootprint.core.usage.usage_pattern import UsagePattern
2323
from efootprint.core.usage.usage_journey import UsageJourney
24-
from efootprint.core.usage.usage_journey_step import UsageJourneyStep
2524
from efootprint.core.hardware.network import Network
2625
from efootprint.core.usage.edge.edge_usage_journey import EdgeUsageJourney
2726
from efootprint.core.usage.edge.edge_usage_pattern import EdgeUsagePattern
28-
from efootprint.core.usage.edge.recurrent_server_need import RecurrentServerNeed
2927

3028

3129
@dataclass(frozen=True, eq=False)

‎specs/features/multiple-usage-journeys-per-pattern/plan.html‎

Lines changed: 36 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@
2525
<body>
2626

2727
<h1>Multiple usage journeys per pattern — Implementation plan</h1>
28-
<p class="status">Status: Plan — <strong>under review</strong> · 2026-09-01 ·
28+
<p class="status">Status: Plan — <strong>approved</strong> · 2026-09-01 ·
2929
Spec: <a href="spec.html">spec.html</a></p>
3030

3131
<section>
@@ -46,6 +46,12 @@ <h2>1. Approach</h2>
4646
and footprint calculations, preventing physical fabrication and idle/base energy from being repeated
4747
per bundle.</p>
4848

49+
<p>Validate memory and cache scaling immediately after the library behavior lands, before adapting the
50+
interface. Establish <code>e-footprint/performance/memory/</code> as the canonical home for model-engine
51+
benchmarks so calculation changes can be profiled and refined beside their implementation. Keep only
52+
Django startup, <code>ModelWeb</code>, rendered-payload, memory-monitor, cgroup, and production-container
53+
measurements in e-footprint-interface; retain its historical evidence in place.</p>
54+
4955
<svg viewBox="0 0 800 310" role="img" aria-labelledby="flow-title flow-desc">
5056
<title id="flow-title">Journey-aware pattern calculation flow</title>
5157
<desc id="flow-desc">A web pattern fans out through weighted journeys and an edge pattern fans
@@ -110,21 +116,25 @@ <h2>2. Affected modules</h2>
110116
<tbody>
111117
<tr><td><code>efootprint/core/usage/usage_pattern.py</code></td><td>modified</td><td>Weighted non-empty journey relationship, weight metadata, occurrence terminology, aggregate jobs, and relationship validation.</td></tr>
112118
<tr><td><code>efootprint/core/usage/usage_journey.py</code><br><code>usage_journey_step.py</code></td><td>modified</td><td>Apply the pattern-specific journey weight; cache step occupancy by the actual <code>(pattern, journey)</code> path when a step is reused within one pattern.</td></tr>
113-
<tr><td><code>efootprint/core/usage/edge/edge_usage_pattern.py</code><br><code>edge_usage_journey.py</code></td><td>modified</td><td>Move span/concurrency to the deployment pattern; add the non-empty journey list; expose one typed, non-serialized containment inventory of server-need and component-need paths.</td></tr>
119+
<tr><td><code>efootprint/core/usage/edge/edge_usage_pattern.py</code><br><code>edge_usage_journey.py</code></td><td>modified</td><td>Move span/concurrency to the deployment pattern; enforce the non-empty, duplicate-free journey list; expose one typed, non-serialized containment inventory of server-need and component-need paths.</td></tr>
114120
<tr><td><code>efootprint/core/usage/job.py</code></td><td>modified</td><td>Add journey to web occurrence coordinates; keep the edge base coordinate at <code>(pattern, recurrent server need)</code> and carry bundle identity plus scalar path share on attribution cells.</td></tr>
115121
<tr><td><code>efootprint/core/usage/edge/recurrent_*.py</code></td><td>modified</td><td>Expand one recurring series per <code>(pattern, need)</code> over the calendar covered by the deployment series, multiply it by <code>nb_of_occurrences_of_self_within_usage_pattern</code> obtained from the inventory, then apply active deployments in downstream physical aggregation.</td></tr>
116122
<tr><td><code>efootprint/core/hardware/device.py</code></td><td>modified</td><td>Sum weighted journey occupancy per pattern and emit one device atom per journey/step path.</td></tr>
117123
<tr><td><code>efootprint/core/hardware/edge/edge_component.py</code><br><code>edge_device.py</code></td><td>modified</td><td>Use pattern-level active deployments for fixed hardware; combine aggregate need demand before component energy and allocation; split the resulting need atoms across inventory paths while retaining existing transient source helpers.</td></tr>
124+
<tr><td><code>efootprint/core/hardware/server_base.py</code><br><code>storage.py</code><br><code>network.py</code><br><code>efootprint/builders/external_apis/external_api_base_class.py</code></td><td>modified</td><td>Propagate the explicit journey carried by every Job attribution cell into the atoms emitted by all server-side impact sources.</td></tr>
118125
<tr><td><code>efootprint/core/system.py</code></td><td>modified</td><td>Flatten journeys from all pattern collections and preserve stable deduplication for system traversal.</td></tr>
119126
<tr><td><code>efootprint/core/attribution/__init__.py</code></td><td>modified</td><td>Store explicit journey identity in atom coordinates and serialized matrix rows instead of deriving a singular journey from the pattern.</td></tr>
127+
<tr><td><code>efootprint/comparison/</code></td><td>verified / modified as needed</td><td>Expose weighted web journey membership and weight changes with the “Journeys per pattern occurrence” relationship label through the existing input-diff machinery.</td></tr>
120128
<tr><td><code>efootprint/api_utils/version_upgrade_handlers.py</code><br><code>efootprint/version.py</code><br><code>pyproject.toml</code></td><td>modified</td><td>Introduce the next schema major and transform singular relationships, edge span ownership, occurrence field names, and incompatible calculated state.</td></tr>
121129
<tr><td><code>efootprint/modeling_templates/</code><br><code>efootprint/builders/</code><br><code>docs_sources/</code></td><td>modified as applicable</td><td>Update constructors, examples, template authoring sources, generated descriptions, and public reference wording.</td></tr>
122130
<tr><td><code>tests/</code></td><td>modified / expanded</td><td>Update fixtures and API callers; add multi-journey computation, mutation, persistence, migration, attribution, and reuse coverage.</td></tr>
131+
<tr><td><code>performance/memory/</code><br><code>tests/performance_tests/</code></td><td>new / modified</td><td>Move model-engine memory scenarios close to e-footprint: native hydration, totals, cold/warm attribution matrix, direct attribution, shared-child topology generation, cache/slot counts, and fresh-process evidence. Permit measured library refinements before interface adaptation.</td></tr>
123132
<tr><td><code>../e-footprint-interface/model_builder/domain/entities/web_core/usage/</code></td><td>modified</td><td>Expose web weights, edge bundle selection, pattern-owned span/defaults, non-empty creation defaults, and plural volume terminology.</td></tr>
124133
<tr><td><code>../e-footprint-interface/model_builder/adapters/forms/</code><br><code>adapters/ui_config/</code></td><td>modified</td><td>Use the existing weighted-dict and multi-select patterns; preselect the first journey, preserve weight sources, prevent last removal, and update labels/tooltips.</td></tr>
125134
<tr><td><code>../e-footprint-interface/model_builder/domain/entities/web_core/usage/usage_pattern_web_base_class.py</code></td><td>modified</td><td>Emit canvas links to every selected journey while retaining top-level journey cards rather than rendering them as nested accordion children.</td></tr>
126135
<tr><td><code>../e-footprint-interface/model_builder/domain/services/system_validation_service.py</code></td><td>modified</td><td>Keep computation-readiness messages aligned with the new cardinality and bundle semantics as a user-facing safeguard.</td></tr>
127136
<tr><td><code>../e-footprint-interface/scripts/intro_template_scenarios/</code><br><code>tests/</code></td><td>modified / expanded</td><td>Update scenario builders, form snapshots, integration workflows, results smoke cases, and one critical Playwright flow for each paradigm.</td></tr>
137+
<tr><td><code>../e-footprint-interface/performance/memory/</code></td><td>refined</td><td>Keep the production adapter concerns: Django/application imports, <code>ModelWeb</code> and session hydration, rendered Sankey payloads, computation-memory monitor modes, cgroup enforcement, and container calibration. Preserve historical evidence and point model-engine benchmarking to the library.</td></tr>
128138
</tbody>
129139
</table>
130140
</section>
@@ -193,14 +203,24 @@ <h2>3. Calculation and relationship details</h2>
193203
<li>Do not add transient semantics to <code>computed_dict</code> in this feature unless profiling first
194204
demonstrates a material retained-memory regression and a separately reviewed lifetime design covers
195205
all shared consumers and dependent structures.</li>
206+
<li>Run model-engine memory work from the library immediately after the core implementation. Native
207+
scenarios load through e-footprint, compute totals, cold/warm attribution matrices, and direct attributed
208+
footprints while varying patterns, journeys, shared children, and modeled hours. Findings may drive a
209+
focused library refinement before the interface task begins.</li>
210+
<li>Do not relocate historical interface measurements: they describe production-container and middleware
211+
behavior. Slim future interface profiling to runtime/adapter overhead and keep calculation/cache physics in
212+
the library benchmark.</li>
196213
</ul>
197214
</details>
198215
<details><summary>Cardinality enforcement</summary>
199216
<p>Use domain guards that read relationship membership/weights so a live mutation participates in
200-
<code>ModelingUpdate</code> and rolls back atomically. Also reject empty constructor input and
201-
validate raw loaded pattern records before hydration makes them live, because the current loader
202-
intentionally does not compute guards. The interface mirrors the invariant by preselecting the
203-
first journey and disabling removal of the final relationship; it is not the source of truth.</p>
217+
<code>ModelingUpdate</code> and rolls back atomically. Reject empty constructor input on both sides,
218+
non-positive web weights, and duplicate edge journey references. Validate the same invariants in raw
219+
loaded pattern records before hydration makes them live, because the current loader intentionally does
220+
not compute guards. Web uniqueness already follows from weighted-dictionary keys; edge uniqueness needs
221+
an explicit guard because lists and JSON arrays permit duplicates. The interface mirrors the invariant
222+
by preselecting the first journey and disabling removal of the final relationship; it is not the source
223+
of truth.</p>
204224
</details>
205225
</section>
206226

@@ -232,26 +252,30 @@ <h2>5. Cross-cutting concerns</h2>
232252
<li><strong>Library tests:</strong> cover weights below/above 1, two journeys with distinct and
233253
shared steps/jobs, two edge bundles with distinct and shared needs, one journey reused by several
234254
patterns, physical edge-footprint non-duplication, last-link mutation rollback, dependency
235-
invalidation after membership/weight changes, and all old single-journey behavior at weight 1.</li>
255+
invalidation after membership/weight changes, duplicate-edge-journey rejection at construction,
256+
mutation, and load, edge-list order invariance, and all old single-journey behavior at weight 1.</li>
236257
<li><strong>Attribution tests:</strong> extend conservation harness cases with multiple journeys
237258
under one pattern and reused lower-level objects. Assert journey nodes and matrix rows remain
238259
distinguishable and sum to eager footprint streams. Assert each need's
239260
<code>nb_of_occurrences_of_self_within_usage_pattern</code> equals the sum of its inventory paths'
240261
<code>nb_occurrences</code> and normalized path shares sum to one.</li>
241262
<li><strong>Serialization tests:</strong> round-trip both relationship types and weight sources;
242263
add the version migration and verify old calculated state cannot attach under obsolete coordinates.</li>
264+
<li><strong>Comparison tests:</strong> verify adding/removing a web journey and changing its weight
265+
produces relationship-diff rows labelled “Journeys per pattern occurrence”.</li>
243266
<li><strong>Interface tests:</strong> unit snapshots for the weighted/multi-select forms and moved
244267
usage span; integration create/edit/delete flows including the last-link invariant; results-view
245268
smoke coverage; one non-redundant E2E flow for weighted web journeys and one for multiple edge bundles.</li>
246269
<li><strong>Recomputation:</strong> verify recreated web coordinates select stable computed-dictionary
247270
sub-slots, a journey weight or membership edit invalidates only the affected coordinate cone, departed
248271
paths are pruned, and edge relationship edits rebuild the containment inventory and its dependent
249272
aggregate series.</li>
250-
<li><strong>Performance and memory:</strong> update benchmark accessors and big-system generation.
251-
Exercise <code>cold-sankey</code>, <code>results-primed-sankey</code>, and direct-attribution scenarios
252-
with many journeys and shared children; compare materialized coordinate-subslot counts, peak and retained
253-
memory, and reactive callback counts. Assert hourly cache growth follows actual web paths and distinct
254-
edge <code>(pattern, need)</code> pairs, never a Cartesian product or edge bundle-path count.</li>
273+
<li><strong>Performance and memory:</strong> add a library-native memory laboratory and update benchmark
274+
accessors/big-system generation. Exercise native hydration, totals, cold/warm attribution matrix, primed
275+
calculation, and direct-attribution scenarios with many journeys and shared children; compare materialized
276+
coordinate-subslot counts, peak and retained memory, and reactive callback counts. Assert hourly cache growth
277+
follows actual web paths and distinct edge <code>(pattern, need)</code> pairs, never a Cartesian product or edge
278+
bundle-path count. Keep interface profiling focused on production adapter/container behavior.</li>
255279
<li><strong>Docs:</strong> update library relationship, persistence, attribution, and modeling pages;
256280
update interface architecture's relationship/form section and user-journey design/help text. This
257281
is the non-trivial relationship pattern documentation required by both repositories' agent guidance.</li>

‎specs/features/multiple-usage-journeys-per-pattern/spec.html‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@
2828
<body>
2929

3030
<h1>Multiple usage journeys per pattern</h1>
31-
<p class="status">Status: Spec — under review · 2026-09-01</p>
31+
<p class="status">Status: Spec — approved · 2026-09-01</p>
3232

3333
<section>
3434
<h2>1. Problem and audience</h2>

0 commit comments

Comments
 (0)