Skip to content

Add Feature Requirements, Architecture Design, and Dependable Element Wiring for score/memory - #953

Draft
castler wants to merge 6 commits into
eclipse-score:mainfrom
castler:feature/memory-requirements
Draft

Add Feature Requirements, Architecture Design, and Dependable Element Wiring for score/memory#953
castler wants to merge 6 commits into
eclipse-score:mainfrom
castler:feature/memory-requirements

Conversation

@castler

@castler castler commented Aug 18, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Builds out the S-CORE dependability artifacts for score/memory, following the pattern established by score/message_passing and score/mw/com.

Feature Requirements

  • score/memory/dependability/assumed_system/assumed_system_requirements.trlc: system-level assumed requirement (SharedMemoryIPC, ASIL B) and a SafeState mitigation.
  • score/memory/dependability/requirements/feature_requirements.trlc: 14 FeatReq records derived from the assumed system requirements.

Architecture Design

  • score/memory/dependability/software_architectural_design/{static_design.puml,public_api.puml,BUILD}: static decomposition of the Memory SEooC into a Memory component with 5 sub-components (SharedMemoryManagement, OffsetPointer, SharedMemoryContainers, SharedMemorySynchronization, TypedAndSealedMemory) containing 10 units, plus the public API surface.
  • score/memory/dependability/software_unit_design/BUILD: unit_design() stubs for all 10 units.

Dependable Element / Component / Unit wiring

  • score/memory/shared/BUILD: 10 unit() targets mapping each software unit to its real cc_library implementation(s) and cc_unit_test targets.
  • score/memory/dependability/BUILD (new): 5 component() targets grouping the units, a parent component_memory, and the dependable_element_memory target wiring together the architectural design, requirements, and components. dependability_analysis is intentionally left empty pending a future FMEA/FMEDA.
  • Minor visibility widenings in flock/BUILD, test_offset_ptr/BUILD, sealedshm_wrapper/BUILD so the new unit() targets can reference their tests.
  • static_design.puml unit aliases renamed to match the Bazel *_unit target names for a clean architecture-to-Bazel naming consistency check.

Verification

  • bazel test //score/memory/dependability/assumed_system:assumed_system_requirements_test //score/memory/dependability/requirements:feature_requirements_test — PASSED
  • bazel build //score/memory/shared:all //score/memory/dependability:dependable_element_memory — succeeds
  • buildifier --lint=warn --mode=check — clean

Co-authored-by: Copilot 223556219+Copilot@users.noreply.github.com

@castler castler changed the title Add Feature Requirements for score/memory Add Feature Requirements and Architecture Design for score/memory Aug 18, 2026
@castler castler changed the title Add Feature Requirements and Architecture Design for score/memory Add Feature Requirements, Architecture Design, and Dependable Element Wiring for score/memory Aug 18, 2026
castler and others added 4 commits August 18, 2026 16:47
@castler
Add Feature Requirements for score/memory
99c1019 
Introduces the ScoreMemory dependability requirements package,
following the pattern established by score/message_passing:

- assumed_system/assumed_system_requirements.trlc: system-level
  requirement for shared-memory IPC and a safe-silent mitigation.
- requirements/feature_requirements.trlc: 14 FeatReq records derived
  from the assumed system requirements, covering transparent memory
  abstraction, polymorphic allocation across heap/shared memory,
  process-relative offset pointers, offset-pointer bounds checking,
  shared-memory resource lifecycle, access control, stale-artefact
  cleanup, typed memory support, concurrent reader/writer-safe region
  tracking, sealed shared memory, inter-process mutexes,
  shared-memory-safe containers, mock injection for testing, and
  graceful degradation to safe-silent on resource failure.
- BUILD files wiring assumed_system_requirements and
  feature_requirements Bazel targets, including the manual
  feature_requirements_ai_check target.

Verified with:
  bazel test //score/memory/dependability/assumed_system:assumed_system_requirements_test \
             //score/memory/dependability/requirements:feature_requirements_test

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@castler
Add Architecture Design for score/memory
11f396a 
Introduces the S-CORE architectural design artifacts for the Memory
SEooC, following the pattern established by score/message_passing:

- software_architectural_design/static_design.puml: static
  decomposition of the Memory SEooC into one top-level component
  containing five sub-components (SharedMemoryManagement,
  OffsetPointer, SharedMemoryContainers, SharedMemorySynchronization,
  TypedAndSealedMemory), each grouping the units mirroring the
  existing score/memory/shared source layout (ManagedMemoryResource,
  SharedMemoryResource, SharedMemoryFactory, MemoryResourceRegistry,
  OffsetPtr, PolymorphicOffsetPtrAllocator, Containers, FlockMutex,
  TypedMemory, SealedSharedMemory).
- software_architectural_design/public_api.puml: the public interfaces
  exposed to callers (ManagedMemoryResource, ISharedMemoryResource,
  ISharedMemoryFactory, OffsetPtr, PolymorphicOffsetPtrAllocator).
- software_architectural_design/BUILD: wires the architectural_design
  Bazel target (maturity = "development").
- software_unit_design/BUILD: stub unit_design targets for each of the
  10 units identified in the static diagram, ready to be filled in
  with per-unit class/sequence diagrams.

Verified with:
  bazel build //score/memory/dependability/software_architectural_design:memory_architectural_design \
              //score/memory/dependability/software_unit_design:all
Both targets build successfully (maturity = "development" downgrades
the public-API-port validation finding to a warning, matching the
same, pre-existing finding in score/message_passing's own
architectural design).

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@castler
Add dependable_element/component/unit wiring for score/memory
e04e55c 
Wires the score/memory dependability artifacts into the Bazel
rules_score dependable_element hierarchy, following the pattern
established by score/message_passing and score/mw/com:

- score/memory/shared/BUILD: define 10 unit() targets (one per
  software unit from the static architecture design), each mapping
  to the real cc_library implementation(s) and cc_unit_test targets
  already present in score/memory/shared. Unit implementation lists
  are kept to a single representative library per unit where
  possible, since the validator's AST-based class-diagram check does
  not deduplicate classes reached via multiple transitive include
  paths; maturity = "development" is set on every unit so any
  remaining (non-blocking) findings surface as warnings instead of
  hard build failures, consistent with the SEooC's current
  development stage.
- score/memory/shared/flock/BUILD,
  score/memory/shared/test_offset_ptr/BUILD,
  score/memory/shared/sealedshm/sealedshm_wrapper/BUILD: widen test
  target visibility to //score/memory/shared:__pkg__ so the new
  unit() targets (which must live alongside their cc_library
  counterparts in score/memory/shared) can reference them.
- score/memory/dependability/BUILD (new): 5 component() targets
  grouping the 10 units (SharedMemoryManagement, OffsetPointer,
  SharedMemoryContainers, SharedMemorySynchronization,
  TypedAndSealedMemory), a parent component_memory component, and the
  dependable_element_memory target wiring in the architectural
  design and assumed-system/feature requirements created previously.
  dependability_analysis is left empty pending a future FMEA/FMEDA.
- software_unit_design/BUILD: fix unit_design() visibility to target
  //score/memory/shared (where the real unit() targets live) instead
  of //score/memory.
- static_design.puml: rename unit aliases to match the *_unit Bazel
  target names (avoiding collisions with existing cc_library targets
  of the same base name) so the architecture-to-Bazel naming
  consistency check passes cleanly.

Verified via `bazel build //score/memory/shared:all
//score/memory/dependability:dependable_element_memory` and
`bazel test` on the existing requirements targets; buildifier clean.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@castler
Add score memory unit design diagrams
1f4a088 
Author real static and dynamic unit design diagrams for the score/memory software units and wire them into the unit_design targets. The diagrams complement the architecture-level public API design by documenting unit-level structure and key runtime flows.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@castler
castler marked this pull request as draft August 19, 2026 03:48
castler and others added 2 commits August 19, 2026 06:54
@castler
Refine memory unit design class diagrams
506d2c0 
Strengthen the score/memory unit-design PlantUML static diagrams with real class members and relationships drawn from the implementation headers, while keeping the architecture-level public API boundary separate.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@castler
Fix unit design diagrams not rendering in generated docs
e53736b 
The unit_design rule (rules_score private/unit_design.bzl) is currently
a stub: unlike architectural_design (which calls make_puml_rst_wrappers()
to auto-generate an RST wrapper with a `.. uml::` directive for every bare
.puml input), unit_design just passes raw files through untouched.

dependable_element's per-unit doc generator (_generate_unit_doc in
private/dependable_element.bzl) only emits an "Unit Design" section/
toctree entry for ".rst"/".md" "document" files (_is_document_file());
bare ".puml" files are merely symlinked next to the unit page and never
referenced by any directive. As a result, all 10 score/memory unit design
diagrams were silently absent from the generated docs even though the
unit_design() targets built successfully.

Add a minimal hand-authored ".rst" wrapper (title + `.. uml:: <file>.puml`)
for each of the 19 diagram files, modeled on rules_score's own
puml_diagram.template.rst, and list it alongside its .puml file in each
unit_design()'s static/dynamic attrs. This can be removed once unit_design
gains the same auto-wrapping support as architectural_design upstream.

Actually wiring the diagrams into the Sphinx build surfaced a genuine
PlantUML syntax error that had never been caught before because the
diagram was never actually rendered: managed_memory_resource_dynamic.puml
used an unescaped multi-line quoted participant label, which is invalid
sequence-diagram syntax. Fixed by joining it onto a single line.

Verified:
- bazel build //score/memory/dependability:dependable_element_memory now
  renders all diagrams as SVGs on their respective unit pages (confirmed
  via generated _html/units/*.html and _sources/units/*.rst.txt output).
- bazel build //score/memory/dependability/software_unit_design:all
  //score/memory/shared:all - succeeds.
- bazel test assumed_system_requirements_test / feature_requirements_test
  - PASSED.
- buildifier --lint=warn --mode=check - clean.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@hoe-jo hoe-jo Awaiting requested review from hoe-jo hoe-jo is a code owner
@LittleHuba LittleHuba Awaiting requested review from LittleHuba LittleHuba is a code owner
@crimson11 crimson11 Awaiting requested review from crimson11 crimson11 is a code owner
@bemerybmw bemerybmw Awaiting requested review from bemerybmw bemerybmw is a code owner
@limdor limdor Awaiting requested review from limdor limdor is a code owner

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

None yet

Projects

COM - Communication FT
Status: Backlog

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@castler