> ## Documentation Index
> Fetch the complete documentation index at: https://docs.canary.effectiveai.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Check messages: citations

> Each filed number cites the document that states it.

*Generated from the `rslc` compiler.*

## E-PROVENANCE

**A filed number needs a citation.**

Each table, constant and rounding states a number from the filing. The check asks each one to cite the region of the source document that prints it.

A citation tells a reviewer where to look. A number that the filing leaves unstated, such as a unit conversion, says why with `[reason: "…"]`.

**Example**

The constant `rate_per_1000` carries a filed rate and lacks a citation.

```rsl theme={"languages":{"custom":["languages/rsl.tmLanguage.json"]}}
Constants = {
    rate_per_1000 = 2
}
```

```sh theme={"languages":{"custom":["languages/rsl.tmLanguage.json"]}}
rslc check bad/rater.rsl
```

```text theme={"languages":{"custom":["languages/rsl.tmLanguage.json"]}}
FAIL bad/rater.rsl (strict)
error: E-PROVENANCE bad/rater.rsl:17:5: constant `rate_per_1000` has no citation
  = because: every filed number cites the filing region that states it; a number no filing states says why in `[reason: "…"]`
  = help: cite the region that states it, `rate_per_1000 [cite: manual:p12] = …`, or say why no filing does: `rate_per_1000 [reason: "unit conversion"] = …`
  = applicability: manual
cost premium: 1 (each list of size 1: 1, 3: 1, 10: 1)
```

**Fix**

Cite the page that prints the rate.

```rsl theme={"languages":{"custom":["languages/rsl.tmLanguage.json"]}}
Constants = {
    rate_per_1000 [cite: manual:p3] = 2
}
```

> [accordion] Complete files
>
> ```rsl bad/rater.rsl theme={"languages":{"custom":["languages/rsl.tmLanguage.json"]}}
> spec {
>     rsl: "0.4.1",
>     carrier: "Example Mutual",
>     state: AZ,
>     product: "Staffing Liability",
>     effective_date: 2026-01-01
> }
>
> Sources = {
>     manual: Source = {
>         artifact: artifact("00000000-0000-4000-8000-000000000000"),
>         kind: pdf
>     }
> }
>
> Constants = {
>     rate_per_1000 = 2
> }
>
> Records = {
>     Policy = {
>         inputs {
>             payroll: Num {precision: int} where self in [0, 100000000]
>         },
>         step rating {
>             premium: Premium [cite: manual:p3] = round(self.payroll / 1000 * rate_per_1000, 2, half_up)
>         }
>     }
> }
>
> RatingOutcomes = {
>     premium: Policy.premium
> }
> ```
>
> ```rsl good/rater.rsl theme={"languages":{"custom":["languages/rsl.tmLanguage.json"]}}
> spec {
>     rsl: "0.4.1",
>     carrier: "Example Mutual",
>     state: AZ,
>     product: "Staffing Liability",
>     effective_date: 2026-01-01
> }
>
> Sources = {
>     manual: Source = {
>         artifact: artifact("00000000-0000-4000-8000-000000000000"),
>         kind: pdf
>     }
> }
>
> Constants = {
>     rate_per_1000 [cite: manual:p3] = 2
> }
>
> Records = {
>     Policy = {
>         inputs {
>             payroll: Num {precision: int} where self in [0, 100000000]
>         },
>         step rating {
>             premium: Premium [cite: manual:p3] = round(self.payroll / 1000 * rate_per_1000, 2, half_up)
>         }
>     }
> }
>
> RatingOutcomes = {
>     premium: Policy.premium
> }
> ```

## E-SOURCE-SCHEMA

**A source has an artifact and a kind.**

`Sources` declares each document a rater cites. A source has exactly two fields. `artifact` holds the ID of the stored document, written `artifact("<uuid>")` with a lowercase UUID. `kind` is the file type, written bare: `pdf`, `xlsx`, `csv`, `html`, `zip`, `png` or `parquet`.

A citation such as `[cite: manual:p3]` names a source and a region inside it. The fixed shape lets every tool open the same stored document at the cited page.

**Example**

The source `manual` has a third field, `title`.

```rsl theme={"languages":{"custom":["languages/rsl.tmLanguage.json"]}}
    manual: Source = {
        artifact: artifact("00000000-0000-4000-8000-000000000000"),
        kind: pdf,
        title: "Rate manual"
    }
}
```

```sh theme={"languages":{"custom":["languages/rsl.tmLanguage.json"]}}
rslc check bad/rater.rsl
```

```text theme={"languages":{"custom":["languages/rsl.tmLanguage.json"]}}
FAIL bad/rater.rsl (strict)
error: E-SOURCE-SCHEMA bad/rater.rsl:13:9: source 'manual' has unknown field 'title'. A Source has exactly these fields: artifact: artifact("<uuid>"), kind: pdf | xlsx | csv | html | zip | png | parquet. Delete it or move the text to a comment.
```

**Fix**

Delete the extra field. Text that helps a reader, such as the document's title, fits in a comment.

```rsl theme={"languages":{"custom":["languages/rsl.tmLanguage.json"]}}
    manual: Source = {
        artifact: artifact("00000000-0000-4000-8000-000000000000"),
        kind: pdf
    }
}
```

**Other causes**

* A source lacks `artifact` or `kind`.
* A source states one field twice.
* `kind` is a quoted string such as `"pdf"`, or a file type outside the list.
* `artifact` holds something other than `artifact("…")`, such as a bare string or `file("manual.pdf")`.
* The ID inside `artifact("…")` is something other than a lowercase UUID, such as `"rate-manual"`.

> [accordion] Complete files
>
> ```rsl bad/rater.rsl theme={"languages":{"custom":["languages/rsl.tmLanguage.json"]}}
> spec {
>     rsl: "0.4.1",
>     carrier: "Example Mutual",
>     state: AZ,
>     product: "Staffing Liability",
>     effective_date: 2026-01-01
> }
>
> Sources = {
>     manual: Source = {
>         artifact: artifact("00000000-0000-4000-8000-000000000000"),
>         kind: pdf,
>         title: "Rate manual"
>     }
> }
>
> Constants = {
>     rate_per_1000 [cite: manual:p3] = 2
> }
>
> Records = {
>     Policy = {
>         inputs {
>             payroll: Num {precision: int} where self in [0, 100000000]
>         },
>         step rating {
>             premium: Premium [cite: manual:p3] = round(self.payroll / 1000 * rate_per_1000, 2, half_up)
>         }
>     }
> }
>
> RatingOutcomes = {
>     premium: Policy.premium
> }
> ```
>
> ```rsl good/rater.rsl theme={"languages":{"custom":["languages/rsl.tmLanguage.json"]}}
> spec {
>     rsl: "0.4.1",
>     carrier: "Example Mutual",
>     state: AZ,
>     product: "Staffing Liability",
>     effective_date: 2026-01-01
> }
>
> Sources = {
>     manual: Source = {
>         artifact: artifact("00000000-0000-4000-8000-000000000000"),
>         kind: pdf
>     }
> }
>
> Constants = {
>     rate_per_1000 [cite: manual:p3] = 2
> }
>
> Records = {
>     Policy = {
>         inputs {
>             payroll: Num {precision: int} where self in [0, 100000000]
>         },
>         step rating {
>             premium: Premium [cite: manual:p3] = round(self.payroll / 1000 * rate_per_1000, 2, half_up)
>         }
>     }
> }
>
> RatingOutcomes = {
>     premium: Policy.premium
> }
> ```

## E-CITATION

**A citation names a declared source and region.**

A citation names a source and a region inside it: `[cite: manual:p3]`. The check asks for a source that `Sources` declares and a region that fits the source's `kind`:

* `pdf`: a page `p33` or a page range `pp20-24`
* `xlsx`: a cell `'Sheet name'!A2` or a cell range `'Sheet name'!A2:F20`
* `csv` and `parquet`: `row 12` or `rows 12-20`
* `html`: `anchor "rates"`
* `zip`: `member "rates/manual.pdf"`
* `png`: `image`

A citation that resolves lets a reviewer open the document at the place that states the number.

**Example**

The constant cites `manual:page3`, and `manual` is a PDF, so the region reads `p3`.

```rsl theme={"languages":{"custom":["languages/rsl.tmLanguage.json"]}}
Constants = {
    rate_per_1000 [cite: manual:page3] = 2
}
```

```sh theme={"languages":{"custom":["languages/rsl.tmLanguage.json"]}}
rslc check bad/rater.rsl
```

```text theme={"languages":{"custom":["languages/rsl.tmLanguage.json"]}}
FAIL bad/rater.rsl (strict)
error: E-CITATION bad/rater.rsl:17:26: citation 'manual:page3': region `page3` is not a pdf region; write `p33` or `pp20-24`.
```

**Fix**

Write the page as `p3`.

```rsl theme={"languages":{"custom":["languages/rsl.tmLanguage.json"]}}
Constants = {
    rate_per_1000 [cite: manual:p3] = 2
}
```

**Other causes**

* The citation names a source that `Sources` lacks, such as `filing:p3` beside a source named `manual`.
* A page or row number is 0, or a range runs backwards; pages and rows start at 1.
* A citation sits on a type or a source; cite the table, constant, step, calculation or input that uses the document.
* A table's `otherwise` row lacks a citation; write `otherwise [cite: manual:p3]: { … }`.
* A table column maps to the CSV header `cite`; that header holds a citation for each row.
* A cell of a table's `cite` column holds a citation the table leaves undeclared, or text of another shape.
* A `then:` tie priority of a ranking function such as `argmax` lacks a citation; write `then [cite: manual:p3]: …`.
* A placeholder carries `@manual:p3` after `nl "…"`; cite the calculation in its place.
* A calculation's body is a quoted string; write a placeholder as `nl "…"`.

> [accordion] Complete files
>
> ```rsl bad/rater.rsl theme={"languages":{"custom":["languages/rsl.tmLanguage.json"]}}
> spec {
>     rsl: "0.4.1",
>     carrier: "Example Mutual",
>     state: AZ,
>     product: "Staffing Liability",
>     effective_date: 2026-01-01
> }
>
> Sources = {
>     manual: Source = {
>         artifact: artifact("00000000-0000-4000-8000-000000000000"),
>         kind: pdf
>     }
> }
>
> Constants = {
>     rate_per_1000 [cite: manual:page3] = 2
> }
>
> Records = {
>     Policy = {
>         inputs {
>             payroll: Num {precision: int} where self in [0, 100000000]
>         },
>         step rating {
>             premium: Premium [cite: manual:p3] = round(self.payroll / 1000 * rate_per_1000, 2, half_up)
>         }
>     }
> }
>
> RatingOutcomes = {
>     premium: Policy.premium
> }
> ```
>
> ```rsl good/rater.rsl theme={"languages":{"custom":["languages/rsl.tmLanguage.json"]}}
> spec {
>     rsl: "0.4.1",
>     carrier: "Example Mutual",
>     state: AZ,
>     product: "Staffing Liability",
>     effective_date: 2026-01-01
> }
>
> Sources = {
>     manual: Source = {
>         artifact: artifact("00000000-0000-4000-8000-000000000000"),
>         kind: pdf
>     }
> }
>
> Constants = {
>     rate_per_1000 [cite: manual:p3] = 2
> }
>
> Records = {
>     Policy = {
>         inputs {
>             payroll: Num {precision: int} where self in [0, 100000000]
>         },
>         step rating {
>             premium: Premium [cite: manual:p3] = round(self.payroll / 1000 * rate_per_1000, 2, half_up)
>         }
>     }
> }
>
> RatingOutcomes = {
>     premium: Policy.premium
> }
> ```

## E-PROVENANCE-RUNTIME

**Provenance stays out of rating data.**

Provenance says where a number comes from. In RSL it lives in citations, such as `[cite: manual:p3]` on a table. The compiler checks each citation and leaves it out of the rating calculation.

The check stops provenance that travels as data: a table column of source pages, an input that holds a document, or a flag that says someone verified the rates. A caller would have to supply such a value on every request, and a reviewer would find the evidence in two places.

**Example**

The table `HazardRate` declares a `source_page` column beside its rate.

```rsl theme={"languages":{"custom":["languages/rsl.tmLanguage.json"]}}
    HazardRate [cite: manual:p3] :
        table dims (hazard: Hazard) -> {
            rate: Rate,
            source_page: Num {precision: int}
        }
}
```

```csv theme={"languages":{"custom":["languages/rsl.tmLanguage.json"]}}
hazard,rate,source_page
low,2,3
high,3.5,3
```

```sh theme={"languages":{"custom":["languages/rsl.tmLanguage.json"]}}
rslc check bad/rater.rsl
```

```text theme={"languages":{"custom":["languages/rsl.tmLanguage.json"]}}
FAIL bad/rater.rsl (strict)
error: E-PROVENANCE-RUNTIME bad/rater.rsl:27:13: table 'HazardRate' column 'source_page' carries provenance at runtime. Delete the column and its CSV data, and cite the table: HazardRate [cite: source:region] : (…). For rows from another region, declare that citation on the table too and name it in the optional 'cite' column.
```

**Fix**

Delete the column from the table and from its CSV file. The table's citation already records the page.

When rows come from different pages, declare each citation on the table and name each row's citation in a CSV column headed `cite`.

```rsl theme={"languages":{"custom":["languages/rsl.tmLanguage.json"]}}
    HazardRate [cite: manual:p3] :
        table dims (hazard: Hazard) -> {
            rate: Rate
        }
}
```

```csv theme={"languages":{"custom":["languages/rsl.tmLanguage.json"]}}
hazard,rate
low,2
high,3.5
```

**Other causes**

* A table's CSV file has a column headed `source_page`, `source_part`, `__cite` or a name that starts with `_source`.
* An input has the type `Source`.
* An enum lists artifact IDs as members; declare each document in `Sources`.
* A `Bool` input whose name ends in `_verified`, `_supplied` or `_confirmed` stays unread by every calculation and rule.

> [accordion] Complete files
>
> ```rsl bad/rater.rsl theme={"languages":{"custom":["languages/rsl.tmLanguage.json"]}}
> spec {
>     rsl: "0.4.1",
>     carrier: "Example Mutual",
>     state: AZ,
>     product: "Staffing Liability",
>     effective_date: 2026-01-01
> }
>
> Sources = {
>     manual: Source = {
>         artifact: artifact("00000000-0000-4000-8000-000000000000"),
>         kind: pdf
>     }
> }
>
> Types = {
>     Hazard = {
>         low,
>         high
>     }
> }
>
> Tables = {
>     HazardRate [cite: manual:p3] :
>         table dims (hazard: Hazard) -> {
>             rate: Rate,
>             source_page: Num {precision: int}
>         }
> }
>
> Records = {
>     Policy = {
>         inputs {
>             payroll: Num {precision: int} where self in [0, 100000000],
>             hazard: Hazard
>         },
>         step rating {
>             rate: Rate = lookup!(HazardRate, self.hazard).rate,
>             premium: Premium [cite: manual:p3] = round(self.payroll / 1000 * self.rate, 2, half_up)
>         }
>     }
> }
>
> RatingOutcomes = {
>     premium: Policy.premium
> }
> ```
>
> ```csv bad/tables/HazardRate.csv theme={"languages":{"custom":["languages/rsl.tmLanguage.json"]}}
> hazard,rate,source_page
> low,2,3
> high,3.5,3
> ```
>
> ```rsl good/rater.rsl theme={"languages":{"custom":["languages/rsl.tmLanguage.json"]}}
> spec {
>     rsl: "0.4.1",
>     carrier: "Example Mutual",
>     state: AZ,
>     product: "Staffing Liability",
>     effective_date: 2026-01-01
> }
>
> Sources = {
>     manual: Source = {
>         artifact: artifact("00000000-0000-4000-8000-000000000000"),
>         kind: pdf
>     }
> }
>
> Types = {
>     Hazard = {
>         low,
>         high
>     }
> }
>
> Tables = {
>     HazardRate [cite: manual:p3] :
>         table dims (hazard: Hazard) -> {
>             rate: Rate
>         }
> }
>
> Records = {
>     Policy = {
>         inputs {
>             payroll: Num {precision: int} where self in [0, 100000000],
>             hazard: Hazard
>         },
>         step rating {
>             rate: Rate = lookup!(HazardRate, self.hazard).rate,
>             premium: Premium [cite: manual:p3] = round(self.payroll / 1000 * self.rate, 2, half_up)
>         }
>     }
> }
>
> RatingOutcomes = {
>     premium: Policy.premium
> }
> ```
>
> ```csv good/tables/HazardRate.csv theme={"languages":{"custom":["languages/rsl.tmLanguage.json"]}}
> hazard,rate
> low,2
> high,3.5
> ```

## E-PROVENANCE-COMMENT

**Evidence belongs in a citation.**

A comment that starts with `source:`, `sources:` or `readiness:` records evidence in a place the compiler leaves unread. The check asks for that evidence as a citation on the declaration the comment describes: `[cite: manual:p3]`.

The compiler checks a citation against `Sources`, and tools open the document at the cited page. A comment drifts as the rater changes around it. Comments that explain a calculation in other words pass the check.

**Example**

A comment above the constant repeats where the rate comes from.

```rsl theme={"languages":{"custom":["languages/rsl.tmLanguage.json"]}}
Constants = {
    # source: rate manual, page 3
    rate_per_1000 [cite: manual:p3] = 2
}
```

```sh theme={"languages":{"custom":["languages/rsl.tmLanguage.json"]}}
rslc check bad/rater.rsl
```

```text theme={"languages":{"custom":["languages/rsl.tmLanguage.json"]}}
FAIL bad/rater.rsl (strict)
error: E-PROVENANCE-COMMENT bad/rater.rsl:17:5: comment '# source: …' records evidence that the compiler cannot check. Cite the declaration instead with [cite: source:region], or delete the comment.
  = because: evidence lives only in `[cite: source:region]`, which the compiler checks; a comment is a second, unchecked spelling of it
  = help: put the region in a citation on the declaration the comment describes, `name: T [cite: <source>:<region>] = …`, then delete the comment
  = applicability: placeholders
```

**Fix**

Delete the comment; the constant's citation already names the page. Where the declaration lacks a citation, move the page from the comment into `[cite: …]` first.

```rsl theme={"languages":{"custom":["languages/rsl.tmLanguage.json"]}}
Constants = {
    rate_per_1000 [cite: manual:p3] = 2
}
```

> [accordion] Complete files
>
> ```rsl bad/rater.rsl theme={"languages":{"custom":["languages/rsl.tmLanguage.json"]}}
> spec {
>     rsl: "0.4.1",
>     carrier: "Example Mutual",
>     state: AZ,
>     product: "Staffing Liability",
>     effective_date: 2026-01-01
> }
>
> Sources = {
>     manual: Source = {
>         artifact: artifact("00000000-0000-4000-8000-000000000000"),
>         kind: pdf
>     }
> }
>
> Constants = {
>     # source: rate manual, page 3
>     rate_per_1000 [cite: manual:p3] = 2
> }
>
> Records = {
>     Policy = {
>         inputs {
>             payroll: Num {precision: int} where self in [0, 100000000]
>         },
>         step rating {
>             premium: Premium [cite: manual:p3] = round(self.payroll / 1000 * rate_per_1000, 2, half_up)
>         }
>     }
> }
>
> RatingOutcomes = {
>     premium: Policy.premium
> }
> ```
>
> ```rsl good/rater.rsl theme={"languages":{"custom":["languages/rsl.tmLanguage.json"]}}
> spec {
>     rsl: "0.4.1",
>     carrier: "Example Mutual",
>     state: AZ,
>     product: "Staffing Liability",
>     effective_date: 2026-01-01
> }
>
> Sources = {
>     manual: Source = {
>         artifact: artifact("00000000-0000-4000-8000-000000000000"),
>         kind: pdf
>     }
> }
>
> Constants = {
>     rate_per_1000 [cite: manual:p3] = 2
> }
>
> Records = {
>     Policy = {
>         inputs {
>             payroll: Num {precision: int} where self in [0, 100000000]
>         },
>         step rating {
>             premium: Premium [cite: manual:p3] = round(self.payroll / 1000 * rate_per_1000, 2, half_up)
>         }
>     }
> }
>
> RatingOutcomes = {
>     premium: Policy.premium
> }
> ```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.