Integrations

Integration modules are optional adapters. Core generation remains dependency free; install the corresponding extra before using a sink or publisher.

Note

These adapters are versioned with the core package, but their third-party services are not. Pin the client extra and validate connectivity in CI before publishing a run.

PostgreSQL

fraudtwin.postgres.persist_run	Persist one generated run atomically after migrations have been applied.
fraudtwin.postgres.persist_scale_records	Persist a partition-record stream without whole-run materialization.
fraudtwin.postgres.migrate_database	Apply the packaged, ordered PostgreSQL migrations and return the version.
fraudtwin.postgres.database_status	Return applied migration versions without changing the database.
fraudtwin.postgres.PostgresPersistenceResult	Non-secret metadata recorded in a generated run manifest.

Kafka and lakehouse

fraudtwin.kafka.KafkaPublisher	Publish mapped M24 records with deterministic pacing and acknowledgements.
fraudtwin.kafka.publication_records	Map all observable M24 records into one deterministic publication order.
fraudtwin.kafka.topic_for	Return the stable versioned topic for an M24 subject.
fraudtwin.lakehouse.IcebergLakehouse	Small PyIceberg writer with immutable append and snapshot metadata.
fraudtwin.lakehouse.materialize_run	Backfill one generated run and optionally commit it to Iceberg.
fraudtwin.lakehouse.materialize_dataset	Materialize already-loaded domain objects without regenerating them.
fraudtwin.lakehouse.verify_materialization	Validate a materialization manifest without contacting Iceberg.

Kafka reliability

The chaos harness models logical delivery semantics without changing event identity or payload data. It is useful for testing retry, loss, duplication, delay, reordering, and partition-skew handling before connecting a broker.

fraudtwin.kafka_chaos.KafkaChaosConfig	Immutable, seeded policy for logical Kafka delivery faults.
fraudtwin.kafka_chaos.ChaosEnvelope	Transport metadata wrapped around one immutable publication payload.
fraudtwin.kafka_chaos.KafkaChaosResult	Auditable output of one seeded logical-message chaos run.
fraudtwin.kafka_chaos.simulate_delivery	Apply seeded logical-message faults at a producer or consumer boundary.

from fraudtwin.kafka_chaos import KafkaChaosConfig, simulate_delivery

result = simulate_delivery(records, KafkaChaosConfig(seed=7, duplicate_probability=0.1))
print(result.manifest["counts"])

Replay and scale

fraudtwin.replay.replay_run	Select and order an existing run without regenerating any source data.
fraudtwin.replay.write_replay	Write a replay artifact below the supplied destination root.
fraudtwin.scale.resolve_scale_plan	Resolve the opt-in scale configuration, returning None when disabled.
fraudtwin.scale.require_scale_plan	Resolve an enabled scale plan and narrow away the optional result.
fraudtwin.scale.iter_chunks	Yield deterministic half-open chunk descriptors.
fraudtwin.scale.write_checkpoint	Atomically publish a checkpoint manifest.
fraudtwin.scale.load_checkpoint	Load and validate a checkpoint manifest.
fraudtwin.scale.reconcile_logical_ids	Detect duplicate/lost IDs and return a serializable reconciliation result.
fraudtwin.scale.aggregate_fingerprint	Hash rows incrementally without retaining the complete input.
fraudtwin.scale.chunk_payment_ranges	Yield stable shard-local payment chunks without materializing IDs.
fraudtwin.scale.iter_partition_rows	Read scale chunks one file at a time, keeping reader memory bounded.
fraudtwin.scale.iter_partition_query	Execute an out-of-core DuckDB query over partitioned Parquet.
fraudtwin.scale.iter_payment_ranges	Yield deterministic contiguous payment ordinal ranges per shard.
fraudtwin.scale.run_scale_benchmark	Run one explicitly requested scale job and publish machine evidence.
fraudtwin.scale.write_scale_benchmark_manifest	Write non-deterministic machine evidence separately from run identity.
fraudtwin.storage.FsspecScaleStorage	S3/MinIO-compatible publisher backed by optional fsspec.
fraudtwin.storage.LocalScaleStorage	Filesystem implementation used by default and in CI.
fraudtwin.storage.storage_for	Resolve a configured storage backend without importing optional packages.