# Refresh Strategy (Layer 3)

Date: 2026-03-23  
Status: MVP implementation available (`canonical_layer/refresh.py`)

## 1. Goal

Provide controlled extraction from 1C into canonical store with reproducible runs,
checkpoints, and operational audit trail.

## 2. Refresh modes

### Historical

- bootstrap population of canonical store
- wide scan of selected entity sets
- used to build initial baseline

### Incremental

- regular updates for open periods
- optional date window (`date_from`, `date_to`)
- preferred default daily mode

### Targeted

- selective refresh for one account/document/counterparty context
- optional `target_id` text filter
- used for point recovery and drill-down gaps

## 3. Runtime behavior

1. Resolve entity sets (explicit list or keyword-based discovery).
2. Read records from 1C OData per entity set (bounded by `limit_per_set`).
3. Apply optional date and targeted filters.
4. Map rows to canonical entities and links.
5. Upsert entities/links to canonical store.
6. Update checkpoints for successful sets.
7. Persist run status and metrics into `refresh_runs`.

## 4. Run statuses

- `success`: all requested sets processed
- `partial_success`: at least one set processed, at least one failed
- `failed`: no sets processed successfully

## 5. Execution interfaces

CLI:

- `python scripts/run_refresh.py --mode incremental ...`

PowerShell wrapper:

- `scripts/run_refresh.ps1`

API:

- `POST /refresh/run`
- `GET /refresh/runs`
- `GET /store/stats`

## 6. Safety constraints

- Read-only integration policy stays unchanged.
- No write-back into 1C.
- Local canonical store is internal analytical cache, not source of truth.