acumatica-cli 0.30.0__tar.gz → 0.32.0__tar.gz

{acumatica_cli-0.30.0 → acumatica_cli-0.32.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: acumatica-cli
-Version: 0.30.0
+Version: 0.32.0
 Summary: Acumatica ERP Config-as-Code: tenant provisioning, baseline config, and reference data
 Author: Konstantin Borovik
 Author-email: Konstantin Borovik <kb@lab5.ca>
@@ -40,21 +40,21 @@ YAML in git is the source of truth; the live tenant is the target. `apply` is th
 | ------- | ------- | ------ |
 | Seed a tenant from YAML | `apply` | Idempotent PUT of `config/` into the live tenant |
 | Detect drift | `diff` | Compare seed YAML to live (exit 2 when they diverge) |
-| Pull live config into YAML | `extract` | Inverse of `apply` — GET into `config/{bootstrap,baseline,setup,master}/` |
+| Pull live config into YAML | `survey extract` | Inverse of `apply` — GET into `config/{bootstrap,baseline,setup,master}/` |
 | Run transaction scripts | `run` | Forward documents from `scenario/` (capital, buy, build, sell) |
 | Capture derived balances | `state` | Inquire trial-balance etc. into `state/` (not seed) |
 | Create and destroy tenants | `tenant` | SSH control plane: list / create / delete / recycle |
 | Publish the Bootstrap contract | `bootstrap` | REST publish of AcuBootstrap (or `--export` zip for the UI) |
 | Prove a cold rebuild | `tenant create` then `apply` then `run` then `diff` | Compose on a fresh tenant. No wrap command. |
-| Snapshot a site offline | `inventory` | SM203520 XML ZIP or `ac.exe export xml` writes `inventory/` |
-| Cross-check snapshot vs seed | `reconcile` | `inventory/` plus optional `config/` writes `findings/` only |
+| Snapshot a site offline | `survey inventory` | SM203520 XML ZIP or `ac.exe export xml` writes `inventory/` |
+| Cross-check snapshot vs seed | `survey reconcile` | `inventory/` plus optional `config/` writes `findings/` only |
 | Dump the contract schema | `schema` | OpenAPI `swagger.json` for the pinned endpoint |
 | Scaffold a data repo | `config init` | Full `config/`, `scenario/`, `.env` tree |
 | Preflight a target | `config check` | Discovery, secrets, REST, endpoints, SSH |
 
 Seed YAML covers features, company, credit terms, subaccounts, chart of accounts, ledger, UOMs, financial year / calendar / periods, numbering sequences, inventory and distribution masters, roles, and users.
 
-REST is the data plane (`apply`, `diff`, `run`, `extract`, `state`, `bootstrap`, `schema`).
+REST is the data plane (`apply`, `diff`, `run`, `survey extract`, `state`, `bootstrap`, `schema`).
 SSH is the control plane (`tenant *`).
 
 Hosted sites skip SSH.
@@ -116,11 +116,12 @@ acu [--tenant NAME] [--url URL] [--ssh USER@HOST] [--api-version V]
 ├── run   [--dry-run] [FILES...]      execute transaction scenario YAML (exit 1 on any miss)
 ├── state [--out DIR] [--diff] [--assert-unchanged] [--dry-run] [FILES...]
 │                                     capture derived state into state/ (not seed)
-├── extract [--out DIR] [--only NAME]... [--force] [--dry-run]
-│                                     inverse of apply into config/{bootstrap,baseline,setup,master}/
-├── inventory [--out DIR] [--force] [--dry-run] ARTIFACT
-│                                     offline snapshot artifact → inventory/ (not seed)
-├── reconcile [--inventory DIR] [--config DIR] [--out DIR] [--force] [--dry-run]
+├── survey                            existing-tenant dual-reader (never L1 extract/inventory/reconcile)
+│   ├── extract [--out DIR] [--only NAME]... [--force] [--dry-run]
+│   │                                 inverse of apply into config/{bootstrap,baseline,setup,master}/
+│   ├── inventory [--out DIR] [--force] [--dry-run] ARTIFACT
+│   │                                 offline snapshot artifact → inventory/ (not seed)
+│   └── reconcile [--inventory DIR] [--config DIR] [--out DIR] [--force] [--dry-run]
 │                                     inventory/ + optional config/ → findings/ only
 ├── schema [--out DIR]                dump the endpoint's OpenAPI schema (swagger.json)
 │
@@ -141,12 +142,12 @@ When you omit FILES:
 Scenario YAML may use `${current_period}` (host-local `MMyyyy`) on steps, expect params, and `once.present` params.
 `config/views` and `state` keep Period pinned — see [docs/demo-seed.md](docs/demo-seed.md#period-token-current_period-vs-pinned-views).
 
-`extract` always writes under `config/{bootstrap,baseline,setup,master}/` (catalog-driven; never root SEED_DIRS).
+`survey extract` always writes under `config/{bootstrap,baseline,setup,master}/` (catalog-driven; never root SEED_DIRS).
 
-`inventory` and `reconcile` are offline (no REST, SSH, or password).
-`inventory` turns an SM203520 Settings XML ZIP or `ac.exe export xml` folder into `inventory/`.
+`survey inventory` and `survey reconcile` are offline (no REST, SSH, or password).
+`survey inventory` turns an SM203520 Settings XML ZIP or `ac.exe export xml` folder into `inventory/`.
 
-`reconcile` compares `inventory/` to optional `config/` and writes `findings/` only.
+`survey reconcile` compares `inventory/` to optional `config/` and writes `findings/` only.
 It never writes seed.
 
 Optional `snapshot_map.yaml` (data-repo root, or package defaults) maps DAC tables to catalog entities.
@@ -168,9 +169,9 @@ Do not confuse them with each other or with `state`:
 
 | Command | Plane | Input | Writes | Role |
 | ------- | ----- | ----- | ------ | ---- |
-| `extract` | REST (live) | tenant via contract API | `config/{bootstrap,baseline,setup,master}/` | Inverse of `apply` — seed YAML |
-| `inventory` | Offline | SM203520 Settings XML ZIP or `ac.exe export xml` folder | `inventory/` (`summary.yaml` + `tables/`) | Full-table snapshot IR — not seed |
-| `reconcile` | Offline | `inventory/` + optional `config/` | `findings/` only | Cross-check gaps/deltas — never mutates seed or tenant |
+| `survey extract` | REST (live) | tenant via contract API | `config/{bootstrap,baseline,setup,master}/` | Inverse of `apply` — seed YAML |
+| `survey inventory` | Offline | SM203520 Settings XML ZIP or `ac.exe export xml` folder | `inventory/` (`summary.yaml` + `tables/`) | Full-table snapshot IR — not seed |
+| `survey reconcile` | Offline | `inventory/` + optional `config/` | `findings/` only | Cross-check gaps/deltas — never mutates seed or tenant |
 | `state` | REST (live) | `config/views/` | `state/` | Derived balances/totals — not seed, not inventory |
 | `apply` | REST (live) | seed YAML under `config/` | tenant | **Sole** tenant writer (keyed PUT) |
 
@@ -198,8 +199,8 @@ There is no `--flavor`.
 | `scenario/` | lifecycle txns for `acu run`: once capital, then buy, build, sell |
 | `config/views/` | observer views for `acu state` (`inquire:` / `entity:` / `gi:`; not SEED_DIRS) |
 | `state/` | committed derived-state observations (evidence, not seed; money/qty fixed-point) |
-| `inventory/` | engagement: offline snapshot tables from `acu inventory` (not seed; not SEED_DIRS) |
-| `findings/` | engagement: `acu reconcile` cross-check output (never apply path) |
+| `inventory/` | engagement: offline snapshot tables from `acu survey inventory` (not seed; not SEED_DIRS) |
+| `findings/` | engagement: `acu survey reconcile` cross-check output (never apply path) |
 | `.env` | secrets + where (`ACU_BASE_URL`) + pin (`ACU_API_VERSION`) |
 
 Legacy data repos may still keep root `bootstrap/`…`master/`; bare `apply`/`diff` prefer `config/` when present and never merge both trees.
@@ -208,7 +209,7 @@ Files in each directory apply alphabetically; the numbered prefixes (`10-`, `20-
 Commit seed YAML; keep `.env` out of git (scaffold `.gitignore` already lists it).
 
 Seed YAML is state: `apply` upserts it, `diff` proves it.
-`acu extract` is the inverse of `apply`: GET live tenant rows into seed YAML under `config/{bootstrap,baseline,setup,master}/` (hard-cut).
+`acu survey extract` is the inverse of `apply`: GET live tenant rows into seed YAML under `config/{bootstrap,baseline,setup,master}/` (hard-cut).
 
 Packaged `seed_catalog.yaml` is the sole extract registry (entity, endpoint, keys, file, strip/include, filter-split).
 The demo entity map in [docs/demo-seed.md](docs/demo-seed.md) mirrors those catalog paths.
@@ -220,7 +221,7 @@ Row failures continue (exit 1 only if any row failed).
 Drift stays with `diff`.
 
 ```sh
-acu --tenant DEV extract --out . --force   # refresh config/** from live tenant
+acu --tenant DEV survey extract --out . --force   # refresh config/** from live tenant
 git diff config/                           # review extract delta before commit
 acu --tenant DEV apply config/             # replay extracted seed
 acu --tenant DEV diff config/              # expect exit 0
@@ -377,9 +378,9 @@ gmake release patch   # or minor | major
 2. Fail if `## Unreleased` has no bullets
 3. Bump `pyproject.toml` version (`major` | `minor` | `patch`)
 4. Promote Unreleased body to `## [vX.Y.Z] - YYYY-MM-DD`, leave an empty `## Unreleased`
-5. Commit `CHANGELOG.md` + `pyproject.toml` (+ lock if bumped) together, tag `vX.Y.Z`
-6. `gmake check` again on the promoted tree
-7. Push tag + branch — GitHub Actions publishes
+5. Commit `CHANGELOG.md` + `pyproject.toml` (+ lock if bumped) together
+6. `gmake check` again on the promoted tree — fail keeps the commit, creates no tag, pushes nothing
+7. Tag `vX.Y.Z` and push branch + that tag — GitHub Actions publishes
 
 GitHub Actions on tag `v*` re-runs CI, builds sdist+wheel, publishes to PyPI via OIDC trusted publishing, and creates a GitHub Release whose notes are the promoted CHANGELOG section for that tag (plus the artifacts).
 

{acumatica_cli-0.30.0 → acumatica_cli-0.32.0}/README.md

@@ -22,21 +22,21 @@ YAML in git is the source of truth; the live tenant is the target. `apply` is th
 | ------- | ------- | ------ |
 | Seed a tenant from YAML | `apply` | Idempotent PUT of `config/` into the live tenant |
 | Detect drift | `diff` | Compare seed YAML to live (exit 2 when they diverge) |
-| Pull live config into YAML | `extract` | Inverse of `apply` — GET into `config/{bootstrap,baseline,setup,master}/` |
+| Pull live config into YAML | `survey extract` | Inverse of `apply` — GET into `config/{bootstrap,baseline,setup,master}/` |
 | Run transaction scripts | `run` | Forward documents from `scenario/` (capital, buy, build, sell) |
 | Capture derived balances | `state` | Inquire trial-balance etc. into `state/` (not seed) |
 | Create and destroy tenants | `tenant` | SSH control plane: list / create / delete / recycle |
 | Publish the Bootstrap contract | `bootstrap` | REST publish of AcuBootstrap (or `--export` zip for the UI) |
 | Prove a cold rebuild | `tenant create` then `apply` then `run` then `diff` | Compose on a fresh tenant. No wrap command. |
-| Snapshot a site offline | `inventory` | SM203520 XML ZIP or `ac.exe export xml` writes `inventory/` |
-| Cross-check snapshot vs seed | `reconcile` | `inventory/` plus optional `config/` writes `findings/` only |
+| Snapshot a site offline | `survey inventory` | SM203520 XML ZIP or `ac.exe export xml` writes `inventory/` |
+| Cross-check snapshot vs seed | `survey reconcile` | `inventory/` plus optional `config/` writes `findings/` only |
 | Dump the contract schema | `schema` | OpenAPI `swagger.json` for the pinned endpoint |
 | Scaffold a data repo | `config init` | Full `config/`, `scenario/`, `.env` tree |
 | Preflight a target | `config check` | Discovery, secrets, REST, endpoints, SSH |
 
 Seed YAML covers features, company, credit terms, subaccounts, chart of accounts, ledger, UOMs, financial year / calendar / periods, numbering sequences, inventory and distribution masters, roles, and users.
 
-REST is the data plane (`apply`, `diff`, `run`, `extract`, `state`, `bootstrap`, `schema`).
+REST is the data plane (`apply`, `diff`, `run`, `survey extract`, `state`, `bootstrap`, `schema`).
 SSH is the control plane (`tenant *`).
 
 Hosted sites skip SSH.
@@ -98,11 +98,12 @@ acu [--tenant NAME] [--url URL] [--ssh USER@HOST] [--api-version V]
 ├── run   [--dry-run] [FILES...]      execute transaction scenario YAML (exit 1 on any miss)
 ├── state [--out DIR] [--diff] [--assert-unchanged] [--dry-run] [FILES...]
 │                                     capture derived state into state/ (not seed)
-├── extract [--out DIR] [--only NAME]... [--force] [--dry-run]
-│                                     inverse of apply into config/{bootstrap,baseline,setup,master}/
-├── inventory [--out DIR] [--force] [--dry-run] ARTIFACT
-│                                     offline snapshot artifact → inventory/ (not seed)
-├── reconcile [--inventory DIR] [--config DIR] [--out DIR] [--force] [--dry-run]
+├── survey                            existing-tenant dual-reader (never L1 extract/inventory/reconcile)
+│   ├── extract [--out DIR] [--only NAME]... [--force] [--dry-run]
+│   │                                 inverse of apply into config/{bootstrap,baseline,setup,master}/
+│   ├── inventory [--out DIR] [--force] [--dry-run] ARTIFACT
+│   │                                 offline snapshot artifact → inventory/ (not seed)
+│   └── reconcile [--inventory DIR] [--config DIR] [--out DIR] [--force] [--dry-run]
 │                                     inventory/ + optional config/ → findings/ only
 ├── schema [--out DIR]                dump the endpoint's OpenAPI schema (swagger.json)
 │
@@ -123,12 +124,12 @@ When you omit FILES:
 Scenario YAML may use `${current_period}` (host-local `MMyyyy`) on steps, expect params, and `once.present` params.
 `config/views` and `state` keep Period pinned — see [docs/demo-seed.md](docs/demo-seed.md#period-token-current_period-vs-pinned-views).
 
-`extract` always writes under `config/{bootstrap,baseline,setup,master}/` (catalog-driven; never root SEED_DIRS).
+`survey extract` always writes under `config/{bootstrap,baseline,setup,master}/` (catalog-driven; never root SEED_DIRS).
 
-`inventory` and `reconcile` are offline (no REST, SSH, or password).
-`inventory` turns an SM203520 Settings XML ZIP or `ac.exe export xml` folder into `inventory/`.
+`survey inventory` and `survey reconcile` are offline (no REST, SSH, or password).
+`survey inventory` turns an SM203520 Settings XML ZIP or `ac.exe export xml` folder into `inventory/`.
 
-`reconcile` compares `inventory/` to optional `config/` and writes `findings/` only.
+`survey reconcile` compares `inventory/` to optional `config/` and writes `findings/` only.
 It never writes seed.
 
 Optional `snapshot_map.yaml` (data-repo root, or package defaults) maps DAC tables to catalog entities.
@@ -150,9 +151,9 @@ Do not confuse them with each other or with `state`:
 
 | Command | Plane | Input | Writes | Role |
 | ------- | ----- | ----- | ------ | ---- |
-| `extract` | REST (live) | tenant via contract API | `config/{bootstrap,baseline,setup,master}/` | Inverse of `apply` — seed YAML |
-| `inventory` | Offline | SM203520 Settings XML ZIP or `ac.exe export xml` folder | `inventory/` (`summary.yaml` + `tables/`) | Full-table snapshot IR — not seed |
-| `reconcile` | Offline | `inventory/` + optional `config/` | `findings/` only | Cross-check gaps/deltas — never mutates seed or tenant |
+| `survey extract` | REST (live) | tenant via contract API | `config/{bootstrap,baseline,setup,master}/` | Inverse of `apply` — seed YAML |
+| `survey inventory` | Offline | SM203520 Settings XML ZIP or `ac.exe export xml` folder | `inventory/` (`summary.yaml` + `tables/`) | Full-table snapshot IR — not seed |
+| `survey reconcile` | Offline | `inventory/` + optional `config/` | `findings/` only | Cross-check gaps/deltas — never mutates seed or tenant |
 | `state` | REST (live) | `config/views/` | `state/` | Derived balances/totals — not seed, not inventory |
 | `apply` | REST (live) | seed YAML under `config/` | tenant | **Sole** tenant writer (keyed PUT) |
 
@@ -180,8 +181,8 @@ There is no `--flavor`.
 | `scenario/` | lifecycle txns for `acu run`: once capital, then buy, build, sell |
 | `config/views/` | observer views for `acu state` (`inquire:` / `entity:` / `gi:`; not SEED_DIRS) |
 | `state/` | committed derived-state observations (evidence, not seed; money/qty fixed-point) |
-| `inventory/` | engagement: offline snapshot tables from `acu inventory` (not seed; not SEED_DIRS) |
-| `findings/` | engagement: `acu reconcile` cross-check output (never apply path) |
+| `inventory/` | engagement: offline snapshot tables from `acu survey inventory` (not seed; not SEED_DIRS) |
+| `findings/` | engagement: `acu survey reconcile` cross-check output (never apply path) |
 | `.env` | secrets + where (`ACU_BASE_URL`) + pin (`ACU_API_VERSION`) |
 
 Legacy data repos may still keep root `bootstrap/`…`master/`; bare `apply`/`diff` prefer `config/` when present and never merge both trees.
@@ -190,7 +191,7 @@ Files in each directory apply alphabetically; the numbered prefixes (`10-`, `20-
 Commit seed YAML; keep `.env` out of git (scaffold `.gitignore` already lists it).
 
 Seed YAML is state: `apply` upserts it, `diff` proves it.
-`acu extract` is the inverse of `apply`: GET live tenant rows into seed YAML under `config/{bootstrap,baseline,setup,master}/` (hard-cut).
+`acu survey extract` is the inverse of `apply`: GET live tenant rows into seed YAML under `config/{bootstrap,baseline,setup,master}/` (hard-cut).
 
 Packaged `seed_catalog.yaml` is the sole extract registry (entity, endpoint, keys, file, strip/include, filter-split).
 The demo entity map in [docs/demo-seed.md](docs/demo-seed.md) mirrors those catalog paths.
@@ -202,7 +203,7 @@ Row failures continue (exit 1 only if any row failed).
 Drift stays with `diff`.
 
 ```sh
-acu --tenant DEV extract --out . --force   # refresh config/** from live tenant
+acu --tenant DEV survey extract --out . --force   # refresh config/** from live tenant
 git diff config/                           # review extract delta before commit
 acu --tenant DEV apply config/             # replay extracted seed
 acu --tenant DEV diff config/              # expect exit 0
@@ -359,9 +360,9 @@ gmake release patch   # or minor | major
 2. Fail if `## Unreleased` has no bullets
 3. Bump `pyproject.toml` version (`major` | `minor` | `patch`)
 4. Promote Unreleased body to `## [vX.Y.Z] - YYYY-MM-DD`, leave an empty `## Unreleased`
-5. Commit `CHANGELOG.md` + `pyproject.toml` (+ lock if bumped) together, tag `vX.Y.Z`
-6. `gmake check` again on the promoted tree
-7. Push tag + branch — GitHub Actions publishes
+5. Commit `CHANGELOG.md` + `pyproject.toml` (+ lock if bumped) together
+6. `gmake check` again on the promoted tree — fail keeps the commit, creates no tag, pushes nothing
+7. Tag `vX.Y.Z` and push branch + that tag — GitHub Actions publishes
 
 GitHub Actions on tag `v*` re-runs CI, builds sdist+wheel, publishes to PyPI via OIDC trusted publishing, and creates a GitHub Release whose notes are the promoted CHANGELOG section for that tag (plus the artifacts).
 

{acumatica_cli-0.30.0 → acumatica_cli-0.32.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "acumatica-cli"
-version = "0.30.0"
+version = "0.32.0"
 description = "Acumatica ERP Config-as-Code: tenant provisioning, baseline config, and reference data"
 license = "PolyForm-Noncommercial-1.0.0"
 readme = "README.md"

{acumatica_cli-0.30.0 → acumatica_cli-0.32.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "acumatica-cli"
-version = "0.30.0"
+version = "0.32.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.30.0 → acumatica_cli-0.32.0}/src/acumatica_cli/cli.py

@@ -5,13 +5,13 @@ Configure Acumatica ERP from YAML in a git data repo. No UI wizards.
 \b
 MENTAL MODEL
   Data repo = directory with .env (walk-up from cwd). Holds:
-    config/{bootstrap,baseline,setup,master}/  seed YAML (apply/diff/extract)
+    config/{bootstrap,baseline,setup,master}/  seed YAML (apply/diff/survey extract)
     config/views/                              observer views (state)
     scenario/                                  transaction scripts (run)
     .env                                       secrets + where + API pin
     state/ inventory/ findings/ schemas/       command outputs (not seed)
   Two planes (do not mix):
-    REST data plane — apply diff run bootstrap extract state schema
+    REST data plane — apply diff run bootstrap survey extract state schema
       needs: base_url, tenant, password (SSH optional)
     SSH control plane — tenant list|create|delete|recycle
       needs: non-empty ACU_SSH (user@host)
@@ -56,9 +56,9 @@ COMMAND MAP (pick by intent)
   seed check   diff [FILES...]                           (exit 2 on drift)
   txns         run [--dry-run] [FILES...]
   cold rebuild tenant create then apply then run then diff (no wrap cmd)
-  pull seed    extract [--only ENTITY]...                (inverse of apply)
+  pull seed    survey extract [--only ENTITY]...         (inverse of apply)
   observe      state [--diff|--assert-unchanged]
-  offline      inventory ARTIFACT | reconcile
+  offline      survey inventory ARTIFACT | survey reconcile
   reference    schema
 
 \b
@@ -73,7 +73,7 @@ DEFAULT PATHS (when FILES omitted)
                 then overlays/default-<api>/ when present
   run         -> scenario/ (overlay same-basename wins)
   state       -> config/views/ -> writes state/
-  extract     -> always writes config/{bootstrap,baseline,setup,master}/
+  survey extract -> always writes config/{bootstrap,baseline,setup,master}/
 
 Run `acu <command> --help` for flags, examples, and prerequisites.
 See package README and docs/demo-seed.md for seed YAML shape.
@@ -1027,7 +1027,7 @@ def apply_cmd(inst: Instance, files: tuple[Path, ...], dry_run: bool) -> None:
       acu --tenant DEV apply --dry-run config/master/
       acu --tenant DEV apply config/baseline/20-accounts.yaml
 
-    Related: `diff` (drift) · `extract` (inverse pull) · `run` (txns).
+    Related: `diff` (drift) · `survey extract` (inverse pull) · `run` (txns).
     """
     total_ok = 0
     all_errors: list[str] = []
@@ -1106,7 +1106,7 @@ def diff_cmd(inst: Instance, files: tuple[Path, ...]) -> None:
       acu --tenant DEV diff config/
       acu --tenant DEV diff config/master/90-roles.yaml
 
-    Related: `apply` (fix) · `extract` (pull) · `state` (balances).
+    Related: `apply` (fix) · `survey extract` (pull) · `state` (balances).
     """
     paths = expand_files(files or default_apply_dirs(inst))
     drifts: list[str] = []
@@ -1189,7 +1189,27 @@ def _complete_only(
     ]
 
 
-@cli.command("extract")
+@cli.group("survey", context_settings=_HELP_CTX)
+def survey_group() -> None:
+    """Existing-tenant dual-reader (REST extract + offline inventory/reconcile).
+
+    Noun owns extract|inventory|reconcile. Never L1 those verbs. No aliases.
+
+    \b
+    Subcommands
+      extract [--only ENTITY]...   live GET -> config/ SEED_DIRS (REST)
+      inventory ARTIFACT           snapshot ZIP/folder -> inventory/ (offline)
+      reconcile                    inventory/ + optional config/ -> findings/ (offline)
+
+    \b
+    Examples
+      acu --tenant DEV survey extract
+      acu survey inventory ./export-xml/
+      acu survey reconcile
+    """
+
+
+@survey_group.command("extract")
 @click.option(
     "--out",
     "out_dir",
@@ -1230,11 +1250,11 @@ def extract_cmd(
 
     \b
     Examples
-      acu --tenant DEV extract
-      acu --tenant DEV extract --only Account --only Vendor
-      acu --tenant DEV extract --force --dry-run
+      acu --tenant DEV survey extract
+      acu --tenant DEV survey extract --only Account --only Vendor
+      acu --tenant DEV survey extract --force --dry-run
 
-    Related: `apply` · `diff` · `inventory` · `state`.
+    Related: `apply` · `diff` · `survey inventory` · `state`.
     """
     with AcumaticaClient(inst) as client:
         failed = extract.run(
@@ -1258,7 +1278,7 @@ def _exit_on_drift(inst: Instance, drifts: list[str], files: int) -> None:
     output.success(f"no drift on {inst.tenant} ({inst.base_url}, {files} file(s))")
 
 
-@cli.command("inventory")
+@survey_group.command("inventory")
 @click.argument(
     "artifact",
     type=click.Path(exists=True, path_type=Path),
@@ -1290,15 +1310,15 @@ def inventory_cmd(
     Existing files skip unless --force.
 
     Not extract (REST → config/ seed). Not state (balances). Never writes
-    config/ or state/. Feed inventory/ into `acu reconcile`.
+    config/ or state/. Feed inventory/ into `acu survey reconcile`.
 
     \b
     Exit  0 = clean · 1 = parse/format/version fail · never 2
 
     \b
     Examples
-      acu inventory ./export-xml/
-      acu inventory Settings.zip --out inventory/ --force
+      acu survey inventory ./export-xml/
+      acu survey inventory Settings.zip --out inventory/ --force
     """
     # V9 long single-op: artifact parse (ZIP/folder IR) via step; banner +
     # per-table write/skip emit stay multi-unit stdout after.
@@ -1312,13 +1332,13 @@ def inventory_cmd(
     inventory.emit(art, dest, force=force, dry_run=dry_run)
 
 
-@cli.command("reconcile")
+@survey_group.command("reconcile")
 @click.option(
     "--inventory",
     "inventory_dir",
     type=click.Path(file_okay=False, path_type=Path),
     default=None,
-    help="Inventory tree from `acu inventory` (default: inventory/)",
+    help="Inventory tree from `acu survey inventory` (default: inventory/)",
 )
 @click.option(
     "--config",
@@ -1361,8 +1381,8 @@ def reconcile_cmd(
 
     \b
     Examples
-      acu inventory export.zip && acu reconcile
-      acu reconcile --inventory inv/ --config config/ --out findings/
+      acu survey inventory export.zip && acu survey reconcile
+      acu survey reconcile --inventory inv/ --config config/ --out findings/
     """
     inv = (
         inventory_dir
@@ -1440,7 +1460,7 @@ def state_cmd(
       acu --tenant DEV state --assert-unchanged
       acu --tenant DEV state config/views/10-trial-balance.yaml
 
-    Related: `run` (moves balances) · `diff` (seed drift) · `extract`.
+    Related: `run` (moves balances) · `diff` (seed drift) · `survey extract`.
     """
     if not files:
         default = data_root() / "config" / "views"

{acumatica_cli-0.30.0 → acumatica_cli-0.32.0}/src/acumatica_cli/client.py

@@ -12,6 +12,11 @@ import httpx
 
 from .config import Instance
 
+# Contract control fields travel bare on wrap and stay on unwrap of
+# value-field rows (V54). Files-style rows that unwrap to only these
+# keys are elided so expanded `files` descriptors stay noise.
+_BARE_FIELDS = frozenset({"id", "delete"})
+
 
 def wrap(record: dict[str, Any]) -> dict[str, Any]:
     """Plain dict -> contract-API body: {"Field": {"value": ...}}.
@@ -33,31 +38,35 @@ def wrap(record: dict[str, Any]) -> dict[str, Any]:
             return wrap(v)
         return {"value": v}
 
-    return {k: v if k in ("id", "delete") else _value(v) for k, v in record.items()}
+    return {k: v if k in _BARE_FIELDS else _value(v) for k, v in record.items()}
 
 
 def unwrap(entity: dict[str, Any]) -> dict[str, Any]:
     """Contract-API entity -> plain dict (value fields + detail arrays).
 
-    Inverse of wrap (T60/T65): a list of dicts unwraps row by row; lists
-    that are empty or whose rows carry no value fields are elided (a
-    detail array the source never claimed must not surface, and expanded
-    `files` descriptors are plain dicts that would unwrap to noise). A
-    non-value dict is a linked entity — unwrapped recursively, kept only
-    when something survives, so bookkeeping dicts (custom, _links, note)
-    stay excluded exactly as before.
+    Inverse of wrap (T60/T65/V54): a list of dicts unwraps row by row;
+    lists that are empty or whose rows carry no value fields are elided
+    (a detail array the source never claimed must not surface, and
+    expanded `files` descriptors are plain dicts that would unwrap to
+    noise). A non-value dict is a linked entity — unwrapped recursively,
+    kept only when something survives, so bookkeeping dicts (custom,
+    _links, note) stay excluded exactly as before. `id` and `delete`
+    stay on records and on detail rows that also have value fields so a
+    later PUT updates the existing line (V54).
     """
     out: dict[str, Any] = {}
     for k, v in entity.items():
-        if isinstance(v, dict) and "value" in v:
+        if k in _BARE_FIELDS and not isinstance(v, (dict, list)):
+            out[k] = v
+        elif isinstance(v, dict) and "value" in v:
             out[k] = v["value"]
         elif isinstance(v, dict):
             nested = unwrap(v)
             if nested:
                 out[k] = nested
         elif isinstance(v, list) and v and all(isinstance(row, dict) for row in v):
-            rows = [unwrap(row) for row in v]
-            if any(rows):
+            rows = [row for row in (unwrap(r) for r in v) if set(row) - _BARE_FIELDS]
+            if rows:
                 out[k] = rows
     return out
 
@@ -326,7 +335,7 @@ class AcumaticaClient:
 
     @staticmethod
     def _checked(r: httpx.Response) -> httpx.Response:
-        """Surface exceptionMessage + nested Field.error (V46), not status alone."""
+        """Surface exceptionMessage + innerException + Field.error (V46)."""
         if r.is_error:
             detail = ""
             try:
@@ -338,12 +347,13 @@ class AcumaticaClient:
                         or body.get("error")
                         or ""
                     )
-                    # nested contract-API validation often rides here
-                    if not detail and isinstance(body.get("innerException"), dict):
+                    if isinstance(body.get("innerException"), dict):
                         inner = body["innerException"]
-                        detail = (
+                        inner_msg = (
                             inner.get("exceptionMessage") or inner.get("message") or ""
                         )
+                        if inner_msg:
+                            detail = f"{detail}; {inner_msg}" if detail else inner_msg
                     field_errs = AcumaticaClient._field_errors(body)
                     if field_errs:
                         joined = "; ".join(field_errs)

{acumatica_cli-0.30.0 → acumatica_cli-0.32.0}/src/acumatica_cli/extract.py

@@ -46,6 +46,8 @@ from .models import Model, validation_summary
 from .seed import (
     NUMBERING_RUNTIME_FIELDS,
     PASSWORD_FIELDS,
+    _calendar_day,  # pyright: ignore[reportPrivateUsage]
+    _drop_path_ignored,  # pyright: ignore[reportPrivateUsage]
     active_bootstrap,
     resolve_endpoint,
 )
@@ -263,14 +265,16 @@ def _fetch(client: AcumaticaClient, spec: EntitySpec) -> list[dict[str, Any]]:
 
 # Server-assigned / audit fields that must never enter seed (B11 class).
 # Applied recursively under linked entities and detail rows after expand
-# (T65/T119): MainContact.ContactID and AllowedCashAccounts.LastModified*
-# would otherwise permanent-red-diff after re-apply on a fresh tenant.
+# (T65/T119). `id`/`delete` stay in unwrap for run-capture PUT (V54);
+# extract still strips them so seed is tenant-portable.
 _SERVER_DERIVED = frozenset(
     {
         "ContactID",
         "CreatedDateTime",
         "LastModifiedDateTime",
         "NoteID",
+        "delete",
+        "id",
         "tstamp",
     }
 )
@@ -293,6 +297,26 @@ def _elide_server_derived(value: Any) -> Any:
     return value
 
 
+def _date_strip(value: Any) -> Any:
+    """DateTimeValue seed emit: keep YYYY-MM-DD prefix only (V55)."""
+    if isinstance(value, dict):
+        return {k: _date_strip(v) for k, v in value.items()}
+    if isinstance(value, list):
+        return [_date_strip(v) for v in value]
+    if isinstance(value, str):
+        day = _calendar_day(value)
+        if day is not None:
+            return day
+    return value
+
+
+def _strip_write_only_get_omit(entity: str, field: str, value: Any) -> Any:
+    """Drop path-qualified write-only GET-omit fields from detail rows (V56)."""
+    if not isinstance(value, list):
+        return value
+    return _drop_path_ignored(entity, field, value)
+
+
 def _kept_fields(spec: EntitySpec, record: dict[str, Any]) -> dict[str, Any]:
     """Apply include/strip + nested server-derived elision to one unwrapped row."""
     keep: dict[str, Any] = {}
@@ -313,6 +337,7 @@ def _kept_fields(spec: EntitySpec, record: dict[str, Any]) -> dict[str, Any]:
             continue
         # Nested ContactID / LastModifiedDateTime under expand (T65/T119).
         cleaned = _elide_server_derived(value)
+        cleaned = _strip_write_only_get_omit(spec.entity, field, cleaned)
         if cleaned is None or cleaned == "":
             continue
         if isinstance(cleaned, (dict, list)) and not cleaned:
@@ -320,7 +345,7 @@ def _kept_fields(spec: EntitySpec, record: dict[str, Any]) -> dict[str, Any]:
         keep[field] = cleaned
     ordered = {k: keep[k] for k in spec.keys if k in keep}
     ordered |= {k: keep[k] for k in sorted(keep.keys() - set(spec.keys))}
-    return ordered
+    return _date_strip(ordered)
 
 
 def _shape(spec: EntitySpec, live: list[dict[str, Any]]) -> list[dict[str, Any]]:

{acumatica_cli-0.30.0 → acumatica_cli-0.32.0}/src/acumatica_cli/reconcile.py

@@ -287,7 +287,7 @@ class FindingsBundle(Model):
 
 
 def load_inventory_tree(path: Path | str) -> InventoryTree:
-    """Load an ``inventory/`` tree written by ``acu inventory`` (I.data)."""
+    """Load an ``inventory/`` tree written by ``acu survey inventory`` (I.data)."""
     root = Path(path)
     if not root.is_dir():
         raise SystemExit(f"{root}: inventory directory not found")
@@ -295,7 +295,7 @@ def load_inventory_tree(path: Path | str) -> InventoryTree:
     if not summary_path.is_file():
         raise SystemExit(
             f"{root}: missing {inventory.SUMMARY_NAME} "
-            "(run `acu inventory` first, or pass --inventory DIR)"
+            "(run `acu survey inventory` first, or pass --inventory DIR)"
         )
     try:
         raw = yaml.safe_load(summary_path.read_text(encoding="utf-8"))

{acumatica_cli-0.30.0 → acumatica_cli-0.32.0}/src/acumatica_cli/seed.py

@@ -52,6 +52,7 @@ Default Currency = CM201000 list), so an ambiguous file is a hard error,
 never a silent Default-endpoint PUT.
 """
 
+import re
 from pathlib import Path
 from typing import Any
 
@@ -88,7 +89,34 @@ PASSWORD_FIELDS = frozenset({"Password", "b64__Password"})
 # PUTs them (re-apply must not reset live counters).
 NUMBERING_RUNTIME_FIELDS = frozenset({"LastNbr"})
 # Fields omitted from source↔live compare (V39 write-only + V40 runtime).
+# Field-name deny at every nesting level. Do not add bare ``Value`` here —
+# that would hide real drift on unrelated fields (V56).
 _DIFF_IGNORE_FIELDS = PASSWORD_FIELDS | NUMBERING_RUNTIME_FIELDS
+# Path-qualified write-only GET-omit (V56): (entity, detail, field).
+# Diff ignores; extract strips; apply still PUTs when present in YAML.
+_DIFF_IGNORE_PATHS = frozenset({("LotSerialClass", "Segments", "Value")})
+
+
+def _diff_ignored(entity: str, *path: str) -> bool:
+    """True when source↔live compare skips this field (V39/V40/V56)."""
+    if path and path[-1] in _DIFF_IGNORE_FIELDS:
+        return True
+    return (entity, *path) in _DIFF_IGNORE_PATHS
+
+
+def _drop_path_ignored(entity: str, field: str, rows: list[Any]) -> list[Any]:
+    """Strip path-qualified GET-omit fields from detail rows (V56)."""
+    drop = {
+        sub for (ent, det, sub) in _DIFF_IGNORE_PATHS if ent == entity and det == field
+    }
+    if not drop:
+        return rows
+    return [
+        {k: v for k, v in row.items() if k not in drop}
+        if isinstance(row, dict)
+        else row
+        for row in rows
+    ]
 
 
 def active_bootstrap(root: Path | None = None) -> tuple[str, frozenset[str]]:
@@ -251,18 +279,33 @@ def load_baseline(path: Path) -> BaselineFile | ActionFile:
     return parsed
 
 
+# ISO date or DateTimeValue: calendar-day prefix only (V55). Random strings
+# that merely contain T stay untouched.
+_ISO_CALENDAR_DAY = re.compile(r"(\d{4}-\d{2}-\d{2})(T.*)?")
+
+
+def _calendar_day(text: str) -> str | None:
+    """YYYY-MM-DD when ``text`` is ISO date/datetime; else None. No TZ convert."""
+    m = _ISO_CALENDAR_DAY.fullmatch(text)
+    return None if m is None else m.group(1)
+
+
 def _norm(value: Any) -> str:
-    """Comparable form: bools case-folded, numbers by value, rest stringified.
+    """Comparable form: bools case-folded, numbers by value, dates by day.
 
     Numbers compare by value, not spelling - a YAML `0` against the
     endpoint's `0.0` (DecimalValue fields come back as floats) is not
-    drift (T13).
+    drift (T13). Date-only ``YYYY-MM-DD`` matches a live DateTimeValue on
+    the same calendar day (strip ``T...offset``); a different day still
+    drifts (V55). No timezone conversion.
     """
     if isinstance(value, bool):
         return str(value).lower()
     if isinstance(value, int | float):
         return repr(float(value))
-    return str(value).strip()
+    text = str(value).strip()
+    day = _calendar_day(text)
+    return text if day is None else day
 
 
 def _filter_for(record: dict[str, Any], keys: list[str]) -> str:
@@ -636,13 +679,18 @@ def diff(client: AcumaticaClient, baseline: BaselineFile | ActionFile) -> list[s
             drifts.append(f"{label}: missing on tenant")
             continue
         actual = unwrap(live)
-        # V39/V40: never compare write-only password or runtime numbering counters
-        fields = {k: v for k, v in record.items() if k not in _DIFF_IGNORE_FIELDS}
+        # V39/V40/V56: never compare write-only, runtime, or GET-omit paths
+        fields = {
+            k: v for k, v in record.items() if not _diff_ignored(baseline.entity, k)
+        }
         for field, expected in fields.items():
             if isinstance(expected, list):
                 key = (baseline.detail_keys or {})[field]  # load-validated
-                live_rows = actual.get(field, [])
-                drifts.extend(_diff_details(label, field, key, expected, live_rows))
+                want_rows = _drop_path_ignored(baseline.entity, field, expected)
+                live_rows = _drop_path_ignored(
+                    baseline.entity, field, actual.get(field, [])
+                )
+                drifts.extend(_diff_details(label, field, key, want_rows, live_rows))
             elif isinstance(expected, dict):
                 drifts.extend(
                     _diff_nested(f"{label}.{field}", expected, actual.get(field))

{acumatica_cli-0.30.0 → acumatica_cli-0.32.0}/src/acumatica_cli/templates/README.md

@@ -33,11 +33,11 @@ acu run scenario/10-seed-capital.yaml && acu state --assert-unchanged
 # SSH cold rebuild: acu tenant create --login NAME, then apply, run, diff
 
 # Optional: re-seed from live (inverse of apply; always under config/)
-# acu extract --out . --force
+# acu survey extract --out . --force
 ```
 
 Bare `acu apply` / `acu diff` also prefer `config/` when those trees exist.
-`acu extract` hard-cuts emit to `config/{bootstrap,baseline,setup,master}/` (never root SEED_DIRS).
+`acu survey extract` hard-cuts emit to `config/{bootstrap,baseline,setup,master}/` (never root SEED_DIRS).
 
 ## Layout