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 -NoProfile -ExecutionPolicy Bypass -File scripts/compare_1c_saved_state_objects.ps1 `
  -Server <SqlServer> `
  -Database <SqlDatabase> `
  -User <SqlUser> `
  -Password <SqlPassword> `
  -Output <SavedStateObjectComparisonJson>

Output schema:

onec_saved_state_object_comparison.v1

Detail command:

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:

onec_saved_state_object_detail.v1

Report command:

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:

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 -NoProfile -ExecutionPolicy Bypass -File scripts/watch_1c_saved_state_once.ps1 `
  -Server <SqlServer> `
  -Database <SqlDatabase> `
  -User <SqlUser> `
  -Password <SqlPassword> `
  -OutputRoot <SavedStateWatchRoot>

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

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.

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

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.

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

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:

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

Check command:

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

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

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

Report-to-report delta:

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.

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

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

Object change lookup:

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

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.