Cohesive.Simulation 0.1.0-alpha.84

Cohesive.Simulation

Cohesive.Simulation provides deterministic synthetic-data generation, property cases, replayable worlds, scheduled scenarios, and provider-neutral provisioning over canonical Cohesive shapes. Typed C# builders are the ordinary authoring surface; portable IR remains the semantic authority used by tests, scripts, seeders, and tools.

Install

The current alpha targets .NET 10:

dotnet add package Cohesive.Simulation --prerelease

Add only the integrations the application uses:

Core depends only on Cohesive; Relations, Storage, Transitions, xUnit, CLI, ExternalProcess, and provider integrations stay in optional packages. The CLI can consume a strict portable ExternalProcess import definition while keeping executable paths and process limits local to the invocation, then atomically retain and independently verify the resulting catalog.

Generate a POCO

using Cohesive.Simulation;
using Cohesive.Simulation.Generation;

var customers = Simulation.Define<Customer>(customer => customer
    .Member(value => value.Name, Gen.Categorical(
        Gen.Weighted("Ada", weight: 1d),
        Gen.Weighted("Grace", weight: 1d)))
    .Member(value => value.Age, Gen.Int32(minimum: 18, maximum: 90))
    .Member(value => value.IsActive, Gen.Bernoulli(probability: 0.85)));

Generated<Customer> generated = customers.Compile().Generate(seed: 42);

public sealed record Customer(string Name, int Age, bool IsActive);

The seed is only one replay coordinate. Exact definition identity, revision, fingerprint, scope, interpreter, entropy algorithm, and sequence index are retained with generated observations so replay fails closed against changed semantics.

Check properties

PropertyCaseRunResult run = customers.Compile().CheckProperty(
    seed: 42,
    property: static customer => customer.Age >= 18,
    options: new(requiredPassedCases: 250));

The runner-neutral result contains stable diagnostics, coverage, and a semantically shrunk counterexample with a replay token when the property fails. Cohesive.Simulation.Xunit adds PropertyCaseAssert.Passed(run) without making xUnit part of generation semantics.

Compose and retain a world

using Cohesive.Simulation.Artifacts;
using Cohesive.Simulation.Worlds;

var world = Simulation.DefineWorld("world/demo", "r1", builder => builder
    .Population("customers", count: 100, customers)
    .Exemplar("customer-for-browser", "customers", sequenceIndex: 7));

CompiledWorldPlan plan = world.Compile();
WorldArtifactManifest artifact = WorldArtifactManifest.FromWorld(plan, rootSeed: 42);
string manifestJson = WorldArtifactManifestJsonSerializer.Serialize(artifact);

The manifest is the retained cross-process authority. It embeds the exact portable world, root seed, interpreter, entropy algorithm, compiled population projections, and exemplars behind a content-addressed artifact ID. Persist it before provisioning when data crosses a process or storage boundary.

using Cohesive.Simulation.Provisioning;

await using var output = File.Create("demo.jsonl");
var sink = new WorldJsonLinesSink("demo/artifact", output);
await WorldProvisioner.ProvisionAsync(artifact, sink, new(batchSize: 500));

output.Position = 0;
await WorldJsonLinesVerifier.VerifyAsync(artifact, output);

Provisioning is bounded, deterministic, and sink-neutral. Stable run and batch identities support reconciliation, but the reference provisioner does not invent retries or transactional guarantees a destination cannot provide.

Current alpha boundary

Implemented generators are constants, inclusive uniform Int32, Bernoulli, weighted categorical, exact retained generation catalogs, object/member composition, and correlated record sampling with typed projections. Catalog documents pin values, weights, locale, adapter/provider versions, normalized producer capability profiles, distinct profile and import source evidence, known deviations, and a semantic fingerprint. The same canonical definitions support direct examples, bounded sequences, property cases, static populations, named exemplars, relationship-linked worlds, repository seeding, and portable artifacts.

Worlds currently describe static initial state. Scenarios add actors, declared operations, fixed virtual-time actions, deterministic actor materialization, an explicit runtime interpreter seam, contract-checked outcomes, and fingerprint-verified complete traces. Core and relationship-world materializers expose each actor's observation, entity identity, and origin replay evidence to the runner. Actions can return explicit complete before/after actor replacements; the runner applies them immutably between actions, rejects stale evidence, and retains the verified state chain for final-world reconstruction. Actor creation and deletion, events, queues, resources, and fault policies remain later explicit interpretations rather than implicit callback behavior. Cohesive.Adapters.Bogus and Cohesive.Adapters.Mimesis provide optional snapshot producers without making either provider a core dependency.

Current portable schemas and replay tokens reject earlier versions rather than silently assigning compatibility semantics. See the compatibility guide before retaining artifacts across package upgrades.

Learn more

• Getting started
• Adoption and agentic assurance
• Artifacts, replay, and verification
• Repository seeding and Playwright
• Deterministic scenarios
• Alpha compatibility contract
• Executable end-to-end example
• Relationship worlds
• Repository provisioning
• Transition-driven scenarios
• xUnit integration
• CLI tool
• Bogus catalog adapter
• Mimesis catalog adapter