# SaC Workflow

SaC is the primary authoring path for workbook behavior. Workbook state is maintained as ordered Facade Migration Pack source against one explicit `.univer` target container and a hidden authoring sidecar beside it. On POSIX, `Budget.univer` resolves to `.Budget.univer.sac/`; on Windows, `Budget.univer.sac/` is used with the hidden filesystem attribute.

The target file path identifies the local CLI target. Unit-specific work should first discover the
target's top-level units, including `localUnitId`, unit type, name, and capability status. A sheet
name or A1 range is a coordinate inside a spreadsheet unit, not a replacement for the target path or
the unit's `localUnitId`.

Mutating SaC commands are serialized per target univerfile. `materialize`, `migration create`, `apply`, and `rollback` fail fast when another SaC mutation holds the storage-backed target lock. `materialize`, `apply`, `rollback`, and `verify` also require a clean target: uncommitted local mutations must be committed or restored before SaC uses the target state as evidence.

## Local Path

Materialize the current target state into the sidecar:

```bash
univer sac materialize ./Budget.univer
```

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

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

Write or update `assertions/**/*.assertions.ts` before claiming a non-trivial migration is complete; in practice, write assertions for workbook-visible final-state outcomes such as sheet existence, used ranges, representative values, formulas, formatting, and resources.

Apply the sidecar source chain back to the target univerfile:

```bash
univer sac apply ./Budget.univer
```

Each successful apply records target-owned SaC active state and persists the pack's runtime action batch per affected unit: created units are added, deleted units are soft-deleted, and mutated units receive local changesets. To undo the newest applied SaC pack:

```bash
univer sac rollback ./Budget.univer
```

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

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

Read the JSON summary and its `reportPath`; do not construct the report path by appending `.sac`. If verification fails, inspect the report, repair migration source or the relevant `*.assertions.ts` entrypoint, then apply or verify again. Missing global assertions are a setup error and are not completion evidence.

## Drift Recovery

`SAC_UNIT_STATE_DRIFT` is a hard stop. It means the current committed workbook unit state differs from the sidecar active applied state, so SaC source would be applied against stale workbook state. Do not bypass the guard.

Read the diagnostic before choosing recovery:

- Clean target and no un-applied packs: run `univer sac materialize ./Budget.univer`, then retry `univer sac apply ./Budget.univer`.
- Dirty target: commit or restore uncommitted local mutations first. Do not run materialize as the immediate next command.
- Un-applied packs detected: review, apply, or remove them before materialize. If you intentionally need to re-baseline while preserving drafts, run `univer sac materialize ./Budget.univer --preserve-drafts`, then review the recovery manifest and reattach or recreate the preserved packs against the new baseline.
- Target state moved behind the active applied state: reconcile reset, rollback, or materialize state before applying the current chain head again.

SaC README, installed managed `univer inspect --tool`, sidecar scratch `univer inspect --script`, and
exported handoff files are supplemental inspection surfaces for workbook-visible state and handoff
review. They return evidence facts; durable decisions belong in success criteria, plans, assertions,
or migration source. They are not the primary SaC completion gate when assertions exist.

## Project Shape

- `Budget.univer` is the durable target univerfile.
- The sidecar README and AGENTS.md describe the target container, unit discovery expectations, and
  the boundary between readonly evidence and durable source.
- Unit inventory guidance identifies discovered `localUnitId`, unit type, name, and capability
  status through public command output, sidecar docs, or installed managed inspect tools when available.
- `.Budget.univer.sac/success-criteria/` records durable pass conditions.
- `.Budget.univer.sac/plans/` records workbook behavior decisions before assertions and migration
  source.
- `.Budget.univer.sac/assertions/` contains the workbook-level final-state assertion entrypoint.
- `.Budget.univer.sac/migrations/` contains timestamped migration pack directories on POSIX.
- `.Budget.univer.sac/inspect/` contains installed managed inspect tool guidance and params examples.
- `.Budget.univer.sac/inspect-scripts/` is scratch space for short-lived readonly `.js` probes.
- `.Budget.univer.sac/materialize-recovery/` contains materialize staging, source replacement recovery, and explicit draft-preservation manifests.
- `.Budget.univer.sac/types/` is managed by the current CLI and exposes the curated Facade d.ts view.
- `.Budget.univer.sac/runs/` is reserved for verification reports and sandbox copies.
- Applied migration state belongs to `Budget.univer`, not the hidden sidecar.
- The active SaC mutation lock also belongs to `Budget.univer` storage and is not a sidecar file.
- Once a migration pack is recorded in the target active applied chain, treat that pack's source files and referenced data assets as immutable while active; create a follow-up pack for later changes or roll back the current tail pack first.
- The sidecar does not require `package.json`, `tsconfig.json`, or `node_modules`; apply prepares the shared CLI-owned toolchain as needed.

## Related Help

- `univer help sac authoring`
- `univer help sac facade-api`
- `univer help sac applied-state`
- `univer help sac assertions`
