Initial SQL-only 1C adapter baseline

2026-07-22 03:03:47 +03:00
commit e2503b77e7
545 changed files with 184711 additions and 0 deletions
@@ -0,0 +1,250 @@
+# 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.