# SaC Materialize

Materialize creates or refreshes the hidden authoring sidecar from a target univerfile. On POSIX, `Budget.univer` resolves to `.Budget.univer.sac/`; on Windows, `Budget.univer.sac/` is used with the hidden filesystem attribute. SaC consumes provider-generated checkpoint source as a new authoring baseline for apply and verify.

Materialize runs under the target SaC mutation lock while handing off to the provider and recording the baseline. The lock state is stored in the target univerfile storage. The lock serializes authoring workflows for the same univerfile; it is not a replacement for storage transactions.

Materialize requires a clean target. If the target univerfile has uncommitted local mutations, materialize fails before staging source. Commit those edits into local changesets or restore them first.

## When Materialize Helps

Use materialize when adopting an existing univerfile into SaC source or when the current target state is clearer than noisy migration history. The goal is to establish a full checkpoint migration source chain for the target univerfile.

Materialize does not extract mutation groups. It produces provider-owned checkpoint source that later `univer sac apply` and `univer sac verify` can validate through the normal sidecar source and target-owned active applied state.

## Checkpoint Semantics

A successful materialize prepares `.Budget.univer.sac/migrations/` on POSIX with one generated checkpoint pack and replaces the target-owned active applied chain with one matching materialize baseline entry.

The checkpoint is generated from committed workbook state: init data plus synced changesets plus local changesets replayed through the runtime-visible workbook path. Uncommitted local mutations are excluded and rejected by the clean-target preflight.

When materialize replaces existing active `migrations/`, it archives the previous active migration source under `.Budget.univer.sac/archives/materialize/<archive-id>/migrations/` and writes `materialize-archive-manifest.json`. This archive is for review and audit only; it is not active migration source and does not participate in apply, verify, source hashing, or migration tail selection. Global `assertions/` are preserved and are not archived or regenerated by materialize.

Materialize is also the SaC boundary where storage-owned garbage collection may clean soft-deleted unit data that is no longer needed by the new baseline. Normal `apply` and `rollback` keep soft-deleted unit data available for rollback.

Materialize protects draft source. If the current sidecar contains un-applied migration packs after the active applied chain tail, materialize fails before staging or replacing source. Review, apply, or remove those packs first. If you intentionally need to re-baseline while keeping drafts for later review, use:

```bash
univer sac materialize ./Budget.univer --preserve-drafts
```

`--preserve-drafts` moves un-applied packs under `.Budget.univer.sac/materialize-recovery/<recovery-id>/` and writes `draft-recovery-manifest.json` with original paths, classifications, old active state digest, and new baseline information. Preserved packs are not part of the active source chain until you review and reattach or recreate them against the new baseline.

`--force` is a provider-owned mode for replacing active sidecar source history for the same target univerfile. It does not bypass legacy visible sidecar conflicts, materialization gaps, storage locks, transaction recovery, unsupported unit types, or path safety.

A lock conflict means another SaC mutation is active for the same target or a previous process crashed before releasing its lock. Retry after the active command finishes; use the storage-owned recovery path only after confirming no SaC writer is active.

Materialize archive state is stored in the resolved hidden sidecar `archives/materialize/` directory. Draft recovery state is stored in `materialize-recovery/`. Verification reports and sandbox artifacts belong in `runs/` and must not be removed by archive or recovery cleanup.

## Related Help

- `univer help sac workflow`
- `univer help sac applied-state`
