# SaC Apply And Ledger

`univer sac apply` validates the source chain, validates the target ledger, bundles one pending pack, applies it to an isolated working artifact, commits it, and then moves to the next pack. The commit model is pack by pack.

By default, every successfully applied pack is also committed through workbook versioning as one local changeset. If the newest applied pack is wrong, roll back the target workbook with `univer reset <target> --hard HEAD~1`, inspect, then fix the migration source before applying again.

Use `univer sac apply <workspace> --no-commit` only for compatibility or recovery workflows where SaC should write ledger metadata without creating workbook local changesets.

## Target Lifecycle

When no `--target` is provided, the target path comes from `sac.config.ts` and must match the workspace artifact mode.

Generated workspaces are created by `univer sac init ./model`. They use `artifacts.mode: "generated"` and must write the managed result to `artifacts/<workspace-name>.univer`, for example `./model/artifacts/model.univer`.

Adopted workspaces are created by `univer sac init ./model --from ./existing.univer`. They use `artifacts.mode: "adopted"` and must continue updating the original artifact recorded in `artifacts.defaultWorkbook`.

If `--target` is provided, it must still resolve to the target required by the workspace artifact mode. Do not write SaC result workbooks to `dist/`, the workspace root, or ad hoc output names.

Generated workspaces are created by `univer sac init ./model`. They use `artifacts.mode: "generated"` and must write the managed result to `artifacts/<workspace-name>.univer`, for example `./model/artifacts/model.univer`.

Adopted workspaces are created by `univer sac init ./model --from ./existing.univer`. They use `artifacts.mode: "adopted"` and must continue updating the original artifact recorded in `artifacts.defaultWorkbook`.

If `--target` is provided, it must still resolve to the target required by the workspace artifact mode. Do not write SaC result workbooks to `dist/`, the workspace root, or ad hoc output names.

If the target `.univer` artifact does not exist, apply starts from an empty logical workbook and creates the artifact. The resulting workbook should contain only sheets declared by migration source.

If the target exists, it must be managed by SaC and contain the artifact-local ledger in package manifest metadata.

The ledger is artifact-local to the required result artifact. Apply rejects any default target or `--target` path that does not match the workspace artifact mode.

## Ledger Contract

Each applied pack writes a ledger entry with pack id, source hash, previous pack pointer, artifact content hash, runner metadata, timestamp, and origin.

New default apply entries also include `workbookCommit` with the local changeset `sid`, `reqId`, commit message, and mutation count. Entries created with `--no-commit` omit `workbookCommit` and report the workbook commit as skipped in command output.

Apply fails before executing pending source when:

- the target exists but is unmanaged
- the ledger is malformed
- the target ledger is ahead of source
- an already-applied pack id has a different source hash
- artifact content has drifted since the ledger head
- automatic workbook commit finds no pending workbook mutations
- automatic workbook commit returns more than one local changeset for a single pack

If every source pack is already ledgered with matching hashes and the artifact has not drifted, apply succeeds as an up to date no-op.

## Verification

Apply success is not the Spreadsheet TDD completion gate. For assertion-backed SaC work, run `univer sac verify <workspace> --json` after apply and read the referenced `.sac/runs/<run-id>/verify-report.json`.

Use `inspect`, `pipe out`, and `view` as supplemental workbook-visible checks when they help explain or hand off the result:

```bash
univer sac verify <workspace> --json
univer inspect workbook ./model/artifacts/model.univer
univer pipe out ./model/artifacts/model.univer --range "Revenue!A1:C4" --format tsv
univer view ./model/artifacts/model.univer
```

Do not treat successful command output as the only validation for a non-trivial workbook change.
