FLUXFLUX
  • Introduction
  • Quickstart
  • From Your Data to a Synthetic Copy
  • Two Specs, One Substrate
  • The Six Families
  • The FLUID Seam
  • Deterministic & Governed
  • Runtime & Evidence
  • Anatomy
  • The Nineteen Kinds
  • Versions
  • Changelog
  • JSON Schema 0.5.4
  • UI Hints 0.5.4
  • Enforcement Contract 0.5.0
  • Bundle Manifest 0.5.0
  • Overview
  • Tutorial
  • How-to guides
  • Reference
  • Explanation
  • Command line
  • Error codes
  • Accuracy program
  • The vNext Plan
  • The Nine RFCs
  • Playback Source (proposed)
  • Conformance Profiles
Examples
What's New
FLUID
GitHub
  • Introduction
  • Quickstart
  • From Your Data to a Synthetic Copy
  • Two Specs, One Substrate
  • The Six Families
  • The FLUID Seam
  • Deterministic & Governed
  • Runtime & Evidence
  • Anatomy
  • The Nineteen Kinds
  • Versions
  • Changelog
  • JSON Schema 0.5.4
  • UI Hints 0.5.4
  • Enforcement Contract 0.5.0
  • Bundle Manifest 0.5.0
  • Overview
  • Tutorial
  • How-to guides
  • Reference
  • Explanation
  • Command line
  • Error codes
  • Accuracy program
  • The vNext Plan
  • The Nine RFCs
  • Playback Source (proposed)
  • Conformance Profiles
Examples
What's New
FLUID
GitHub
  • FLUX Simulation Engine
  • Tutorial
    • First evidence pack in five minutes
  • How-to guides
    • Model your customers
    • Add a journey
    • Use the FLUID seam
    • Calibrate from aggregates: declare a scorecard
    • Draw a column given another
    • Ship with evidence
    • Write a bundle from a profile
    • Score a run against a profile, in full or sampled
    • Seal and score a prediction
    • Load a simulation into a database
  • Reference
    • Command line
      • fluxsim init
      • fluxsim validate
      • fluxsim plan
      • fluxsim apply
      • fluxsim run
      • fluxsim verify
      • fluxsim ship
      • fluxsim replay
      • fluxsim calibrate
      • fluxsim accuracy
      • fluxsim gate
      • fluxsim expr
      • fluxsim describe
      • fluxsim plugins
      • fluxsim explain
    • Error codes
    • Python API
    • Schemas
    • Specifications
      • FLUX Simulation Engine: kernel normative specification (v0.1)
      • FLUX Simulation Engine: kernel v2 normative specification (v0.2)
      • Seam generator and fidelity check: normative specification (v0.1)
      • Profile document: normative specification (format 1-1-0)
      • Scorecard: normative specification (format 1-1-0)
      • Sample-based verification: normative specification
      • Parameter register: normative specification (format 1-1-0)
      • flux-expr/1: normative specification (v0.1)
      • flux-expr/2: normative specification (v0.1)
      • flux-expr/3: normative specification (v0.1)
  • Explanation
    • Architecture and patterns
    • The six-step loop
    • Determinism and the seed tree
    • The FLUID seam
    • The evidence pack, and what it does not claim
  • Accuracy program

    • The accuracy program: design
    • Accuracy report

Write a bundle from a profile

Use this page when you have a FLUID contract for a table and a profile of its data, and want synthetic rows that follow both. One command writes the bundle:

fluxsim init bundle --contract contract.orders.fluid.yaml --profile orders.profile.json

It reads the two documents and never a record. Each number it writes is a published aggregate of the profile, a fact of the contract, or an assumption, and the Simulation's parameter register says which, number by number. The run it makes is then checked against the profile and packed with its evidence.

The data owner makes the profile where the data lives, with fluid profile, and the contract usually comes from fluid init --discover. This page writes both by hand so it runs anywhere: 600 orders with an id, a country, an amount and a time.

1. The two documents

The contract, as fluid init --discover writes it for a Parquet file:

# contract.orders.fluid.yaml
fluidVersion: 0.7.6
kind: DataProduct
id: bronze.orders.orders
name: orders / orders
domain: data
description: Source-aligned Bronze ingestion for orders / orders.
metadata:
  layer: Bronze
  productType: SDP
  owner:
    team: data-platform
builds:
- id: ingest_orders
  description: Discovered-source ingest of 1 stream(s).
  pattern: acquisition
  engine: duckdb
  capabilities:
  - full_refresh
  - schema_discovery
  properties:
    source:
      kind: filesystem
      connection:
        uri: file:///srv/orders/data
      mode: full_refresh
      streams:
      - orders
    sink:
      format: parquet
  outputs:
  - orders
exposes:
- exposeId: orders
  kind: table
  binding:
    platform: local
    format: parquet
    location:
      path: ./out/orders.parquet
  contract:
    schema:
    - name: order_id
      type: varchar
      required: false
    - name: country
      type: varchar
      required: false
    - name: amount
      type: decimal(10,2)
      required: false
    - name: created_at
      type: timestamp
      required: false

The profile, as fluid profile writes it: a row count, per column the metrics its output checks let out, and for the number column its mean (mean/1), the statistic a run is checked against. A value the checks withheld carries a status code and no value, here A (a small count, or a zero):

$ cat > orders.profile.json <<'EOF'
{
  "_producer": "https://github.com/Agenticstiger/forge-cli/tree/main/fluid_build/profiler",
  "_schemaURL": "https://agenticstiger.github.io/flux/engine/spec/profile/1-0-0/FluxProfile.json",
  "encoding": {"fractionalBits": 16, "rounding": "floor"},
  "disclosureRules": {
    "acro-default": {"dominance": {"k": "0.90", "n": 2}, "minimumCell": 10, "pRatio": "0.10", "roundingBase": 5, "zerosDisclosive": true}
  },
  "tables": {
    "orders": {
      "rowCount": 600,
      "columns": {
        "amount": {
          "domain": "number",
          "metrics": {
            "count": {"definition": "count/1", "disclosure": "acro-default", "sampleSize": {"max": 602, "min": 598}, "status": "F", "value": 600},
            "distinctCount": {"definition": "distinctCount/1", "disclosure": "acro-default", "sampleSize": {"max": 602, "min": 598}, "status": "F", "value": 10},
            "max": {"definition": "max/1", "disclosure": "acro-default", "sampleSize": {"max": 602, "min": 598}, "status": "F", "value": "100"},
            "min": {"definition": "min/1", "disclosure": "acro-default", "sampleSize": {"max": 602, "min": 598}, "status": "F", "value": "10"},
            "nullCount": {"definition": "nullCount/1", "disclosure": "acro-default", "sampleSize": {"max": 602, "min": 598}, "status": "A"},
            "quantiles": {"definition": "quantiles/1", "disclosure": "acro-default", "sampleSize": {"max": 602, "min": 598}, "status": "F", "values": {"0.25": "20", "0.5": "35", "0.75": "50"}},
            "sum": {"definition": "sum/1", "disclosure": "acro-default", "sampleSize": {"max": 602, "min": 598}, "status": "F", "value": "27750"}
          },
          "statistics": [
            {"definition": "mean/1", "disclosure": "acro-default", "groups": [{"Sx": "1818624000", "group": "", "k": 600, "status": "F"}], "sampleSize": {"max": 602, "min": 598}}
          ]
        },
        "country": {
          "domain": "category",
          "metrics": {
            "count": {"definition": "count/1", "disclosure": "acro-default", "sampleSize": {"max": 602, "min": 598}, "status": "F", "value": 600},
            "distinctCount": {"definition": "distinctCount/1", "disclosure": "acro-default", "sampleSize": {"max": 602, "min": 598}, "status": "F", "value": 5},
            "nullCount": {"definition": "nullCount/1", "disclosure": "acro-default", "sampleSize": {"max": 602, "min": 598}, "status": "A"}
          }
        },
        "created_at": {
          "domain": "timestamp",
          "metrics": {
            "count": {"definition": "count/1", "disclosure": "acro-default", "sampleSize": {"max": 602, "min": 598}, "status": "F", "value": 600},
            "distinctCount": {"definition": "distinctCount/1", "disclosure": "acro-default", "sampleSize": {"max": 602, "min": 598}, "status": "F", "value": 310},
            "max": {"definition": "max/1", "disclosure": "acro-default", "sampleSize": {"max": 602, "min": 598}, "status": "A"},
            "min": {"definition": "min/1", "disclosure": "acro-default", "sampleSize": {"max": 602, "min": 598}, "status": "A"},
            "nullCount": {"definition": "nullCount/1", "disclosure": "acro-default", "sampleSize": {"max": 602, "min": 598}, "status": "A"},
            "quantiles": {"definition": "quantiles/1", "disclosure": "acro-default", "sampleSize": {"max": 602, "min": 598}, "status": "A"}
          }
        },
        "order_id": {
          "domain": "category",
          "metrics": {
            "count": {"definition": "count/1", "disclosure": "acro-default", "sampleSize": {"max": 602, "min": 598}, "status": "F", "value": 600},
            "distinctCount": {"definition": "distinctCount/1", "disclosure": "acro-default", "sampleSize": {"max": 602, "min": 598}, "status": "F", "value": 600},
            "nullCount": {"definition": "nullCount/1", "disclosure": "acro-default", "sampleSize": {"max": 602, "min": 598}, "status": "A"}
          }
        }
      }
    }
  }
}
EOF

2. Write the bundle

$ fluxsim init bundle --contract contract.orders.fluid.yaml --profile orders.profile.json
created bundle from contract.orders.fluid.yaml and orders.profile.json (4 files):

  contract.orders.fluid.yaml  the FLUID contract, copied unchanged
  world.flux.yml              the least World a run needs: the generator emits read none of its numbers
  persona.flux.yml            the least Persona a run needs, for the same reason
  simulation.flux.yml         the run: one generator emit per profiled expose, the profile pin and the register

orders: 600 rows, 4 columns
  order_id    an identifier: 600 distinct values in 600, so the engine derives one per row
  country     5 opaque levels, at equal weights
  amount      a histogram over 5 published order statistics, shaped to the published mean
  created_at  uniform within the run's time window: the profile publishes no order statistic

parameters: 34 declared -- 12 from the pinned profile, 19 assumed, 3 default
assumed (the register gives each assumed number its reason; replace what you know better):
  - country: The profile publishes how many distinct values the column holds and neither the values nor their counts: as many opaque levels, named country-<n>, at equal weights.
  - country, amount, created_at: The profile withheld nullCount (status A): a count withheld as small is zero or below the minimum cell, so no nulls are drawn.
  - amount: Drawn evenly within its bins, the histogram would give a mean other than the one the profile publishes, so within each bin the values are drawn from the part on the mean's side: each bin keeps its share of the rows, so every published quantile or bin count holds, and the mean is the published one, or as near to it as the bins allow on the column's grid.
  - created_at: The profile withheld every order statistic, so it is drawn within the run's time window (spec.timeBounds).
  - time window: No date or timestamp column publishes its range, so the run covers 2026-01-01 to 2026-12-31. Set spec.timeBounds to the span your data covers.

next:
  fluxsim run bundle --profile orders.profile.json

The directory must not exist yet, or must be empty: nothing is ever overwritten. The profile stays outside the bundle, which holds only FLUX and FLUID documents; the Simulation pins its digest instead. Before it writes a file, the command checks the bundle as fluxsim validate does, and as plan does from the documents alone before a row is drawn, and writes nothing either refuses.

3. What each number rests on

The rules run from the most the profile says to the least:

The profile or the contract saysThe bundle declaresSource in the register
a table's rowCountthe emit's rowsprofile
a column's min and maxits range, which the fidelity check holds the run toprofile
min, the quartiles and maxhistogram bins and binWeights, a quarter of the rows in eachprofile
a mean: sum and count, or a mean/1 statisticthe histogram shaped to that mean and, for a mean/1 over a number column with a published range, a mean property the run is checked againstprofile, with the shape assumed
nullCountnullFractionprofile
a histogram, level counts or a list of levelsbins and weights, levels, and a property the run is scored onprofile
as many distinct values as valuesunique: true: an identifier the engine derivesno number
an enum(...) typesupport: declared, with maxCardinality its number of levelscontract
a key, in its semanticsno key of its own: the engine reads keys from the contractno number
nothing, or a withheld valuean assumption, stated with its reasonassumption

These rules shape the assumptions:

  • A column's range and support are what the fidelity check holds the run, and a slice of real records, to: a value outside them is refused. So they are declared only from a published value or the contract. A shape that rests on an assumption, such as the opaque country levels, is declared with keys only the generator reads. One exception: a fidelity block needs a property, so in a table where no column publishes a range or its levels, one column's assumed span or levels is declared for the check, and the output says so.
  • A count withheld as a small one (status A: a bin, a level or the distinct values) lies below its rule's minimum cell, so it is assumed to be half of it: 5, under ACRO's default of 10. Any other status says nothing of a count's size, so a cell withheld under one is assumed to be the mean of the cells its table publishes. A withheld null count is the exception. It is most often a zero, which the checks withhold as disclosive, so no nulls are drawn rather than nulls invented in every column.
  • A number key lies between its published min and max when they hold one value per row. Otherwise its span is assumed, 1 to the row count. It is widened to the values the foreign keys that reference it are declared over, or moved inside the key it references when that key's span is published, down a chain of keys. A foreign key the profile says nothing of is drawn over the span of the key it references.
  • A column of a key over several columns spans its rows the same way, and a text one takes as many opaque levels as rows, so the key can hold one value per row. A key's columns declare no nullFraction, nor does an inner foreign key, and a composite foreign key takes its nulls from its first column alone.
  • A histogram's outer edges are often round numbers beyond the data. Its draw keeps to the published min and max, while the check reads the histogram's own edges.
  • Drawn evenly within its quartile bins, amount would average about 40, and the profile says 46.25. So within each quartile bin the values are drawn from the part on the mean's side: each bin keeps its quarter of the rows, so every published quartile holds, and the mean is the published one. The cuts this adds are assumptions in the register.
  • The World and the Persona are the least a run needs. Their numbers are default in the register: the generator emits read none of them.

A date or timestamp bound is RFC 3339 text, which the register does not count, so an assumed time window is in the command's output and nowhere else. Here no time column publishes its range, because no single instant is held by ten orders, and created_at is drawn within the run's timeBounds.

The register is the parameters list in simulation.flux.yml. Each entry names a number by a JSON Pointer and gives its source: a pointer into the profile and the statistic it lands in, a pointer into the contract, or a reason:

$ grep -A 4 'emits/orders/rows' bundle/simulation.flux.yml
      pointer: /extensions/com.agentics.flux~11/emits/orders/rows
      source: profile
      statistic:
        pointer: /tables/orders/rowCount
    - document: sim-bronze.orders.orders

plan reads every citation in the profile it is handed, and refuses one the profile does not publish (FLX-3113). A contract citation is read in the bundle's contract by every command.

4. Replace the assumptions you can

The assumptions are a first draft. Where you know better, edit the Simulation, and change the number's register entry with it: give it your own reason, or a citation. Here you might:

  • set spec.timeBounds to the quarter the orders cover;
  • name the countries you know in place of country-1 to country-5, with their weights;
  • tighten the property's tolerance to the margin you accept.

5. Run it, check it, ship it

$ fluxsim run bundle --profile orders.profile.json --verify --ship -o out
plan written to ...
coverage: orders: 1 of 4 columns fell back to a type default
  created_at (TIMESTAMP): uniform within the simulation's time bounds: the column declares no draw of its own
--strict-coverage refuses the run, and so does strictCoverage in the bundle; fluxsim explain FLX-3304 says how to cover a column
parameters: 34 declared -- 12 from the pinned profile, 19 assumed, 3 default
applied to ...
emitted orders: 600 rows (generator)
reproducible: not checked | validity: not asserted
...
  fidelity orders: passed -- 1 of 1 declared property within the margin against the pinned profile
  parameters: 34 declared -- 12 from the pinned profile, 19 assumed, 3 default
  scorecard: overall ... against profile sha256:...
...
shipped out/bundle.flux.tgz
run ... complete; shipped to out

The run's mean amount is within the property's 10 % of the profile's, so the check passes, the scorecard scores it, and ship packs the run with its evidence. created_at is reported as a type default, because the profile gave it nothing to declare: it is drawn within the run's time window, and the evidence report names it under "What Was Not Proven", beside the register's shares.

6. What the check does not cover

A run is checked against the statistics a profile publishes, and this one publishes a mean for amount alone. Nothing checks the country levels, which the profile never names, or created_at, whose time window is assumed. A profile with no statistic a property can be checked against, as fluid profile wrote before it wrote mean/1, gives a bundle whose one property verify --profile refuses with FLX-5037, and the command's output says so. Given more statistics (histograms, level counts), fluxsim init declares a property for each one it can carry: Score a run against a profile shows the check.

Some columns carry no property at all. A boolean column's counts shape its draw, but the check reads a category's values as text. A date column's bounds are declared in days, while a profile reads a date as a timestamp in milliseconds. And an integer column whose published values pass 2^53 is a placeholder, 0 on every row, because a run's rows cannot hold such an integer exactly.

What the command refuses

Nothing is written when:

  • the directory holds anything, or cannot be written;
  • --contract comes without --profile, or the reverse (exit 2);
  • the profile cannot be read (FLX-3109) or is not a profile (FLX-5036);
  • the profile describes none of the contract's exposes: the message names the tables on both sides;
  • the bundle would not validate or plan, for example because the contract does not: the message gives the engine's own reason.

An expose is left out of the bundle, and named in the output with the reason, when the profile does not describe it, when a column of it is JSON or bytes (the generator has no draw for them), when a DECIMAL column of it has more than 38 decimal places, or when no column of it has a range or levels a property could read. The exposes of one contract are generated together, so a foreign key into an expose left out is refused, as plan refuses it (FLX-3403), and nothing is written. If the profile has no table for the expose it references, profile that table too. If the command left that expose out for another reason, such as a JSON column, the relationship cannot be generated as the contract declares it.

Last Updated: 11/19/26, 8:45 AM
Prev
Ship with evidence
Next
Score a run against a profile, in full or sampled