llm/docs/1c-saved-state-object-compare.md

# 1C Saved State Object Compare

Status: draft, read-only.

This adapter view compares saved-but-not-applied SQL state with the active
configuration state and returns the result in 1C configurator terms.

Command:

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/compare_1c_saved_state_objects.ps1 `
  -Server <SqlServer> `
  -Database <SqlDatabase> `
  -User <SqlUser> `
  -Password <SqlPassword> `
  -Output <SavedStateObjectComparisonJson>
```

Output schema:

```text
onec_saved_state_object_comparison.v1
```

Detail command:

```powershell
python scripts/analyze_1c_saved_state_object_details.py `
  --comparison <SavedStateObjectComparisonJson> `
  --config-save-dir <ConfigSaveExportDir> `
  --config-dir <ConfigActiveExportDir> `
  --config-cas-save-dir <ConfigCASSaveExportDir> `
  --config-cas-dir <ConfigCASActiveExportDir> `
  --extension-manifest-summary <ExtensionManifestSummaryJson> `
  --config-cas-all-dir <ConfigCASAllDir> `
  --output <SavedStateObjectDetailJson>
```

Detail output schema:

```text
onec_saved_state_object_detail.v1
```

Report command:

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/build_1c_saved_state_object_report.ps1 `
  -Server <SqlServer> `
  -Database <SqlDatabase> `
  -User <SqlUser> `
  -Password <SqlPassword> `
  -OutputDir <SavedStateReportDir>
```

Report output schema:

```text
onec_saved_state_object_report.v1
```

The report command is the normal agent entry point. It runs the object
comparison, exports only the required active/saved SQL payload evidence, and
runs detail analysis into one output directory. By default it also writes
`saved-state-object-report.md`; use `-SkipMarkdown` when only machine-readable
JSON is needed. The JSON report includes `agent_summary`, a compact machine
view with changed 1C object names, changed payload parts, payload roles,
active-missing part counts, and short added/removed semantic term hints.

Watch once command:

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/watch_1c_saved_state_once.ps1 `
  -Server <SqlServer> `
  -Database <SqlDatabase> `
  -User <SqlUser> `
  -Password <SqlPassword> `
  -OutputRoot <SavedStateWatchRoot>
```

```powershell
python scripts/list_1c_saved_state_watch_runs.py `
  --root <SavedStateWatchRoot> `
  --limit <N> `
  --only-with-delta `
  --output <SavedStateWatchRunListJson>
```

```powershell
python scripts/get_1c_saved_state_latest_watch_run.py `
  --root <SavedStateWatchRoot> `
  --require-delta `
  --output <SavedStateLatestWatchRunJson>
```

When `--output` is provided, latest watch lookup writes Markdown next to the
JSON by default. Use `--skip-markdown` to disable this or `--markdown-output`
to set an explicit Markdown path.

```powershell
python scripts/check_1c_saved_state_latest_watch_run.py `
  --latest <SavedStateLatestWatchRunJson> `
  --output <SavedStateLatestWatchRunCheckJson>
```

```powershell
python scripts/render_1c_saved_state_latest_watch_run_markdown.py `
  --latest <SavedStateLatestWatchRunJson> `
  --output <SavedStateLatestWatchRunMarkdown>
```

When `--output` is provided, the watch-run list command writes Markdown next to
the JSON by default. Use `--skip-markdown` to disable this or
`--markdown-output` to set an explicit Markdown path. It also writes
`*-check.json` and runs a contract check by default. Use `--skip-check` to
disable this.

```powershell
python scripts/check_1c_saved_state_watch_run_list.py `
  --list <SavedStateWatchRunListJson> `
  --output <SavedStateWatchRunListCheckJson>
```

```powershell
python scripts/render_1c_saved_state_watch_run_list_markdown.py `
  --list <SavedStateWatchRunListJson> `
  --output <SavedStateWatchRunListMarkdown>
```

The watch command creates a timestamped report directory. If a previous
timestamped report exists under the same root, it also writes a delta from the
previous observation to the new observation. By default it writes
`saved-state-watch-run.md`; use `-SkipMarkdown` to disable Markdown rendering.

Markdown command:

```powershell
python scripts/render_1c_saved_state_object_report_markdown.py `
  --report <SavedStateObjectReportJson> `
  --output <SavedStateObjectReportMarkdown>
```

Check command:

```powershell
python scripts/check_1c_saved_state_object_report.py `
  --report <SavedStateObjectReportJson> `
  --output <SavedStateObjectReportCheckJson>
```

```powershell
python scripts/check_1c_saved_state_watch_once.py `
  --manifest <SavedStateWatchRunJson> `
  --output <SavedStateWatchRunCheckJson>
```

```powershell
python scripts/render_1c_saved_state_watch_once_markdown.py `
  --manifest <SavedStateWatchRunJson> `
  --output <SavedStateWatchRunMarkdown>
```

Report-to-report delta:

```powershell
python scripts/compare_1c_saved_state_object_reports.py `
  --before <PreviousSavedStateObjectReportJson> `
  --after <CurrentSavedStateObjectReportJson> `
  --output <SavedStateObjectReportDeltaJson>
```

When `--output` is provided, the delta command writes Markdown next to the JSON
by default. Use `--skip-markdown` to disable this or `--markdown-output` to set
an explicit Markdown path. It also writes `*-check.json` and runs the delta
contract check by default. Use `--skip-check` to disable this.

```powershell
python scripts/check_1c_saved_state_object_report_delta.py `
  --delta <SavedStateObjectReportDeltaJson> `
  --output <SavedStateObjectReportDeltaCheckJson>
```

```powershell
python scripts/render_1c_saved_state_object_report_delta_markdown.py `
  --delta <SavedStateObjectReportDeltaJson> `
  --output <SavedStateObjectReportDeltaMarkdown>
```

Object change lookup:

```powershell
python scripts/list_1c_saved_state_object_changes.py `
  --report <SavedStateObjectReportJson> `
  --payload-role <PayloadRole> `
  --active-missing true `
  --output <SavedStateObjectChangeListJson>
```

```powershell
python scripts/get_1c_saved_state_object_change.py `
  --report <SavedStateObjectReportJson> `
  --name <ConfiguratorObjectName> `
  --output <SavedStateObjectChangeJson>
```

Use `--name-b64` instead of `--name` when a shell cannot pass Unicode safely.

Rules:

- read-only SQL access only;
- compare `ConfigSave` with `Config`;
- compare `ConfigCASSave` with `ConfigCAS`;
- expose public changes as 1C objects, for example
  `ОбщийМодуль.HttpBridgeКлиент`;
- keep `FileName`, byte sizes, and hashes under `storage` evidence;
- keep `root`, `versions`, and `configinfo` under `system_changes`.
- optional detail analysis can show text deltas, added/removed words, and
  saved form/module string samples inside each changed 1C object.
- when extension manifest summary and active `ConfigCAS` export are provided,
  detail analysis resolves `ConfigCASSave` object parts to active CAS keys and
  compares saved extension payloads with active extension payloads.
- Markdown rendering is read-only and should keep 1C configurator object names
  first, with SQL file names only as storage evidence.
- Agents should read `agent_summary` first, then open `detail` only when a
  concrete changed payload needs inspection.
- Detail parts include `payload_role` hints such as `bsl_module_text`,
  `form_descriptor`, `form_body`, `primary_payload`, or `metadata_payload`.
- Detail payloads may include `semantic_hints.added_terms` and
  `semantic_hints.removed_terms`, filtered from raw word diffs to remove
  technical/base64-like tokens.
- The report command runs the check command as a final contract gate and writes
  `saved-state-object-report-check.json`.
- Report-to-report delta compares two observations by 1C object names and
  stable payload-part fingerprints. Use it when the user continues editing and
  asks what changed since the previous check.
- Delta reports should pass `onec_saved_state_object_report_delta_check.v1`
  before being used as reliable agent input.
- Watch manifests should pass `onec_saved_state_watch_once_check.v1`; they
  verify linked report/delta checks and summary counts.
- Watch run lists expose the latest observation, linked artifact paths, check
  statuses, and delta counts without rereading SQL.
- Watch run lists should pass `onec_saved_state_watch_run_list_check.v1`
  before being used as reliable agent input.
- Latest watch lookup returns the newest matching run, or `found=false` when no
  run satisfies `--require-delta` or `--require-changed`. It writes a check JSON
  by default when `--output` is used; use `--skip-check` to disable this.
- Object change lookup returns `matched`, `not_found`, or `ambiguous`; it must
  return candidates instead of guessing when multiple objects match.
- Object change list supports compact filters by layer, kind, extension,
  payload role, text diff, and active-missing state.