# SaC Workflow

Use SaC when the workbook should be maintained as a source project with ordered Facade Migration Packs. Use `univer run` for one-off workbook-local edits. In SaC, `project/migrations/` is the source of truth and the `.univer` package is updated in place.

## Local Happy Path

Enable the experimental command surface first:

```bash
univer config set experimental.sac true
```

Create an empty SaC project:

```bash
univer new ./model.univer --with-project
```

Create one migration, then edit the generated source before applying it:

```bash
univer sac migration create "Add Revenue Model" ./model.univer
```

Write `assertions.ts` beside the migration `pack.ts` before claiming a non-trivial migration is complete. The assertions should describe workbook-visible outcomes such as sheet existence, used ranges, representative values, and formulas.

Apply the source chain to the same project workbook package:

```bash
univer sac apply ./model.univer
```

For an empty project, `univer new ./model.univer --with-project` creates `project/univer.config.ts` and `project/migrations/` inside the package. Keep `inspect`, `pipe out`, and `view` pointed at `./model.univer`.

Each successful apply creates one workbook local changeset per migration pack. To undo the newest applied migration, use:

```bash
univer reset ./model.univer --hard HEAD~1
```

Verify workbook-visible state after apply with the assertion gate:

```bash
univer sac verify ./model.univer --json
```

Read the JSON summary and the referenced `internal/sac/runs/<run-id>/verify-report.json`. If verification fails, inspect the report, repair migration source or assertions, then apply or verify again. Repeat the loop one migration at a time: create or edit migration, write assertions, apply, verify, repair, and repeat. Keep each migration focused on one durable workbook intent.

`univer inspect`, `univer pipe out`, and `univer view` are supplemental inspection tools for understanding workbook-visible state and handoff review. They are not the primary SaC Spreadsheet TDD completion gate when assertions exist.

## Project Shape

- `project/univer.config.ts` declares `spreadsheet.source.migrationsDir`.
- `project/types/` is managed by the current CLI and exposes the curated Facade d.ts view.
- `project/migrations/` contains timestamped migration pack directories.
- The project does not contain `package.json`, `tsconfig.json`, or `node_modules`; apply prepares the shared CLI-owned toolchain as needed.
- `internal/sac/runs/` is reserved for agent runner evidence and is separate from generated workbook results.

## Related Help

- `univer help sac authoring`
- `univer help sac facade-api`
- `univer help sac apply-ledger`
- `univer help sac assertions`
