# SaC Assertions

Use `assertions.ts` to express the workbook-visible contract for a Facade Migration Pack. `univer sac verify` loads each applied pack's assertion source, copies the target workbook into a sandbox under `internal/sac/runs/<run-id>/`, reads workbook state through the Facade API, and writes `internal/sac/runs/<run-id>/verify-report.json`.

`univer sac verify` does not mutate the canonical target workbook.

## Assertion File

Place `assertions.ts` beside the pack's `pack.ts`:

```text
migrations/
  20260526090000-add-revenue-model/
    pack.ts
    assertions.ts
```

Import the helper from the CLI-owned virtual module:

```ts
import { defineAssertions } from "univer:sac/assertions";

export default defineAssertions(({ sheet, range }) => {
  sheet("Revenue").exists();
  sheet("Revenue").usedRange("A1:C4");
  range("Revenue!A1:C2").values([
    ["Region", "Q1", "Q2"],
    ["West", 1200, 1400]
  ]);
  range("Revenue!C4").formula("=SUM(C2:C3)");
});
```

Supported helpers:

- `sheet(name).exists()` verifies that a sheet exists.
- `sheet(name).usedRange(a1)` verifies the used range reported for that sheet.
- `range(a1).values(matrix)` verifies visible cell values for a sheet-qualified A1 range.
- `range(a1).formula(formula)` verifies one formula cell.
- `range(a1).formulas(matrix)` verifies a formula matrix.

Keep assertions deterministic and representative. Prefer stable workbook-visible facts over broad snapshots. Do not inspect `.univer` or `.unv` package internals as assertion evidence.

## Verify

Run apply before verification when a migration is not yet applied:

```bash
univer sac apply <package.univer>
univer sac verify <package.univer> --json
```

The JSON summary includes status, checked and skipped pack counts, assertion counts, failure summaries, and the report path. Read the referenced report for detailed failure evidence:

```text
internal/sac/runs/<run-id>/verify-report.json
```

Status interpretation:

- `passed`: every checked assertion passed. Relevant skipped packs should still be reviewed before handoff.
- `failed`: at least one assertion ran and observed workbook-visible state that did not match the expected contract.
- `error`: verification setup failed before a reliable assertion result, such as config, target, source validation, bundling, or runtime setup.

Skipped packs are packs without assertion source or packs outside the verified applied set. A pack being authored for Spreadsheet TDD should not be skipped unless the task explicitly excludes assertions.

## Repair Loop

For `failed` reports, inspect each failure for:

- pack id
- assertion kind
- target
- expected value
- actual value
- first difference, when present

Then decide whether the migration source is wrong or the assertion expectation is wrong. Repair the source or assertion, rerun apply when the applied artifact needs to change, then rerun:

```bash
univer sac verify <package.univer> --json
```

For `error` reports, repair setup first. Do not treat setup errors as proof that workbook behavior is wrong.

Apply success is not a Spreadsheet TDD completion gate. The completion gate is a relevant `univer sac verify <package.univer> --json` run with status `passed`, plus the report path recorded in the handoff.
