BaryoDev / BaryoDev/barakoCMS

Epic: dogfood Verdict, Carom and Mapsicle in barakoCMS

Open
#704 0 comments 0 reactions 0 assignees View on GitHub
core enhancement epic
Dominant language
C#
Stars
6
Forks
7
Avg merge
4h 42m
Merged PRs (30d)
307

Description

BaryoDev publishes three .NET libraries that barakoCMS does not use: [Verdict](https://github.com/BaryoDev/Verdict) (zero-allocation results, MPL-2.0), [Carom](https://github.com/BaryoDev/Carom) (resilience, MPL-2.0) and [Mapsicle](https://github.com/BaryoDev/Mapsicle) (object mapping, MIT). `Directory.Packages.props` references none of them.

This epic is to change that deliberately, in an order chosen by risk, with the constraints written down before the first package is added rather than discovered in a review.

## Why this is a real reason and not a rationalisation

Each of those repos makes a measured claim: zero allocations on the hot path, 72-189x over FluentResults, 1.00x hand-written code on a nine-type aggregate. Those are benchmark claims. barakoCMS is the largest .NET codebase this org controls, it runs multi-tenant against real Postgres with real third-party providers, and it is the only place those claims meet a system that has incidents. A library whose only consumer is its own benchmark suite is a benchmark, not a product.

The value runs both ways, and the return leg is the more valuable one: defects and API gaps found here go back as issues on the library repos. That is the part that cannot be got from writing more samples.

It also sits under the `ROADMAP.md` thesis. What BaryoDev publishes is free and stays free, and a library nothing serious runs on is a weaker version of that promise than one the CMS itself depends on.

## Order, by risk

**1. Carom.** Lowest risk, and the only one of the three that fixes something broken rather than improving something that works. Two issues are already filed and are the whole of this step:

- #702, `JobBackoff` has no jitter, so a provider outage retries every job in lockstep. This is a defect on its own terms and worth fixing whether or not Carom is the vehicle.
- #703, an outbound action gets one attempt at the socket, and nothing stops hammering a provider that is down.

**2. Verdict.** Internal code only. `WorkflowActionResult` is already a hand-rolled result type with the same shape (`Succeeded`, `Error`, `Retryable`, plus `Success` / `Failure` / `PermanentFailure` factories), so the ergonomics question is genuinely answerable here.

Be clear-eyed about what is being proven. Verdict's headline number is against FluentResults, which this codebase does not use; it throws, and uses FastEndpoints' `ThrowError`. So the perf ROI is measured against a library we do not have. What dogfooding actually tests is whether the API holds up across a large codebase and where it is missing pieces, which is worth knowing and is not what a benchmark answers.

Best first target is new service code that would otherwise throw for an expected outcome. `Core/Interfaces/StaleContentException.cs` is control flow by exception. `Verdict.AspNetCore` is worth reading against #648, which is an open bug about malformed input answering 500 instead of 4xx and is exactly an error-shape problem.

**3. Mapsicle.** Last, and module-local rather than core. `BarakoCMS.Accounting` has typed documents and `BarakoCMS.Portability` does export and import shape conversion, so both are real workloads. Core is the wrong place: it has 16 `public static ... From(` methods in total, and its hard mapping problem is dynamic (`Content.Data` is a `Dictionary` validated against a runtime `ContentType`), which is not what an object mapper addresses.

## Constraints that do not bend

**Nothing enters the module contract.** `IWorkflowAction.RunAsync` keeps returning `WorkflowActionResult`. It is public extension surface under section 6, and D18 promises module authors that a member arrives with a default implementation and an obsolete window. Changing that return type would break every module author and force a Verdict dependency on all of them, for no functional gain.

**A core dependency reaches every module transitively.** Anything core does not itself need should be adopted in the module that needs it. That is MODULES.md working as intended.

**The lease budget in #703 is a design input, not a detail.** Inner retries that outrun `WorkflowRetryPolicy.LeaseDuration` (5 minutes) or `Jobs:LeaseSeconds` (600) cause an action to run twice with one outcome recorded, which `WorkflowRunner` handles by discarding the loser on purpose.

**Every package needs a `Directory.Packages.props` entry and a regenerated `packages.lock.json`.** CI restores in locked mode and a stale lock fails NU1004 rather than being silently regenerated.

**`EVENT-SOURCING-PER-CONTENT-TYPE.md` currently cites Mapsicle as the cautionary tale**, twice, as the example of a conversion cascade where the same rule was written three times and the copies drifted. Adopting Mapsicle without amending that doc leaves the repo arguing with itself. Either the doc gets the context it is missing, or step 3 needs a better answer than it has now.

**Release cadences couple.** A bug in one of these becomes a barakoCMS patch release. Licences are clean and consistent (MPL-2.0 for Carom and Verdict, matching this repo; MIT for Mapsicle), but #626 is on the board because ImageSharp's terms moved underneath us, and self-owned is not the same as risk-free.

## Done when

Each of the three is either adopted in a named place with tests, or has a written reason it was not, on this issue. A step that stalls should say so rather than staying open indefinitely.

Contributor guide

Open the contributing guide

Research direction

Start with Directory.Packages.props and packages.lock.json, then read #702, #703, WorkflowActionResult, Core/Interfaces/StaleContentException.cs, #648, and EVENT-SOURCING-PER-CONTENT-TYPE.md. Evaluate Carom, Verdict, and Mapsicle in the named workloads without changing IWorkflowAction.RunAsync or adding unnecessary core dependencies. Done means each package is adopted with tests in a named place, or has a written reason it was not.

Written by the indexing model from the issue text.

Assessment

Tech stack
csharp
Domain
backend
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
32/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.