acumatica-cli 0.12.1__tar.gz → 0.13.0__tar.gz

{acumatica_cli-0.12.1 → acumatica_cli-0.13.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: acumatica-cli
-Version: 0.12.1
+Version: 0.13.0
 Summary: Acumatica ERP Config-as-Code: tenant provisioning, baseline config, and reference data
 Author: Konstantin Borovik
 Author-email: Konstantin Borovik <kb@lab5.ca>
@@ -89,6 +89,8 @@ acu [--tenant NAME] [--url URL] [--ssh USER@HOST] [--api-version V]
 ├── apply [--dry-run] [FILES...]      push YAML via REST (idempotent PUT upserts)
 ├── diff  [FILES...]                  drift check vs the live tenant (exit 2 on drift)
 ├── run   [--dry-run] [FILES...]      execute transaction scenario YAML (exit 1 on any miss)
+├── snapshot [--out DIR] [--diff] [--assert-unchanged] [--dry-run] [FILES...]
+│                                     capture derived state into state/ (not seed)
 ├── extract [--out DIR] [--only NAME]... [--force] [--dry-run]
 │                                     dump live tenant state as seed YAML (inverse of apply)
 ├── schema [--out DIR]                dump the endpoint's OpenAPI schema (swagger.json)
@@ -103,6 +105,7 @@ acu [--tenant NAME] [--url URL] [--ssh USER@HOST] [--api-version V]
 `apply` and `diff` without FILES prefer `config/<name>/` when any seed child exists under `config/`; otherwise root `bootstrap/`, `baseline/`, `setup/`, then `master/` when present.
 A path like `config/` expands nested seed dirs in that fixed order.
 `run` without FILES defaults to `scenario/`.
+`snapshot` without FILES defaults to `config/snapshot/`; writes go to `state/` (`--out`).
 `acu --completion` emits a completion script for bash, zsh, or fish — source it from your shell profile.
 Run `acu <command> --help` for details on any command.
 
@@ -119,6 +122,8 @@ Your configuration lives in its own git repo.
 | `setup/` / `config/setup/` | one-time actions: financial year, master calendar, open periods |
 | `config/master/` | distribution masters (prefs, warehouse, items, parties); flavor only |
 | `scenario/` | lifecycle txns for `acu run`: once capital, then buy, build stub, sell |
+| `config/snapshot/` | observer views for `acu snapshot` (`inquire:` / `entity:` / `gi:`; not SEED_DIRS) |
+| `state/` | committed derived-state observations (evidence, not seed; money/qty fixed-point) |
 | `target.yaml` | committed verified matrix: `erp` + `default_api` (what, not where) |
 | `.env` | where to apply and who signs in, every key an `ACU_*` variable |
 
@@ -131,6 +136,10 @@ Scenario YAML is different — it describes transactions that flow forward.
 `acu run` executes each step in order (`put`, `action`, `wait`, `get`), captures server-assigned document numbers into `${var}` references for later steps, and checks `expect:` assertions as deltas against a pre-run snapshot, so additive scenarios re-run safely on a warm tenant.
 `once: true` scenarios declare a `present` inquire-absolute gate; when the probe already holds, the CLI prints `skip <path> (once: already present)` and runs neither steps nor expects (Owner Capital does not restack).
 
+`acu snapshot` is the third observation path: it captures live derived state (balances) into `state/` for git review. It is not `extract` (config seed) and not `diff` (desired vs actual config). Packaged golden is trial-balance via contract `inquire:` (`EndingBalance` fixed-point); inventory-summary is not golden this pass. `gi:` stays optional when a GI is V12-verified and **Expose via OData** is on (`params` fail-closed vs `$metadata`). After a cold `acu run scenario/ && acu snapshot`, warm `acu run scenario/10-seed-capital.yaml && acu snapshot --assert-unchanged` is the once-class gate (full scenario re-run is additive and moves cash observations on the TB).
+
+**Migration (path hard-cut):** bare defaults are `config/snapshot/` (views) and `state/` (observations). Root `snapshot/` and `snapshots/` are no longer defaulted — move files or pass explicit path args.
+
 ### Seed `endpoint:` symbols
 
 Dual-served entities (on both Bootstrap and Default) need an explicit `endpoint:` line.

{acumatica_cli-0.12.1 → acumatica_cli-0.13.0}/README.md

@@ -71,6 +71,8 @@ acu [--tenant NAME] [--url URL] [--ssh USER@HOST] [--api-version V]
 ├── apply [--dry-run] [FILES...]      push YAML via REST (idempotent PUT upserts)
 ├── diff  [FILES...]                  drift check vs the live tenant (exit 2 on drift)
 ├── run   [--dry-run] [FILES...]      execute transaction scenario YAML (exit 1 on any miss)
+├── snapshot [--out DIR] [--diff] [--assert-unchanged] [--dry-run] [FILES...]
+│                                     capture derived state into state/ (not seed)
 ├── extract [--out DIR] [--only NAME]... [--force] [--dry-run]
 │                                     dump live tenant state as seed YAML (inverse of apply)
 ├── schema [--out DIR]                dump the endpoint's OpenAPI schema (swagger.json)
@@ -85,6 +87,7 @@ acu [--tenant NAME] [--url URL] [--ssh USER@HOST] [--api-version V]
 `apply` and `diff` without FILES prefer `config/<name>/` when any seed child exists under `config/`; otherwise root `bootstrap/`, `baseline/`, `setup/`, then `master/` when present.
 A path like `config/` expands nested seed dirs in that fixed order.
 `run` without FILES defaults to `scenario/`.
+`snapshot` without FILES defaults to `config/snapshot/`; writes go to `state/` (`--out`).
 `acu --completion` emits a completion script for bash, zsh, or fish — source it from your shell profile.
 Run `acu <command> --help` for details on any command.
 
@@ -101,6 +104,8 @@ Your configuration lives in its own git repo.
 | `setup/` / `config/setup/` | one-time actions: financial year, master calendar, open periods |
 | `config/master/` | distribution masters (prefs, warehouse, items, parties); flavor only |
 | `scenario/` | lifecycle txns for `acu run`: once capital, then buy, build stub, sell |
+| `config/snapshot/` | observer views for `acu snapshot` (`inquire:` / `entity:` / `gi:`; not SEED_DIRS) |
+| `state/` | committed derived-state observations (evidence, not seed; money/qty fixed-point) |
 | `target.yaml` | committed verified matrix: `erp` + `default_api` (what, not where) |
 | `.env` | where to apply and who signs in, every key an `ACU_*` variable |
 
@@ -113,6 +118,10 @@ Scenario YAML is different — it describes transactions that flow forward.
 `acu run` executes each step in order (`put`, `action`, `wait`, `get`), captures server-assigned document numbers into `${var}` references for later steps, and checks `expect:` assertions as deltas against a pre-run snapshot, so additive scenarios re-run safely on a warm tenant.
 `once: true` scenarios declare a `present` inquire-absolute gate; when the probe already holds, the CLI prints `skip <path> (once: already present)` and runs neither steps nor expects (Owner Capital does not restack).
 
+`acu snapshot` is the third observation path: it captures live derived state (balances) into `state/` for git review. It is not `extract` (config seed) and not `diff` (desired vs actual config). Packaged golden is trial-balance via contract `inquire:` (`EndingBalance` fixed-point); inventory-summary is not golden this pass. `gi:` stays optional when a GI is V12-verified and **Expose via OData** is on (`params` fail-closed vs `$metadata`). After a cold `acu run scenario/ && acu snapshot`, warm `acu run scenario/10-seed-capital.yaml && acu snapshot --assert-unchanged` is the once-class gate (full scenario re-run is additive and moves cash observations on the TB).
+
+**Migration (path hard-cut):** bare defaults are `config/snapshot/` (views) and `state/` (observations). Root `snapshot/` and `snapshots/` are no longer defaulted — move files or pass explicit path args.
+
 ### Seed `endpoint:` symbols
 
 Dual-served entities (on both Bootstrap and Default) need an explicit `endpoint:` line.

{acumatica_cli-0.12.1 → acumatica_cli-0.13.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "acumatica-cli"
-version = "0.12.1"
+version = "0.13.0"
 description = "Acumatica ERP Config-as-Code: tenant provisioning, baseline config, and reference data"
 authors = [{ name = "Konstantin Borovik", email = "kb@lab5.ca" }]
 license = "PolyForm-Noncommercial-1.0.0"

{acumatica_cli-0.12.1 → acumatica_cli-0.13.0}/src/acumatica_cli/cli.py

@@ -12,7 +12,7 @@ import click
 import httpx
 from click.shell_completion import get_completion_class
 
-from . import bootstrap, extract, firstlogin, output, run, seed
+from . import bootstrap, extract, firstlogin, output, run, seed, snapshot
 from .client import AcumaticaClient
 from .config import (
     INIT_FLAVORS,
@@ -946,3 +946,79 @@ def _exit_on_drift(inst: Instance, drifts: list[str], files: int) -> None:
             output.data(f"  {line}")
         raise SystemExit(2)
     output.success(f"no drift on {inst.tenant} ({inst.base_url}, {files} file(s))")
+
+
+@cli.command("snapshot")
+@click.argument(
+    "files", nargs=-1, required=False, type=click.Path(exists=True, path_type=Path)
+)
+@click.option(
+    "--out",
+    "out_dir",
+    type=click.Path(file_okay=False, path_type=Path),
+    default=None,
+    help="Observation output directory (default: state/)",
+)
+@click.option(
+    "--diff",
+    "do_diff",
+    is_flag=True,
+    help="Compare live vs disk; write nothing (exit 0 either way)",
+)
+@click.option(
+    "--assert-unchanged",
+    is_flag=True,
+    help="Like --diff, but exit 2 when state moved (idempotence gate)",
+)
+@click.option(
+    "--dry-run",
+    is_flag=True,
+    help="Resolve views and validate sources without HTTP",
+)
+@pass_instance
+def snapshot_cmd(
+    inst: Instance,
+    files: tuple[Path, ...],
+    out_dir: Path | None,
+    do_diff: bool,
+    assert_unchanged: bool,
+    dry_run: bool,
+) -> None:
+    """Capture live derived state into committed observation files.
+
+    FILES are snapshot view YAML files or directories. Omitted, they default
+    to the data repo's config/snapshot/ directory (hard-cut; no root
+    snapshot/ fallback). Default write target is state/ (--out; no
+    snapshots/ fallback). Bare capture writes observations (change is
+    fine). --diff compares live to disk without writing.
+    --assert-unchanged is the warm-run idempotence gate (exit 2 when
+    moved). Never writes seed trees or endpoint: symbols (V32). Exit 0
+    ok, 1 op fail, 2 only under --assert-unchanged when state moved.
+    """
+    assert_target_compatible(inst)
+    if not files:
+        default = data_root() / "config" / "snapshot"
+        if not default.is_dir():
+            raise SystemExit(f"{default}: snapshot directory does not exist")
+        files = (Path(os.path.relpath(default)),)
+    paths = snapshot.expand_view_files(files)
+    views = [snapshot.load_view(path) for path in paths]
+    dest = out_dir if out_dir is not None else Path("state")
+    if dry_run:
+        code = snapshot.run_views(None, views, out_dir=dest, mode="dry")
+    else:
+        mode = "assert" if assert_unchanged else "diff" if do_diff else "write"
+        with AcumaticaClient(inst) as client:
+            code = snapshot.run_views(client, views, out_dir=dest, mode=mode)
+    if code:
+        raise SystemExit(code)
+    if dry_run:
+        return
+    if assert_unchanged:
+        output.success(f"{len(views)} snapshot(s) unchanged on {inst.tenant}")
+    elif do_diff:
+        output.success(f"{len(views)} snapshot(s) compared on {inst.tenant}")
+    else:
+        output.success(
+            f"{len(views)} snapshot(s) written under {dest} on {inst.tenant}"
+        )

{acumatica_cli-0.12.1 → acumatica_cli-0.13.0}/src/acumatica_cli/client.py

@@ -538,3 +538,27 @@ class AcumaticaClient:
         return self._checked(
             self._http.post("/CustomizationApi/publishEnd", json={})
         ).json()
+
+    # -- OData Generic Inquiry (snapshot gi: source; V33) --
+
+    def _odata_gi_root(self) -> str:
+        """24R2+ OData GI service root ``/t/<tenant>/api/odata/gi`` (V33)."""
+        tenant = quote(self.instance.tenant, safe="")
+        return f"/t/{tenant}/api/odata/gi"
+
+    def odata_gi_metadata(self, name: str) -> str:
+        """GET OData GI service ``$metadata`` XML (V33 param validation).
+
+        ``name`` is reserved for future per-GI metadata URLs; the 24R2
+        service exposes one EDMX document at the service root.
+        """
+        del name  # service-level metadata; per-GI filter is validate_gi_params
+        r = self._checked(self._http.get(f"{self._odata_gi_root()}/$metadata"))
+        return r.text
+
+    def odata_gi(self, name: str, params: dict[str, str] | None = None) -> Any:
+        """GET OData GI rows as JSON (requires Expose via OData on the GI)."""
+        gi = quote(name, safe="")
+        return self._checked(
+            self._http.get(f"{self._odata_gi_root()}/{gi}", params=params)
+        ).json()

{acumatica_cli-0.12.1 → acumatica_cli-0.13.0}/src/acumatica_cli/config.py

@@ -58,6 +58,11 @@ INIT_TEMPLATES = (
     ("finance/setup/10-financial-year.yaml", "setup/10-financial-year.yaml"),
     ("finance/setup/20-master-calendar.yaml", "setup/20-master-calendar.yaml"),
     ("finance/setup/30-open-periods.yaml", "setup/30-open-periods.yaml"),
+    # V28/V32: observer views under config/snapshot/ (not SEED_DIRS; lone config/ ok)
+    (
+        "finance/snapshot/10-trial-balance.yaml",
+        "config/snapshot/10-trial-balance.yaml",
+    ),
 )
 
 # Opt-in `--flavor distribution` overlays + extras (V28/V29/T87). Resource
@@ -168,6 +173,10 @@ DISTRIBUTION_TEMPLATES = (
     ),
     ("distribution/scenario/30-build.yaml", "scenario/30-build.yaml"),
     ("distribution/scenario/40-sell.yaml", "scenario/40-sell.yaml"),
+    (
+        "distribution/snapshot/10-trial-balance.yaml",
+        "config/snapshot/10-trial-balance.yaml",
+    ),
     ("distribution/README.md", "README.md"),
 )
 
@@ -237,10 +246,13 @@ class Instance(BaseSettings):
 def templates_for(flavor: str | None) -> tuple[tuple[str, str], ...]:
     """Resolve (resource, dest) pairs for ``config init`` (V28/T87).
 
-    Absent flavor → finance-minimal ``INIT_TEMPLATES`` at root. ``distribution``
-    keeps root meta (``.env``/``.gitignore``/``target.yaml``), rehomes finance
-    seed under ``config/``, then overlays ``DISTRIBUTION_TEMPLATES`` (config/
-    seeds + lifecycle ``scenario/`` + README). Never dual root+config trees.
+    Absent flavor → finance-minimal ``INIT_TEMPLATES`` at root (+ observer
+    ``config/snapshot/``). ``distribution`` keeps root meta
+    (``.env``/``.gitignore``/``target.yaml``), rehomes finance seed under
+    ``config/``, then overlays ``DISTRIBUTION_TEMPLATES`` (config/ seeds +
+    lifecycle ``scenario/`` + ``config/snapshot/`` + README). Never dual
+    root+config seed trees. Paths already under ``config/`` (snapshot
+    views) pass through unchanged.
     """
     if flavor is None:
         return INIT_TEMPLATES
@@ -256,11 +268,14 @@ def templates_for(flavor: str | None) -> tuple[tuple[str, str], ...]:
             by_dest[dest] = res
             order.append(dest)
             continue
-        target = (
-            f"config/{dest}"
-            if any(dest.startswith(p) for p in _SEED_PREFIXES)
-            else dest
-        )
+        if dest.startswith("config/"):
+            target = dest
+        else:
+            target = (
+                f"config/{dest}"
+                if any(dest.startswith(p) for p in _SEED_PREFIXES)
+                else dest
+            )
         if target not in by_dest:
             order.append(target)
         by_dest[target] = res

acumatica_cli-0.13.0/src/acumatica_cli/snapshot.py

@@ -0,0 +1,573 @@
+"""Derived-state observations: config/snapshot/*.yaml views -> state/*.yaml.
+
+`acu snapshot` captures live balances, quantities, and totals as committed
+evidence (SPEC I.cmd / V32). Not a seed inverse: never writes seed trees,
+never carries endpoint: symbols, never participates in apply/diff. Views
+configure the observer under config/snapshot/ (not SEED_DIRS); observations
+are git-diffable flow-style YAML under state/. Bare defaults hard-cut those
+paths (no root snapshot/ or snapshots/ fallback).
+
+View file format (I.data config/snapshot/*):
+
+    name: trial-balance
+    source:
+      inquire: AccountSummaryInquiry  # or: gi: LAB5-… | entity: Account
+      params: { Ledger: ACTUAL, Period: "072026" }  # pinned; not runtime-resolved
+      match: { Account: "30000" }     # optional Results row filter (inquire only)
+    key: [Account]
+    capture: [Description, BegBalance, DebitTotal, CreditTotal, EndingBalance]
+    decimals: 2
+
+Observation file format (I.data state/*):
+
+    view: trial-balance
+    erp: "26.101.0225"
+    rows:
+      - {Account: "10100", BegBalance: "0.00", ...}
+"""
+
+from __future__ import annotations
+
+import xml.etree.ElementTree as ET
+from decimal import Decimal, InvalidOperation
+from pathlib import Path
+from typing import Any, Literal
+
+import yaml
+from pydantic import Field, ValidationError, field_validator, model_validator
+
+from . import output
+from .client import AcumaticaClient, unwrap
+from .models import Model, validation_summary
+from .seed import _norm  # pyright: ignore[reportPrivateUsage]
+
+# Flow-style observation rows: one mapping per line under `rows:`.
+_ROW_PREFIX = "  - "
+
+
+class SourceSpec(Model):
+    """Exactly one of gi: | entity: | inquire:; optional params pinned (V33).
+
+    ``match`` is an optional Results-row filter for ``inquire:`` only
+    (same idiom as ``run`` expect/present). Params for inquire become the
+    PUT body; ``$expand=Results`` is always added by the backend.
+    """
+
+    gi: str | None = None
+    entity: str | None = None
+    inquire: str | None = None
+    params: dict[str, Any] = Field(default_factory=dict)
+    match: dict[str, Any] | None = None
+
+    @model_validator(mode="after")
+    def _one_source(self) -> SourceSpec:
+        kinds = sum(1 for v in (self.gi, self.entity, self.inquire) if v is not None)
+        if kinds != 1:
+            raise ValueError("source: exactly one of gi, entity, inquire")
+        if self.match is not None and self.inquire is None:
+            raise ValueError("source.match requires inquire")
+        return self
+
+    @property
+    def kind(self) -> Literal["gi", "entity", "inquire"]:
+        """Discriminator: ``gi``, ``entity``, or ``inquire`` (exactly one set)."""
+        if self.gi is not None:
+            return "gi"
+        if self.entity is not None:
+            return "entity"
+        return "inquire"
+
+    @property
+    def name(self) -> str:
+        """The GI title, contract entity, or inquiry entity name for this source."""
+        if self.gi is not None:
+            return self.gi
+        if self.entity is not None:
+            return self.entity
+        assert self.inquire is not None
+        return self.inquire
+
+
+class ViewDef(Model):
+    """Observer config for one capture (I.data config/snapshot/*; V32/V33)."""
+
+    name: str
+    source: SourceSpec
+    key: list[str]
+    capture: list[str]
+    decimals: int = 2
+    path: Path = Field(exclude=True, repr=False)
+
+    @field_validator("name")
+    @classmethod
+    def _name_stem(cls, v: str) -> str:
+        v = v.strip()
+        if not v or "/" in v or "\\" in v or v.endswith(".yaml"):
+            raise ValueError(
+                f"name must be a bare output stem (got {v!r}); writes state/<name>.yaml"
+            )
+        return v
+
+    @field_validator("key", "capture")
+    @classmethod
+    def _nonempty_fields(cls, v: list[str]) -> list[str]:
+        if not v:
+            raise ValueError("must be a non-empty list of field names")
+        return list(v)
+
+    @field_validator("decimals")
+    @classmethod
+    def _decimals_nonneg(cls, v: int) -> int:
+        if v < 0:
+            raise ValueError("decimals must be >= 0")
+        return v
+
+
+class Observation(Model):
+    """Committed derived-state capture (I.data state/*; V32)."""
+
+    view: str
+    erp: str
+    rows: list[dict[str, Any]] = Field(default_factory=list)
+
+
+def load_view(path: Path) -> ViewDef:
+    """Parse one snapshot view definition; hard error on invalid shape."""
+    try:
+        raw = yaml.safe_load(path.read_text(encoding="utf-8"))
+    except yaml.YAMLError as exc:
+        raise SystemExit(f"{path}: invalid YAML: {exc}") from exc
+    if not isinstance(raw, dict):
+        raise SystemExit(f"{path}: expected a mapping at the root")
+    try:
+        return ViewDef.model_validate({**raw, "path": path})
+    except ValidationError as exc:
+        raise SystemExit(f"{path}: {validation_summary(exc)}") from exc
+
+
+def load_observation(path: Path) -> Observation:
+    """Parse a committed observation file."""
+    try:
+        raw = yaml.safe_load(path.read_text(encoding="utf-8"))
+    except yaml.YAMLError as exc:
+        raise SystemExit(f"{path}: invalid YAML: {exc}") from exc
+    if not isinstance(raw, dict):
+        raise SystemExit(f"{path}: expected a mapping at the root")
+    try:
+        return Observation.model_validate(raw)
+    except ValidationError as exc:
+        raise SystemExit(f"{path}: {validation_summary(exc)}") from exc
+
+
+def _is_numeric(value: Any) -> bool:
+    """True when value should be fixed-point formatted (money/qty)."""
+    if isinstance(value, bool) or value is None:
+        return False
+    if isinstance(value, (int, float, Decimal)):
+        return True
+    if isinstance(value, str):
+        text = value.strip()
+        if not text:
+            return False
+        try:
+            Decimal(text)
+        except InvalidOperation:
+            return False
+        return True
+    return False
+
+
+def format_key(value: Any) -> str | int | bool | None:
+    """Identity cell for key columns - no money fixed-point (V32).
+
+    Account codes like "10000" and ints stay as-is so sort identity
+    matches the live tenant; only capture columns get decimals formatting.
+    """
+    if value is None:
+        return None
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, int):
+        return value
+    if isinstance(value, float):
+        # key from float is rare; keep lossless string without forcing scale
+        return str(value).rstrip("0").rstrip(".") if "." in str(value) else str(value)
+    if isinstance(value, str):
+        return value
+    return str(value)
+
+
+def format_cell(value: Any, decimals: int) -> str | int | bool | None:
+    """Normalize one capture cell for observation output (V32).
+
+    Numerics become fixed-point strings at ``decimals`` (money/qty). Non-
+    numerics keep a YAML-safe scalar type. Nested values stringify.
+    """
+    if value is None:
+        return None
+    if isinstance(value, bool):
+        return value
+    if _is_numeric(value):
+        quant = Decimal(1).scaleb(-decimals) if decimals else Decimal(1)
+        d = Decimal(str(value)).quantize(quant)
+        # fixed-point string always — never float in the file
+        return f"{d:.{decimals}f}" if decimals else str(int(d))
+    if isinstance(value, (int, str)):
+        return value
+    return str(value)
+
+
+def _key_tuple(row: dict[str, Any], keys: list[str]) -> tuple[Any, ...]:
+    return tuple(row.get(k) for k in keys)
+
+
+def project_rows(
+    live_rows: list[dict[str, Any]], view: ViewDef
+) -> list[dict[str, Any]]:
+    """Allowlist + format + sort by key; key-tuple collision → SystemExit 1 path.
+
+    ``capture:`` is an allowlist (V32): unexpected live fields are dropped.
+    Sort is always by the key tuple so REST/OData order is not contractual.
+    Key columns use ``format_key`` (identity); other capture columns use
+    fixed-point ``format_cell`` so money never lands as float.
+    """
+    projected: list[dict[str, Any]] = []
+    seen: dict[tuple[Any, ...], int] = {}
+    capture_only = [f for f in view.capture if f not in view.key]
+    for i, raw in enumerate(live_rows):
+        row: dict[str, Any] = {}
+        for k in view.key:
+            row[k] = format_key(raw.get(k))
+        for f in capture_only:
+            if f in raw:
+                row[f] = format_cell(raw.get(f), view.decimals)
+        kt = _key_tuple(row, view.key)
+        if kt in seen:
+            raise SystemExit(
+                f"{view.path}: key collision on {dict(zip(view.key, kt, strict=True))} "
+                f"(rows {seen[kt]} and {i}); key must uniquely identify rows (V32)"
+            )
+        seen[kt] = i
+        projected.append(row)
+    projected.sort(key=lambda r: _key_tuple(r, view.key))
+    # observation row: key fields first (view order), then capture alpha
+    ordered: list[dict[str, Any]] = []
+    capture_rest = sorted(capture_only)
+    col_order = [*view.key, *capture_rest]
+    for row in projected:
+        ordered.append({c: row[c] for c in col_order if c in row})
+    return ordered
+
+
+def _yaml_flow_scalar(value: Any) -> str:
+    """Render one scalar inside a flow mapping (ASCII, git-friendly).
+
+    Strings are always double-quoted so codes like ``10100`` and fixed-
+    point money stay strings on ``yaml.safe_load`` round-trip (bare
+    ``10100`` would reparse as int and break key identity).
+    """
+    if value is None:
+        return "null"
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, int) and not isinstance(value, bool):
+        return str(value)
+    text = str(value)
+    escaped = text.replace("\\", "\\\\").replace('"', '\\"')
+    return f'"{escaped}"'
+
+
+def render_observation(obs: Observation) -> str:
+    """Byte-stable observation YAML: one flow-style row per line (V32)."""
+    lines = [
+        f"view: {obs.view}",
+        f"erp: {_yaml_flow_scalar(obs.erp)}",
+        "rows:",
+    ]
+    if not obs.rows:
+        lines.append("  []")
+    else:
+        for row in obs.rows:
+            # key-sorted within the flow map for stable diffs when col set grows
+            items = ", ".join(f"{k}: {_yaml_flow_scalar(row[k])}" for k in row)
+            lines.append(f"{_ROW_PREFIX}{{{items}}}")
+    return "\n".join(lines) + "\n"
+
+
+def write_observation(path: Path, obs: Observation) -> None:
+    """Write observation file; parent dirs created as needed."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(render_observation(obs), encoding="utf-8")
+
+
+def compare_observations(live: Observation, disk: Observation | None) -> list[str]:
+    """Human-readable drift lines (view/erp/rows); empty = identical rows+erp.
+
+    Row identity is the full projected row dict order as rendered. Used by
+    --diff and --assert-unchanged; never writes.
+    """
+    if disk is None:
+        return [f"missing on disk (live has {len(live.rows)} row(s))"]
+    drifts: list[str] = []
+    if live.view != disk.view:
+        drifts.append(f"view: live={live.view!r} disk={disk.view!r}")
+    if live.erp != disk.erp:
+        drifts.append(f"erp: live={live.erp!r} disk={disk.erp!r}")
+    live_text = render_observation(live)
+    disk_text = render_observation(disk)
+    if live_text == disk_text:
+        return drifts
+    if len(live.rows) != len(disk.rows):
+        drifts.append(f"rows: live has {len(live.rows)}, disk has {len(disk.rows)}")
+    elif not drifts:
+        for i, (a, b) in enumerate(zip(live.rows, disk.rows, strict=True)):
+            if a != b:
+                drifts.append(f"row[{i}]: live={a!r} disk={b!r}")
+    return drifts
+
+
+def expand_view_files(files: tuple[Path, ...]) -> list[Path]:
+    """Expand dir args to sorted ``*.yaml``; explicit files preserved order."""
+    paths: list[Path] = []
+    for path in files:
+        if path.is_dir():
+            found = sorted(path.glob("*.yaml"))
+            if not found:
+                raise SystemExit(f"{path}: no snapshot *.yaml files in directory")
+            paths += found
+        else:
+            paths.append(path)
+    return paths
+
+
+def live_erp_build(client: AcumaticaClient) -> str:
+    """Live ERP build id for observation ``erp:`` header (V32).
+
+    Prefers ``GET /entity`` wrapper ``version.acumaticaBuildVersion`` (T92);
+    falls back to claimed ``target.yaml`` erp is not available here — use
+    the configured default string when the wrapper omits build.
+    """
+    try:
+        _endpoints, build = client.entity_root()
+    except RuntimeError, OSError:
+        return "unknown"
+    return build or "unknown"
+
+
+def fetch_live_rows(client: AcumaticaClient, view: ViewDef) -> list[dict[str, Any]]:
+    """Pull raw unwrapped rows for a view via entity: / gi: / inquire: (V33)."""
+    if view.source.kind == "entity":
+        return _fetch_entity_rows(client, view)
+    if view.source.kind == "gi":
+        return _fetch_gi_rows(client, view)
+    return _fetch_inquire_rows(client, view)
+
+
+def _odata_params(params: dict[str, Any]) -> dict[str, str]:
+    """Stringify view params for OData/query use; keys pass through as-is."""
+    return {str(k): "" if v is None else str(v) for k, v in params.items()}
+
+
+def _fetch_entity_rows(client: AcumaticaClient, view: ViewDef) -> list[dict[str, Any]]:
+    """Contract REST list GET on Default/<api_version> (V33; no per-view pin)."""
+    assert view.source.entity is not None
+    params = _odata_params(view.source.params)
+    # narrow select when no explicit $select — allowlist only
+    if "$select" not in params and "select" not in params:
+        fields = list(dict.fromkeys([*view.key, *view.capture]))
+        params["$select"] = ",".join(fields)
+    rows = client.get_list(view.source.entity, params=params or None)
+    return [unwrap(r) for r in rows]
+
+
+def validate_gi_params(metadata_xml: str, gi_name: str, params: dict[str, Any]) -> None:
+    """Fail-closed: every param key must appear in the GI's $metadata (V33).
+
+    Acumatica OData metadata is EDMX. Parameter names may surface as
+    ``Parameter`` / ``Property`` / ``ParameterImport`` elements with a
+    ``Name`` attribute. Unknown param keys raise SystemExit — silent
+    ignore of Period (and kin) would produce phantom full-set captures.
+    """
+    if not params:
+        return
+    try:
+        root = ET.fromstring(metadata_xml)
+    except ET.ParseError as exc:
+        raise SystemExit(
+            f"gi {gi_name!r}: $metadata not parseable as XML: {exc}"
+        ) from exc
+    names: set[str] = set()
+    for el in root.iter():
+        tag = el.tag.rsplit("}", 1)[-1]
+        if tag in {
+            "Parameter",
+            "Property",
+            "ParameterImport",
+            "FunctionImport",
+            "EntityType",
+            "ComplexType",
+        }:
+            name = el.attrib.get("Name") or el.attrib.get("name")
+            if name:
+                names.add(name)
+        # also collect Annotation/Documentation free text sparingly — skip
+    # Always allow common OData system options
+    system = {"$filter", "$select", "$top", "$orderby", "$expand", "$skip", "$format"}
+    unknown = [k for k in params if k not in names and k not in system]
+    if unknown and not names:
+        # metadata had no Name attributes we recognize — fail closed
+        raise SystemExit(
+            f"gi {gi_name!r}: $metadata has no discoverable parameter names; "
+            f"cannot validate params {sorted(params)}; refuse rather than "
+            "silently ignore (V33)"
+        )
+    if unknown:
+        raise SystemExit(
+            f"gi {gi_name!r}: unknown params {unknown} not in $metadata "
+            f"(known: {', '.join(sorted(names)) or '(none)'}) (V33)"
+        )
+
+
+def _fetch_gi_rows(client: AcumaticaClient, view: ViewDef) -> list[dict[str, Any]]:
+    """OData Generic Inquiry rows (V33); params validated against $metadata."""
+    assert view.source.gi is not None
+    gi = view.source.gi
+    params = dict(view.source.params)
+    meta = client.odata_gi_metadata(gi)
+    validate_gi_params(meta, gi, params)
+    raw = client.odata_gi(gi, params=_odata_params(params) or None)
+    return _odata_value_rows(raw)
+
+
+def _fetch_inquire_rows(client: AcumaticaClient, view: ViewDef) -> list[dict[str, Any]]:
+    """Contract inquiry PUT ``$expand=Results`` (V33; same idiom as run).
+
+    View ``params`` are the PUT body (pinned in YAML). Optional ``match``
+    keeps only Results rows whose unwrapped fields equal the filter
+    (``seed._norm`` compare — number spelling tolerant). Rows are then
+    projected by key+capture in ``project_rows``.
+    """
+    assert view.source.inquire is not None
+    body = client.put(
+        view.source.inquire,
+        dict(view.source.params),
+        params={"$expand": "Results"},
+    )
+    match = view.source.match
+    rows: list[dict[str, Any]] = []
+    for row in body.get("Results") or []:
+        values = unwrap(row) if isinstance(row, dict) else {}
+        if match and any(
+            field not in values or _norm(values[field]) != _norm(want)
+            for field, want in match.items()
+        ):
+            continue
+        rows.append(values)
+    return rows
+
+
+def _odata_value_rows(body: Any) -> list[dict[str, Any]]:
+    """Normalize OData JSON to a list of plain dict rows."""
+    if isinstance(body, list):
+        return [dict(r) for r in body if isinstance(r, dict)]
+    if isinstance(body, dict):
+        value = body.get("value")
+        if isinstance(value, list):
+            return [dict(r) for r in value if isinstance(r, dict)]
+        # single entity object
+        if body and not any(k.startswith("@odata") for k in body if k != "value"):
+            # might still be a wrapper with only odata keys + value missing
+            data = {k: v for k, v in body.items() if not str(k).startswith("@")}
+            if data and "value" not in data:
+                return [data]
+    raise RuntimeError(f"OData response not a row list: {type(body).__name__}")
+
+
+def capture_view(
+    client: AcumaticaClient, view: ViewDef, erp: str | None = None
+) -> Observation:
+    """Fetch live rows, project, return Observation (no disk I/O)."""
+    rows = project_rows(fetch_live_rows(client, view), view)
+    return Observation(
+        view=view.name,
+        erp=erp if erp is not None else live_erp_build(client),
+        rows=rows,
+    )
+
+
+def observation_path(out_dir: Path, view: ViewDef) -> Path:
+    """Default observation path for a view under ``out_dir``."""
+    return out_dir / f"{view.name}.yaml"
+
+
+def _dry_run_views(views: list[ViewDef], out_dir: Path) -> int:
+    """List resolved views without HTTP (V32 --dry-run)."""
+    for view in views:
+        src = f"{view.source.kind}:{view.source.name}"
+        params = f" params={view.source.params}" if view.source.params else ""
+        output.data(
+            f"would capture {view.path} -> "
+            f"{observation_path(out_dir, view)} ({src}{params})"
+        )
+    output.data(f"{len(views)} view(s) (dry run)")
+    return 0
+
+
+def _process_view(
+    client: AcumaticaClient,
+    view: ViewDef,
+    *,
+    out_dir: Path,
+    erp: str,
+    diff: bool,
+) -> bool:
+    """Capture one view; write or compare. Returns True if state moved."""
+    dest = observation_path(out_dir, view)
+    output.data(f"{view.path} -> {view.name} ({view.source.kind}:{view.source.name})")
+    live = capture_view(client, view, erp=erp)
+    if not diff:
+        write_observation(dest, live)
+        output.data(f"  wrote {dest} ({len(live.rows)} row(s))")
+        return False
+    disk = load_observation(dest) if dest.is_file() else None
+    drifts = compare_observations(live, disk)
+    if drifts:
+        output.data(f"  changed ({len(drifts)} difference(s))")
+        for line in drifts:
+            output.data(f"    {line}")
+        return True
+    output.data(f"  {len(live.rows)} row(s) unchanged")
+    return False
+
+
+def run_views(
+    client: AcumaticaClient | None,
+    views: list[ViewDef],
+    *,
+    out_dir: Path,
+    mode: Literal["write", "diff", "assert", "dry"] = "write",
+) -> int:
+    """Execute snapshot for views; return process exit code (V32 exit matrix).
+
+    0 = ok (write or compare; change fine unless assert)
+    1 = operational failure
+    2 = state moved under assert mode
+    """
+    if mode == "dry":
+        return _dry_run_views(views, out_dir)
+    assert client is not None
+    diff = mode in ("diff", "assert")
+    erp = live_erp_build(client)
+    moved = False
+    try:
+        for view in views:
+            if _process_view(client, view, out_dir=out_dir, erp=erp, diff=diff):
+                moved = True
+    except SystemExit:
+        raise
+    except (RuntimeError, OSError) as exc:
+        output.error(str(exc))
+        return 1
+    if mode == "assert" and moved:
+        return 2
+    return 0

{acumatica_cli-0.12.1 → acumatica_cli-0.13.0}/src/acumatica_cli/templates/distribution/README.md

@@ -21,6 +21,11 @@ acu run scenario/
 
 # 5. Prove no drift
 acu diff config/
+
+# 6. Capture derived-state observations (EndingBalance trial-balance)
+acu snapshot
+# warm gate: once-capital only — additive buy/sell moves numeric observations
+acu run scenario/10-seed-capital.yaml && acu snapshot --assert-unchanged
 ```
 
 Bare `acu apply` / `acu diff` also prefer `config/` when those trees exist.
@@ -34,6 +39,8 @@ Bare `acu apply` / `acu diff` also prefer `config/` when those trees exist.
 | `config/setup/` | Financial year, master calendar, open periods |
 | `config/master/` | Inventory, warehouse, items, vendors, customers, module prefs |
 | `scenario/` | Lifecycle: `10-seed-capital` (once) + `20-buy-gateways` + `30-build` (stub) + `40-sell` |
+| `config/snapshot/` | Observer views (`inquire:` TB golden; optional custom `gi:` / `inquire:`) for `acu snapshot` (not SEED_DIRS) |
+| `state/` | Committed observation files (written by `acu snapshot`, not seed; money fixed-point) |
 | `target.yaml` | Verified ERP / Default API matrix |
 
 Org CD is the single placeholder **LAB5** across company, ledger-company, open periods, inventory transit branch, and cash account.
@@ -44,15 +51,36 @@ Org CD is the single placeholder **LAB5** across company, ledger-company, open p
 
 A warm second `acu run scenario/` skips capital when the probe already holds, so Owner Capital stays 50000 (not 100000).
 
-Additive buy/sell legs re-run with per-leg delta expects.
+Additive buy/sell legs re-run with per-leg delta expects (including `InventorySummaryInquiry` qty deltas on the scenario path — not snapshot golden).
 
 Monoscenario `buy-sell` is not part of this flavor.
 
+## Snapshot vs extract / diff
+
+| Command | Reads | Writes |
+| ------- | ----- | ------ |
+| `extract` | live **config** | seed YAML under bootstrap/baseline/setup |
+| `diff` | seed YAML + live config | nothing (exit 2 on drift) |
+| `snapshot` | live **derived state** | `state/*.yaml` observations (not seed) |
+
+Default scaffold golden is **trial-balance only** (V28/V33):
+
+- `10-trial-balance.yaml` → `inquire: AccountSummaryInquiry`, capture includes `EndingBalance`
+
+Roster-only `entity: Account` is not used for that stem.
+`inventory-summary` / `QtyOnHand` is not packaged this pass (`InventorySummaryInquiry`
+warehouse-only returns empty Results). Add a custom view when a verified path is known.
+`gi:` remains optional when a GI is V12-verified and **Expose via OData** is on
+(seed under `config/master/`, pin `source.gi:` + params).
+
+**Migration:** bare `acu snapshot` reads `config/snapshot/` and writes `state/` (not root `snapshot/` / `snapshots/`).
+
 ## Non-goals
 
 - Multi-org, multicurrency, full tax engine
 - Production cutover / opening balances from a legacy system
 - Replacing external data repos for production cutovers
+- Historical series inside the tool — use `git log -p state/`
 
 ## Default flavor
 

acumatica_cli-0.13.0/src/acumatica_cli/templates/distribution/snapshot/10-trial-balance.yaml

@@ -0,0 +1,20 @@
+# Snapshot view: GL trial balance (EndingBalance-class, V33).
+# inquire: AccountSummaryInquiry — same contract inquiry as run expect/present
+# (Ledger + Period pinned; Results projected by Account). gi: LAB5-TrialBalance
+# remains optional when GenericInquiry is V12-verified and Expose via OData is on.
+# After scenario/, `acu snapshot --assert-unchanged` is the idempotence gate (V32).
+name: trial-balance
+source:
+  inquire: AccountSummaryInquiry
+  params:
+    Ledger: ACTUAL
+    Period: "072026"
+key:
+  - Account
+capture:
+  - Description
+  - BegBalance
+  - DebitTotal
+  - CreditTotal
+  - EndingBalance
+decimals: 2

acumatica_cli-0.13.0/src/acumatica_cli/templates/finance/snapshot/10-trial-balance.yaml

@@ -0,0 +1,20 @@
+# Snapshot view: GL trial balance (EndingBalance-class, V33).
+# inquire: AccountSummaryInquiry — same contract inquiry as run expect/present
+# (Ledger + Period pinned; Results projected by Account). gi: LAB5-TrialBalance
+# remains optional when GenericInquiry is V12-verified and Expose via OData is on.
+# After scenario/, `acu snapshot --assert-unchanged` is the idempotence gate (V32).
+name: trial-balance
+source:
+  inquire: AccountSummaryInquiry
+  params:
+    Ledger: ACTUAL
+    Period: "072026"
+key:
+  - Account
+capture:
+  - Description
+  - BegBalance
+  - DebitTotal
+  - CreditTotal
+  - EndingBalance
+decimals: 2