# 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, migrations/ is the source of truth and the .univer target artifact is generated by replaying migration source.

## Local Happy Path

Enable the experimental command surface first:

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

Create an empty SaC project:

```bash
univer sac init ./model
```

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

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

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 default `.univer` artifact from `sac.config.ts`:

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

For an empty project, `univer sac init ./model` creates a generated workspace. Its result workbook is `./model/artifacts/model.univer`. Keep `inspect`, `pipe out`, and `view` pointed at that same artifact.

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

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

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

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

Read the JSON summary and the referenced `.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

- `sac.config.ts` declares the migration directory, artifact mode, and default artifact path.
- `types/` is managed by the current CLI and exposes the curated Facade d.ts view.
- `migrations/` contains timestamped migration pack directories.
- The workspace does not contain `package.json`, `tsconfig.json`, or `node_modules`; apply prepares the shared CLI-owned toolchain as needed.
- Empty init uses generated mode: `artifacts/<workspace-name>.univer` is the generated workbook result and should stay ignored by git unless a workflow explicitly chooses otherwise.
- `.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`
