acumatica-cli 0.9.0__tar.gz → 0.10.0__tar.gz

{acumatica_cli-0.9.0 → acumatica_cli-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: acumatica-cli
-Version: 0.9.0
+Version: 0.10.0
 Summary: Acumatica ERP Config-as-Code: tenant provisioning, baseline config, and reference data
 Author: Konstantin Borovik
 Author-email: Konstantin Borovik <kb@lab5.ca>
@@ -38,8 +38,9 @@ uv tool install acumatica-cli
 
 acu config init --host erp.example.com my-erp
 cd my-erp                                # edit .env: set ACU_PASSWORD
+                                         # keep ACU_API_VERSION in sync with target.yaml
 
-acu config check                         # read-only preflight
+acu config check                         # read-only preflight (incl. target.yaml)
 acu tenant create --id 3 --login DEV     # create the tenant + bootstrap it (needs SSH)
 acu --tenant DEV apply                   # seed bootstrap/, baseline/, setup/
 acu --tenant DEV diff                    # prove zero drift (exit 2 on drift)
@@ -79,9 +80,9 @@ acu [--tenant NAME] [--url URL] [--ssh USER@HOST] [--api-version V]
 ├── schema [--out DIR]                dump the endpoint's OpenAPI schema (swagger.json)
 │
 └── config                            configuration ops
-    ├── init [--host HOST] [DIR]      scaffold a data repo (.env plus example YAML)
+    ├── init [--host HOST] [DIR]      scaffold a data repo (.env, target.yaml, example YAML)
     ├── show                          print the resolved config as a complete .env
-    └── check                         read-only preflight: discovery, secrets, REST, SSH
+    └── check [--strict]              preflight: discovery, secrets, target, REST, endpoints, SSH
 ```
 
 `apply` and `diff` called without FILES default to the scaffolded directories, in order: `bootstrap/`, then `baseline/`, then `setup/`.
@@ -93,20 +94,36 @@ Run `acu <command> --help` for details on any command.
 
 Your configuration lives in its own git repo. `acu config init` scaffolds everything except `scenario/`, which you author by hand:
 
-| Path         | What it holds                                                              |
-| ------------ | -------------------------------------------------------------------------- |
-| `bootstrap/` | what makes a virgin tenant configurable: features, company, credit terms   |
-| `baseline/`  | reference data: subaccounts, chart of accounts, ledger, units of measure   |
-| `setup/`     | one-time actions: financial year, master calendar, open periods            |
-| `scenario/`  | transaction scenarios for `acu run`: purchase, build, sell flows            |
-| `.env`       | where to apply and who signs in, every key an `ACU_*` variable             |
+| Path          | What it holds                                                              |
+| ------------- | -------------------------------------------------------------------------- |
+| `bootstrap/`  | what makes a virgin tenant configurable: features, company, credit terms   |
+| `baseline/`   | reference data: subaccounts, chart of accounts, ledger, units of measure   |
+| `setup/`      | one-time actions: financial year, master calendar, open periods            |
+| `scenario/`   | transaction scenarios for `acu run`: purchase, build, sell flows            |
+| `target.yaml` | committed verified matrix: `erp` + `default_api` (what, not where)         |
+| `.env`        | where to apply and who signs in, every key an `ACU_*` variable             |
 
-Files in each directory apply alphabetically; the numbered prefixes (`10-`, `20-`, and so on) encode dependency order. The scaffolded `.gitignore` keeps `.env` out of git — store it encrypted (for example as `.env.gpg`) and decrypt once per clone.
+Files in each directory apply alphabetically; the numbered prefixes (`10-`, `20-`, and so on) encode dependency order.
+The scaffolded `.gitignore` keeps `.env` out of git — store it encrypted (for example as `.env.gpg`) and decrypt once per clone.
+Commit `target.yaml` with the seeds so every clone knows the verified ERP line and Default API generation.
 
 Seed YAML in `bootstrap/`, `baseline/`, and `setup/` is state: `apply` upserts it, `diff` proves it.
 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 a scenario re-runs safely on a warm tenant.
 
+### Seed `endpoint:` symbols
+
+Dual-served entities (on both Bootstrap and Default) need an explicit `endpoint:` line.
+
+| Value | Resolves to |
+| ----- | ----------- |
+| omitted | `Default/<ACU_API_VERSION>` for Default-only entities |
+| `bootstrap` | active `Bootstrap/<ver>` from `bootstrap/project.xml` or the packaged contract |
+| `default` | `Default/<ACU_API_VERSION>` — tracks the operator API version |
+| `Bootstrap/1.9.0` or `Default/25.200.001` | literal pin (ignores `ACU_API_VERSION` for Default) |
+
+Prefer symbolic `default` over a pinned `Default/25.200.001` so the seed tree travels with the configured API generation.
+
 ## Installation
 
 Requires Python 3.14 or newer.
@@ -125,16 +142,32 @@ Verify with `acu --version`.
 
 ## Configuration
 
-Everything lives in one `.env` file: *where* to apply and *who* signs in. Three values are required; everything else has a code default matching a stock Acumatica install:
+Everything lives in one `.env` file: *where* to apply and *who* signs in.
+Three values are required; everything else has a code default matching a stock Acumatica install:
 
 ```sh
 ACU_BASE_URL=http://acu-dev1.vm.internal/AcumaticaERP  # required: REST root
 ACU_TENANT=LAB5                                        # sign-in name of the tenant API sessions use
 ACU_SSH=Administrator@acu-dev1.vm.internal             # optional: control-plane user@host (tenant CRUD)
+ACU_API_VERSION=25.200.001                             # Default contract version half only
 ACU_USER=admin                                         # optional, defaults to admin
 ACU_PASSWORD=...                                       # required for live commands
 ```
 
+`ACU_API_VERSION` is the version half only (`25.200.001`), never `Default/25.200.001`.
+A full path would nest as `/entity/Default/Default/...`.
+
+The committed `target.yaml` next to `.env` declares the verified matrix (what, not where):
+
+```yaml
+erp: "26.101.0225"           # claimed product line/build (README-level detail)
+default_api: "25.200.001"    # must match ACU_API_VERSION
+```
+
+When `target.yaml` is present, `apply` / `diff` / `run` / `extract` / `schema` / `bootstrap` hard-fail if `default_api` does not match the configured API version.
+`acu config check` reports the same match as a probe line.
+Missing `target.yaml` only warns on check unless you pass `--strict`.
+
 Worth knowing:
 
 - The file is found by walking up from the current directory, so any subdirectory of the data repo works.
@@ -143,13 +176,15 @@ Worth knowing:
 - Leave it blank on hosted instances; only `acu tenant` needs it.
 - Nothing is derived: split-horizon DNS, port forwards, and jump hosts are all handled by writing the address you actually want into the address keys.
 - `acu config show` prints the fully resolved configuration as a complete, valid `.env` — every knob visible, the password excluded.
+- When `target.yaml` is present, `config show` also comments `erp` / `default_api`.
 - Redirect it to turn resolved state into a working config: `acu config show > .env`.
 
 Verify before touching anything live:
 
 ```sh
-acu config check       # read-only preflight: discovery, secrets, REST, SSH
-acu apply --dry-run    # show what would be written, write nothing
+acu config check           # discovery, secrets, target, REST, endpoints, SSH
+acu config check --strict  # missing target.yaml becomes fail
+acu apply --dry-run        # show what would be written, write nothing
 ```
 
 ## Control and Data Planes

{acumatica_cli-0.9.0 → acumatica_cli-0.10.0}/README.md

@@ -21,8 +21,9 @@ uv tool install acumatica-cli
 
 acu config init --host erp.example.com my-erp
 cd my-erp                                # edit .env: set ACU_PASSWORD
+                                         # keep ACU_API_VERSION in sync with target.yaml
 
-acu config check                         # read-only preflight
+acu config check                         # read-only preflight (incl. target.yaml)
 acu tenant create --id 3 --login DEV     # create the tenant + bootstrap it (needs SSH)
 acu --tenant DEV apply                   # seed bootstrap/, baseline/, setup/
 acu --tenant DEV diff                    # prove zero drift (exit 2 on drift)
@@ -62,9 +63,9 @@ acu [--tenant NAME] [--url URL] [--ssh USER@HOST] [--api-version V]
 ├── schema [--out DIR]                dump the endpoint's OpenAPI schema (swagger.json)
 │
 └── config                            configuration ops
-    ├── init [--host HOST] [DIR]      scaffold a data repo (.env plus example YAML)
+    ├── init [--host HOST] [DIR]      scaffold a data repo (.env, target.yaml, example YAML)
     ├── show                          print the resolved config as a complete .env
-    └── check                         read-only preflight: discovery, secrets, REST, SSH
+    └── check [--strict]              preflight: discovery, secrets, target, REST, endpoints, SSH
 ```
 
 `apply` and `diff` called without FILES default to the scaffolded directories, in order: `bootstrap/`, then `baseline/`, then `setup/`.
@@ -76,20 +77,36 @@ Run `acu <command> --help` for details on any command.
 
 Your configuration lives in its own git repo. `acu config init` scaffolds everything except `scenario/`, which you author by hand:
 
-| Path         | What it holds                                                              |
-| ------------ | -------------------------------------------------------------------------- |
-| `bootstrap/` | what makes a virgin tenant configurable: features, company, credit terms   |
-| `baseline/`  | reference data: subaccounts, chart of accounts, ledger, units of measure   |
-| `setup/`     | one-time actions: financial year, master calendar, open periods            |
-| `scenario/`  | transaction scenarios for `acu run`: purchase, build, sell flows            |
-| `.env`       | where to apply and who signs in, every key an `ACU_*` variable             |
+| Path          | What it holds                                                              |
+| ------------- | -------------------------------------------------------------------------- |
+| `bootstrap/`  | what makes a virgin tenant configurable: features, company, credit terms   |
+| `baseline/`   | reference data: subaccounts, chart of accounts, ledger, units of measure   |
+| `setup/`      | one-time actions: financial year, master calendar, open periods            |
+| `scenario/`   | transaction scenarios for `acu run`: purchase, build, sell flows            |
+| `target.yaml` | committed verified matrix: `erp` + `default_api` (what, not where)         |
+| `.env`        | where to apply and who signs in, every key an `ACU_*` variable             |
 
-Files in each directory apply alphabetically; the numbered prefixes (`10-`, `20-`, and so on) encode dependency order. The scaffolded `.gitignore` keeps `.env` out of git — store it encrypted (for example as `.env.gpg`) and decrypt once per clone.
+Files in each directory apply alphabetically; the numbered prefixes (`10-`, `20-`, and so on) encode dependency order.
+The scaffolded `.gitignore` keeps `.env` out of git — store it encrypted (for example as `.env.gpg`) and decrypt once per clone.
+Commit `target.yaml` with the seeds so every clone knows the verified ERP line and Default API generation.
 
 Seed YAML in `bootstrap/`, `baseline/`, and `setup/` is state: `apply` upserts it, `diff` proves it.
 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 a scenario re-runs safely on a warm tenant.
 
+### Seed `endpoint:` symbols
+
+Dual-served entities (on both Bootstrap and Default) need an explicit `endpoint:` line.
+
+| Value | Resolves to |
+| ----- | ----------- |
+| omitted | `Default/<ACU_API_VERSION>` for Default-only entities |
+| `bootstrap` | active `Bootstrap/<ver>` from `bootstrap/project.xml` or the packaged contract |
+| `default` | `Default/<ACU_API_VERSION>` — tracks the operator API version |
+| `Bootstrap/1.9.0` or `Default/25.200.001` | literal pin (ignores `ACU_API_VERSION` for Default) |
+
+Prefer symbolic `default` over a pinned `Default/25.200.001` so the seed tree travels with the configured API generation.
+
 ## Installation
 
 Requires Python 3.14 or newer.
@@ -108,16 +125,32 @@ Verify with `acu --version`.
 
 ## Configuration
 
-Everything lives in one `.env` file: *where* to apply and *who* signs in. Three values are required; everything else has a code default matching a stock Acumatica install:
+Everything lives in one `.env` file: *where* to apply and *who* signs in.
+Three values are required; everything else has a code default matching a stock Acumatica install:
 
 ```sh
 ACU_BASE_URL=http://acu-dev1.vm.internal/AcumaticaERP  # required: REST root
 ACU_TENANT=LAB5                                        # sign-in name of the tenant API sessions use
 ACU_SSH=Administrator@acu-dev1.vm.internal             # optional: control-plane user@host (tenant CRUD)
+ACU_API_VERSION=25.200.001                             # Default contract version half only
 ACU_USER=admin                                         # optional, defaults to admin
 ACU_PASSWORD=...                                       # required for live commands
 ```
 
+`ACU_API_VERSION` is the version half only (`25.200.001`), never `Default/25.200.001`.
+A full path would nest as `/entity/Default/Default/...`.
+
+The committed `target.yaml` next to `.env` declares the verified matrix (what, not where):
+
+```yaml
+erp: "26.101.0225"           # claimed product line/build (README-level detail)
+default_api: "25.200.001"    # must match ACU_API_VERSION
+```
+
+When `target.yaml` is present, `apply` / `diff` / `run` / `extract` / `schema` / `bootstrap` hard-fail if `default_api` does not match the configured API version.
+`acu config check` reports the same match as a probe line.
+Missing `target.yaml` only warns on check unless you pass `--strict`.
+
 Worth knowing:
 
 - The file is found by walking up from the current directory, so any subdirectory of the data repo works.
@@ -126,13 +159,15 @@ Worth knowing:
 - Leave it blank on hosted instances; only `acu tenant` needs it.
 - Nothing is derived: split-horizon DNS, port forwards, and jump hosts are all handled by writing the address you actually want into the address keys.
 - `acu config show` prints the fully resolved configuration as a complete, valid `.env` — every knob visible, the password excluded.
+- When `target.yaml` is present, `config show` also comments `erp` / `default_api`.
 - Redirect it to turn resolved state into a working config: `acu config show > .env`.
 
 Verify before touching anything live:
 
 ```sh
-acu config check       # read-only preflight: discovery, secrets, REST, SSH
-acu apply --dry-run    # show what would be written, write nothing
+acu config check           # discovery, secrets, target, REST, endpoints, SSH
+acu config check --strict  # missing target.yaml becomes fail
+acu apply --dry-run        # show what would be written, write nothing
 ```
 
 ## Control and Data Planes

{acumatica_cli-0.9.0 → acumatica_cli-0.10.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "acumatica-cli"
-version = "0.9.0"
+version = "0.10.0"
 description = "Acumatica ERP Config-as-Code: tenant provisioning, baseline config, and reference data"
 authors = [{ name = "Konstantin Borovik", email = "kb@lab5.ca" }]
 readme = "README.md"

{acumatica_cli-0.9.0 → acumatica_cli-0.10.0}/src/acumatica_cli/cli.py

@@ -22,6 +22,7 @@ from .config import (
     read_env_values,
     scaffold,
 )
+from .target import assert_target_compatible, load_target
 from .tenant import TenantManager
 
 
@@ -370,6 +371,7 @@ def bootstrap_cmd(ctx: click.Context, export_path: Path | None) -> None:
         output.success(f"wrote {export_path}")
         return
     inst = _resolve_instance(ctx)
+    assert_target_compatible(inst)
     if not inst.tenant:
         raise SystemExit(
             "tenant not set (pass --tenant, "
@@ -433,29 +435,45 @@ def config_show(inst: Instance) -> None:
     so the printed values are exactly what a live command would trust -
     global flag overrides (--url, --ssh, ...) included. The password is
     never emitted in any form (V2): no ACU_PASSWORD key, no value.
-    Redirect to a file and edit: the output loads back through
-    load_instance unchanged, the password supplied out of band.
+    When target.yaml is present, surfaces erp/default_api as comments
+    (mismatch noted, still exit 0 — no hard gate). Redirect to a file and
+    edit: the output loads back through load_instance unchanged, the
+    password supplied out of band.
     """
     output.data("# resolved by `acu config show` - a complete .env")
     output.data("# ACU_PASSWORD comes from .env or the environment, never from here")
     for field, value in inst.model_dump(exclude={"password"}).items():
         output.data(f"ACU_{field.upper()}={value}")
+    target = load_target()
+    if target is not None:
+        output.data(f"# target.yaml: erp={target.erp} default_api={target.default_api}")
+        if target.default_api != inst.api_version:
+            output.data(
+                f"# warn: default_api={target.default_api} != "
+                f"ACU_API_VERSION={inst.api_version}"
+            )
 
 
 @config_group.command("check")
+@click.option(
+    "--strict",
+    is_flag=True,
+    help="Promote warn classes (missing target.yaml) to fail",
+)
 @click.pass_context
-def config_check(ctx: click.Context) -> None:
-    """Read-only preflight of the resolved target, one ok/fail line per probe.
+def config_check(ctx: click.Context, strict: bool) -> None:
+    """Read-only preflight of the resolved target, one ok/fail/warn/skip line.
 
     Dependency order: discovery (.env walk-up + parse + ACU_BASE_URL), then
-    secrets (ACU_PASSWORD resolved), then REST (login, landed-tenant verify,
-    logout) and ssh probed independently - ssh set → trivial remote; ssh
-    unset → skip (ACU_SSH optional, V3 hosted path), never fail. A discovery
-    or secrets failure stops; a REST failure still probes ssh when set and
-    vice versa. Discovery is lax (V3): no .env passes when --url covers
-    base_url, and flags-only runs (no .env anywhere) are valid. Writes
-    nothing: no PUTs, no tenant CRUD. Exit 0 when every non-skipped probe
-    passes, 1 on any failure.
+    secrets (ACU_PASSWORD resolved), then local target.yaml probe, then REST
+    (login, landed-tenant verify, logout) and ssh probed independently -
+    ssh set → trivial remote; ssh unset → skip (ACU_SSH optional, V3 hosted
+    path), never fail. A discovery or secrets failure stops; a REST failure
+    still probes ssh when set and vice versa. Discovery is lax (V3): no
+    .env passes when --url covers base_url, and flags-only runs (no .env
+    anywhere) are valid. Writes nothing: no PUTs, no tenant CRUD. Exit 0
+    when no fail line (warns allowed); --strict promotes missing target to
+    fail; exit 1 on any failure.
     """
     overrides: dict[str, str] = ctx.obj or {}
     # discovery (V3): lax walk-up + parse; base_url (the primary identity
@@ -493,13 +511,15 @@ def config_check(ctx: click.Context) -> None:
     # both live probes run through the exact objects live commands use, so
     # a pass here proves the real code path, not a parallel one
     inst = _resolve_instance(ctx)
-    failed = False
+    failed = _probe_target(root, inst, strict=strict)
     try:
         # entering the client is the whole probe: login + landed-tenant
-        # verify (V5), and the context manager guarantees logout (V6)
-        with AcumaticaClient(inst):
-            pass
-        output.data(f"ok rest ({inst.base_url}, tenant {inst.tenant})")
+        # verify (V5), and the context manager guarantees logout (V6);
+        # endpoints probe (T74) reuses the same session when login succeeds
+        with AcumaticaClient(inst) as client:
+            output.data(f"ok rest ({inst.base_url}, tenant {inst.tenant})")
+            if not _probe_endpoints(client, inst):
+                failed = True
     except (RuntimeError, httpx.HTTPError) as exc:
         output.data(f"fail rest: {exc}")
         failed = True
@@ -517,6 +537,68 @@ def config_check(ctx: click.Context) -> None:
         raise SystemExit(1)
 
 
+def _probe_target(root: Path | None, inst: Instance, *, strict: bool) -> bool:
+    """Emit the local target probe line; return True when it failed (V27).
+
+    Invalid target hard-exits (any loader). Missing under data root warns
+    unless --strict. No data root → skip. Match → ok (erp claimed-only).
+    """
+    try:
+        target = load_target(root)
+    except SystemExit as exc:
+        output.data(f"fail target: {exc}")
+        raise SystemExit(1) from exc
+    if root is None:
+        output.data("skip target (no data root)")
+        return False
+    if target is None:
+        msg = (
+            f"target: no target.yaml under {root} - dataset verified matrix "
+            "unknown; add target.yaml (see acu config init) or pass --strict "
+            "to require it"
+        )
+        output.data(f"{'fail' if strict else 'warn'} {msg}")
+        return strict
+    if target.default_api != inst.api_version:
+        output.data(
+            f"fail target: dataset default_api={target.default_api} vs "
+            f"configured {inst.api_version}"
+        )
+        return True
+    output.data(
+        f"ok target (default_api={target.default_api} matches configured; "
+        f"erp={target.erp} claimed)"
+    )
+    # T76: no stable HTTP ERP-build discovery (V12) — keep erp claimed-only;
+    # skip rather than invent SSH/sqlcmd (control-plane exclusion, V1)
+    output.data(f"skip erp (live probe not available; claimed {target.erp})")
+    return False
+
+
+def _probe_endpoints(client: AcumaticaClient, inst: Instance) -> bool:
+    """Emit endpoints probe; return True on pass, False on fail (V12/V27).
+
+    Exact match: a Default entry whose version half equals
+    ``Instance.api_version``. Fail-closed when GET /entity is unparseable.
+    """
+    want = f"Default/{inst.api_version}"
+    try:
+        endpoints = client.list_endpoints()
+    except (RuntimeError, httpx.HTTPError) as exc:
+        output.data(f"fail endpoints: {exc}")
+        return False
+    defaults = [v for name, v in endpoints if name == "Default"]
+    if inst.api_version in defaults:
+        output.data(f"ok endpoints ({want} present)")
+        return True
+    present = ", ".join(f"Default/{v}" for v in defaults) or "(none)"
+    output.data(
+        f"fail endpoints: configured {want} not listed; "
+        f"present Default versions: {present}"
+    )
+    return False
+
+
 SEED_DIRS = ("bootstrap", "baseline", "setup")
 
 
@@ -571,6 +653,7 @@ def apply_cmd(inst: Instance, files: tuple[Path, ...], dry_run: bool) -> None:
     they default to the data repo's existing init-scaffolded directories in
     fixed order: bootstrap/, baseline/, setup/.
     """
+    assert_target_compatible(inst)
     with AcumaticaClient(inst) as client:
         for path in expand_files(files or default_seed_dirs()):
             baseline = seed.load_baseline(path)
@@ -596,6 +679,7 @@ def schema_cmd(inst: Instance, out_dir: Path | None) -> None:
     The schema is the authoritative field-level reference for the exact
     build - regenerate rather than version (the file is ~3 MB).
     """
+    assert_target_compatible(inst)
     if out_dir is None:
         out_dir = data_root() / "schemas"
     out_file = out_dir / f"swagger-Default-{inst.api_version}.json"
@@ -623,6 +707,7 @@ def diff_cmd(inst: Instance, files: tuple[Path, ...]) -> None:
     they default to the data repo's existing init-scaffolded directories in
     fixed order: bootstrap/, baseline/, setup/.
     """
+    assert_target_compatible(inst)
     paths = expand_files(files or default_seed_dirs())
     drifts: list[str] = []
     with AcumaticaClient(inst) as client:
@@ -659,6 +744,7 @@ def run_cmd(inst: Instance, files: tuple[Path, ...], dry_run: bool) -> None:
     last, so a scenario re-runs safely on a warm tenant. Exit 0 when every
     expectation holds, 1 on any step error or expectation miss.
     """
+    assert_target_compatible(inst)
     if not files:
         default = data_root() / "scenario"
         if not default.is_dir():
@@ -731,6 +817,7 @@ def extract_cmd(
     when every row wrote or skipped clean, 1 when any row failed - drift
     detection stays with diff.
     """
+    assert_target_compatible(inst)
     with AcumaticaClient(inst) as client:
         failed = extract.run(
             client,

{acumatica_cli-0.9.0 → acumatica_cli-0.10.0}/src/acumatica_cli/client.py

@@ -62,6 +62,49 @@ def unwrap(entity: dict[str, Any]) -> dict[str, Any]:
     return out
 
 
+def parse_entity_list(response: httpx.Response) -> list[tuple[str, str]]:
+    """Parse ``GET /entity`` into ``[(name, version), ...]`` (fail-closed).
+
+    Vendor contract shape (Acumatica help + docs/rest-api.md): a JSON array
+    of objects with ``name`` and ``version`` strings. Unparseable body →
+    RuntimeError with status, content-type, and a short raw hint so a
+    shape change is re-verified (V12) rather than silently skipped.
+    """
+    try:
+        body = response.json()
+    except Exception as exc:
+        hint = response.text[:200].replace("\n", " ")
+        raise RuntimeError(
+            "GET /entity response not parseable as endpoint list "
+            f"(status {response.status_code}; "
+            f"content-type {response.headers.get('content-type', '?')}; "
+            f"first 200 chars: {hint})"
+        ) from exc
+    if not isinstance(body, list) or not body:
+        hint = str(body)[:200]
+        raise RuntimeError(
+            "GET /entity response not parseable as endpoint list "
+            f"(status {response.status_code}; expected non-empty JSON array; "
+            f"first 200 chars: {hint})"
+        )
+    out: list[tuple[str, str]] = []
+    for item in body:
+        if not isinstance(item, dict):
+            raise RuntimeError(
+                "GET /entity response not parseable as endpoint list "
+                f"(row is not an object: {item!r})"
+            )
+        name = item.get("name")
+        version = item.get("version")
+        if not isinstance(name, str) or not isinstance(version, str):
+            raise RuntimeError(
+                "GET /entity response not parseable as endpoint list "
+                f"(row missing string name/version: {item!r})"
+            )
+        out.append((name, version))
+    return out
+
+
 # The list GET's optimized-export failure (B9): the contract API's list GET
 # 500s with this marker when any field in scope maps to a BQL-delegate view.
 # The one error read paths retry around (seed.diff via the key-URL GET,
@@ -93,6 +136,9 @@ class AcumaticaClient:
         self._http = httpx.Client(
             base_url=instance.base_url, timeout=timeout, transport=transport
         )
+        # V5/B24: first successful Company PUT this session → one re-login
+        # so later branch selectors resolve; warm re-PUT is re-login-safe
+        self._refreshed_after_company = False
 
     def __enter__(self) -> AcumaticaClient:
         # tenant guard (V5, docs/rest-api.md): an omitted or empty tenant is
@@ -105,27 +151,10 @@ class AcumaticaClient:
                 "an explicit tenant silently lands on the default tenant; "
                 "set ACU_TENANT in .env or pass --tenant"
             )
-        creds: dict[str, str] = {
-            "name": self.instance.user,
-            "password": self.instance.password,
-            "tenant": self.instance.tenant,
-        }
-        self._checked(self._http.post("/entity/auth/login", json=creds))
-        # tenant guard, landed side (V5, B5): login accepting the name proves
-        # nothing - a stale tenant map reroutes named logins to the default
-        # tenant, and a single-tenant instance accepts ANY name (both verified
-        # live, docs/rest-api.md). Verify where the session actually landed
-        # and refuse on mismatch; logout first, since __exit__ never runs
-        # when __enter__ raises (V6 - sessions count against the license).
+        # logout first on failure: __exit__ never runs when __enter__ raises
+        # (V6 - sessions count against the license)
         try:
-            landed = self._landed_tenant()
-            if landed.casefold() != self.instance.tenant.casefold():
-                raise RuntimeError(
-                    f"tenant guard: asked for tenant {self.instance.tenant!r} "
-                    f"but the session landed on {landed!r} - the instance "
-                    "tenant map is stale or the tenant does not exist; check "
-                    "acu tenant list and recycle the app pool"
-                )
+            self._login()
         except BaseException:
             self.__exit__()
             raise
@@ -138,6 +167,50 @@ class AcumaticaClient:
         finally:
             self._http.close()
 
+    def _login(self) -> None:
+        """POST login + refuse on landed-tenant mismatch (V5, B5).
+
+        Login accepting the name proves nothing - a stale tenant map
+        reroutes named logins to the default tenant, and a single-tenant
+        instance accepts ANY name (both verified live, docs/rest-api.md).
+        """
+        creds: dict[str, str] = {
+            "name": self.instance.user,
+            "password": self.instance.password,
+            "tenant": self.instance.tenant,
+        }
+        self._checked(self._http.post("/entity/auth/login", json=creds))
+        landed = self._landed_tenant()
+        if landed.casefold() != self.instance.tenant.casefold():
+            raise RuntimeError(
+                f"tenant guard: asked for tenant {self.instance.tenant!r} "
+                f"but the session landed on {landed!r} - the instance "
+                "tenant map is stale or the tenant does not exist; check "
+                "acu tenant list and recycle the app pool"
+            )
+
+    def relogin(self) -> None:
+        """Drop the cookie session and open a new one without closing transport.
+
+        Mid-session Company create leaves branch selectors empty until a
+        fresh login (V5, B24). Unlike ``__exit__``, the httpx client stays
+        open so the outer context manager still owns the session lifecycle.
+        """
+        # empty body → Content-Length: 0 (V6 / IIS 411)
+        self._http.post("/entity/auth/logout", content=b"")
+        self._login()
+
+    def refresh_after_company(self) -> None:
+        """Re-login once after the first successful Company PUT this session.
+
+        Warm-tenant Company re-PUT is re-login-safe (V5); further Company
+        records in the same run skip the second bounce.
+        """
+        if self._refreshed_after_company:
+            return
+        self.relogin()
+        self._refreshed_after_company = True
+
     def _landed_tenant(self) -> str:
         """The tenant this session actually landed on (login name).
 
@@ -160,9 +233,20 @@ class AcumaticaClient:
         return html.unescape(m.group(1))
 
     def _url(self, entity: str, endpoint: str | None = None) -> str:
-        # V11: versioned path only; the endpoint-name half is hardcoded
-        # Default - custom endpoints arrive per call (seed `endpoint:`)
-        return f"/entity/{endpoint or f'Default/{self.instance.api_version}'}/{entity}"
+        # V11: versioned path only. Omitted or symbolic "default" (V20) →
+        # Default/<Instance.api_version> so dual-serve seeds track the
+        # configured API generation; literals pass through unchanged.
+        if endpoint is None or endpoint == "default":
+            endpoint = f"Default/{self.instance.api_version}"
+        return f"/entity/{endpoint}/{entity}"
+
+    def list_endpoints(self) -> list[tuple[str, str]]:
+        """Authenticated ``GET /entity`` → ``[(name, version), ...]`` (V12).
+
+        Fail-closed on unparseable body — see ``parse_entity_list``.
+        """
+        r = self._checked(self._http.get("/entity"))
+        return parse_entity_list(r)
 
     @staticmethod
     def _checked(r: httpx.Response) -> httpx.Response:

{acumatica_cli-0.9.0 → acumatica_cli-0.10.0}/src/acumatica_cli/config.py

@@ -34,6 +34,7 @@ DB_NAME = "AcumaticaDB"
 INIT_TEMPLATES = (
     ("env", ".env"),
     ("gitignore", ".gitignore"),
+    ("target", "target.yaml"),
     ("baseline/10-subaccounts.yaml", "baseline/10-subaccounts.yaml"),
     ("baseline/20-accounts.yaml", "baseline/20-accounts.yaml"),
     ("baseline/40-ledger.yaml", "baseline/40-ledger.yaml"),
@@ -93,8 +94,20 @@ class Instance(BaseSettings):
 
     @field_validator("api_version")
     @classmethod
-    def _no_surrounding_slashes(cls, v: str) -> str:
-        return v.strip("/")
+    def _api_version_half_only(cls, v: str) -> str:
+        # V11: version half only (e.g. 25.200.001). A full path like
+        # Default/25.200.001 would nest as /entity/Default/Default/...
+        v = v.strip().strip("/")
+        if not v:
+            raise ValueError(
+                "api_version must be the version half only (e.g. 25.200.001)"
+            )
+        if "/" in v or v.lower().startswith("default"):
+            raise ValueError(
+                "api_version must be the version half only "
+                f"(e.g. 25.200.001), not a path like Default/{v}"
+            )
+        return v
 
 
 def scaffold(directory: Path, host: str | None = None) -> Iterator[tuple[str, Path]]:

{acumatica_cli-0.9.0 → acumatica_cli-0.10.0}/src/acumatica_cli/extract.py

@@ -141,7 +141,7 @@ def _fetch(client: AcumaticaClient, spec: EntitySpec) -> list[dict[str, Any]]:
     A manifest filter rides both list reads, so the two paths serve the
     same record set and the per-key walk only visits filtered keys.
     """
-    endpoint = resolve_endpoint(spec.endpoint)
+    endpoint = resolve_endpoint(spec.endpoint, api_version=client.instance.api_version)
     narrowed = {"$filter": spec.filter} if spec.filter else {}
     try:
         return client.get_list(spec.entity, params=narrowed or None, endpoint=endpoint)
@@ -418,7 +418,9 @@ class _Extraction:
             # the active package does not serve cannot be read - skip clean
             # rather than 404 (full company surface lives in the data-repo
             # contract; minimal packaged fallback has config-init only).
-            resolved = resolve_endpoint(spec.endpoint)
+            resolved = resolve_endpoint(
+                spec.endpoint, api_version=self.client.instance.api_version
+            )
             if resolved == active_name and spec.entity not in active_entities:
                 self._skip(target, "entity not in active Bootstrap contract")
                 continue

{acumatica_cli-0.9.0 → acumatica_cli-0.10.0}/src/acumatica_cli/seed.py

@@ -60,7 +60,7 @@ from pydantic import Field, ValidationError, field_validator, model_validator
 
 from . import bootstrap, output
 from .client import OPTIMIZATION_500, AcumaticaClient, unwrap
-from .config import Instance, find_data_root
+from .config import find_data_root
 from .models import Model, validation_summary
 
 # Packaged-fallback defaults (no data-repo contract). Prefer active_bootstrap()
@@ -68,10 +68,15 @@ from .models import Model, validation_summary
 BOOTSTRAP_ENDPOINT, BOOTSTRAP_ENTITIES = bootstrap.parse_endpoint(
     bootstrap.packaged_contract_xml()
 )
-# The code-default instance endpoint, for the V20 error message - read off
-# the Instance field default rather than hand-synced (V11: one spelling).
-_DEFAULT_ENDPOINT: str = f"Default/{Instance.model_fields['api_version'].default}"
+# Dual-serve error text prefers the symbolic Default form (V20) so operators
+# do not read the code-default version as their configured ACU_API_VERSION.
+_DEFAULT_ENDPOINT_NAME = "Default"
 _SYMBOLIC_BOOTSTRAP = "bootstrap"
+_SYMBOLIC_DEFAULT = "default"
+# Mid-session branch-selector failure (V5/B24): virgin-tenant apply opens
+# the REST session pre-Company; INPreferences TransitBranchID (and kin)
+# 500 with this message until a fresh login sees the new branch.
+_BRANCH_EMPTY = "'Branch' cannot be empty"
 
 
 def active_bootstrap(root: Path | None = None) -> tuple[str, frozenset[str]]:
@@ -86,10 +91,30 @@ def active_bootstrap(root: Path | None = None) -> tuple[str, frozenset[str]]:
     return bootstrap.parse_endpoint(bootstrap.load_contract_xml(root))
 
 
-def resolve_endpoint(endpoint: str | None, root: Path | None = None) -> str | None:
-    """Map symbolic ``bootstrap`` to the active ``Bootstrap/<ver>`` (V20)."""
+def resolve_endpoint(
+    endpoint: str | None,
+    root: Path | None = None,
+    *,
+    api_version: str | None = None,
+) -> str | None:
+    """Map symbolic endpoint names to versioned paths (V20).
+
+    ``bootstrap`` → active ``Bootstrap/<ver>`` from contract XML (load-time
+    what). ``default`` → ``Default/<api_version>``; ``api_version`` required
+    when endpoint is default. Other values pass through (literals or None).
+
+    Apply/diff primarily resolve symbolic default in ``client._url``; this
+    helper serves extract pre-HTTP path building and offline unit tests.
+    """
     if endpoint == _SYMBOLIC_BOOTSTRAP:
         return active_bootstrap(root)[0]
+    if endpoint == _SYMBOLIC_DEFAULT:
+        if not api_version:
+            raise SystemExit(
+                "endpoint: default requires a configured api_version "
+                "(ACU_API_VERSION or --api-version)"
+            )
+        return f"{_DEFAULT_ENDPOINT_NAME}/{api_version}"
     return endpoint
 
 
@@ -186,6 +211,8 @@ def load_baseline(path: Path) -> BaselineFile | ActionFile:
 
     Symbolic ``endpoint: bootstrap`` resolves to the active package version
     at load (data-repo contract when present, else packaged minimal — V20).
+    Symbolic ``endpoint: default`` stays on the model and resolves at HTTP
+    time via ``client._url`` (never load-rewritten — version is where).
     An entity the active Bootstrap contract serves still needs an explicit
     endpoint (literal or symbolic); silent Default-endpoint PUTs are the
     B8 class.
@@ -204,10 +231,10 @@ def load_baseline(path: Path) -> BaselineFile | ActionFile:
         parsed = parsed.model_copy(update={"endpoint": name})
     elif parsed.endpoint is None and parsed.entity in entities:
         raise SystemExit(
-            f"{path}: entity '{parsed.entity}' is served by both the instance "
-            f"default endpoint ({_DEFAULT_ENDPOINT}) and the active "
-            f"{name} - add an explicit 'endpoint:' line to pick one "
-            f"(literal or symbolic 'bootstrap')"
+            f"{path}: entity '{parsed.entity}' is served by both "
+            f"Default (use endpoint: default -> Default/<ACU_API_VERSION>) "
+            f"and the active {name} - add an explicit 'endpoint:' line to "
+            f"pick one (literal or symbolic 'bootstrap' | 'default')"
         )
     return parsed
 
@@ -303,6 +330,10 @@ def apply(
 ) -> int:
     """PUT every record (upsert by key); an action file invokes its action.
 
+    After the first successful Company PUT this session, re-login once so
+    branch selectors resolve for later files (V5/B24). A PUT that still
+    500s with ``'Branch' cannot be empty`` gets one re-login + retry.
+
     Returns the record count.
     """
     if isinstance(baseline, ActionFile):
@@ -315,11 +346,30 @@ def apply(
             body = record
             if any(isinstance(v, list) for v in record.values()):
                 body = _with_detail_ids(client, baseline, record)
-            client.put(baseline.entity, body, endpoint=baseline.endpoint)
+            _put(client, baseline.entity, body, baseline.endpoint)
+            if baseline.entity == "Company":
+                client.refresh_after_company()
             output.data(f"  PUT {baseline.entity} [{label}]")
     return len(baseline.records)
 
 
+def _put(
+    client: AcumaticaClient,
+    entity: str,
+    body: dict[str, Any],
+    endpoint: str | None,
+) -> None:
+    """PUT one record; one re-login + retry on branch-empty 500 (V5/B24)."""
+    try:
+        client.put(entity, body, endpoint=endpoint)
+    except RuntimeError as err:
+        if _BRANCH_EMPTY not in str(err):
+            raise
+        output.info(f"re-login and retry {entity} (branch empty)")
+        client.relogin()
+        client.put(entity, body, endpoint=endpoint)
+
+
 def _with_detail_ids(
     client: AcumaticaClient, baseline: BaselineFile, record: dict[str, Any]
 ) -> dict[str, Any]:

acumatica_cli-0.10.0/src/acumatica_cli/target.py

@@ -0,0 +1,100 @@
+"""Dataset target matrix: committed verified ERP + Default API versions (V27).
+
+``target.yaml`` is *what* (V2) — co-located with the data-repo root found by
+``.env`` discovery. Never secrets. Present → hard-match ``default_api`` to
+``Instance.api_version`` on allowlisted data-plane cmds and ``config check``;
+missing → warn on check unless ``--strict``; invalid → hard-fail any loader.
+"""
+
+from pathlib import Path
+
+import yaml
+from pydantic import ValidationError, field_validator
+
+from .config import Instance, find_data_root
+from .models import Model, validation_summary
+
+TARGET_FILENAME = "target.yaml"
+
+
+class DatasetTarget(Model):
+    """Committed verified target for a data repo (V2 what — never secrets)."""
+
+    erp: str  # claimed product line/build; live compare only when a probe exists
+    default_api: str  # Default contract version half only (e.g. 25.200.001)
+
+    @field_validator("default_api")
+    @classmethod
+    def _api_version_half_only(cls, v: str) -> str:
+        v = v.strip().strip("/")
+        if not v:
+            raise ValueError(
+                "default_api must be the version half only (e.g. 25.200.001)"
+            )
+        if "/" in v or v.lower().startswith("default"):
+            raise ValueError(
+                "default_api must be the version half only "
+                f"(e.g. 25.200.001), not a path like Default/{v}"
+            )
+        return v
+
+    @field_validator("erp")
+    @classmethod
+    def _erp_nonempty(cls, v: str) -> str:
+        v = v.strip()
+        if not v:
+            raise ValueError("erp must be a non-empty build id (e.g. 26.101.0225)")
+        return v
+
+
+def find_target_path(root: Path | None = None) -> Path | None:
+    """``{data-root}/target.yaml`` when the file exists; else None."""
+    root = root if root is not None else find_data_root()
+    if root is None:
+        return None
+    path = root / TARGET_FILENAME
+    return path if path.is_file() else None
+
+
+def load_target(root: Path | None = None) -> DatasetTarget | None:
+    """Return DatasetTarget, None if absent, or SystemExit on unreadable/invalid.
+
+    Invalid file is always a hard error for any caller that loads it — never
+    silently ignored on apply while only failing on config check (V27).
+    """
+    path = find_target_path(root)
+    if path is None:
+        return None
+    try:
+        with open(path) as f:
+            data = yaml.safe_load(f)
+    except OSError as exc:
+        raise SystemExit(f"{path}: cannot read target.yaml: {exc}") from exc
+    if data is None:
+        raise SystemExit(f"{path}: target.yaml is empty")
+    if not isinstance(data, dict):
+        raise SystemExit(f"{path}: expected a mapping at the top level")
+    try:
+        return DatasetTarget.model_validate(data)
+    except ValidationError as exc:
+        raise SystemExit(f"{path}: {validation_summary(exc)}") from exc
+
+
+def assert_target_compatible(inst: Instance, root: Path | None = None) -> None:
+    """Hard-fail when target.yaml present and default_api mismatches api_version.
+
+    Missing target is not an error here (config check --strict owns that).
+    Invalid target always SystemExit. Call only from the allowlisted
+    data-plane commands (V27) — never from bare pass_instance.
+    """
+    target = load_target(root)
+    if target is None:
+        return
+    if target.default_api != inst.api_version:
+        raise SystemExit(
+            "Default API version mismatch:\n"
+            f"  dataset target (target.yaml): default_api={target.default_api}\n"
+            f"  configured (ACU_API_VERSION/--api-version): {inst.api_version}\n"
+            f"Fix: set ACU_API_VERSION={target.default_api} to match this "
+            f"dataset, or use a dataset verified for {inst.api_version}."
+        )

{acumatica_cli-0.9.0 → acumatica_cli-0.10.0}/src/acumatica_cli/templates/env

@@ -4,6 +4,9 @@
 # ACU_BASE_URL (REST root) is required; ACU_SSH (control-plane user@host)
 # is optional - leave blank for hosted / data-plane-only (tenant CRUD still
 # needs it). The rest are code defaults you can override here.
+# ACU_API_VERSION is the Default contract version half only (e.g. 25.200.001),
+# never "Default/25.200.001". Must match target.yaml default_api when that
+# file exists (see acu config check).
 # Keep this file out of git (the scaffolded .gitignore already lists it;
 # encrypt at rest, e.g. .env.gpg).
 ACU_BASE_URL=http://erp.example.com/AcumaticaERP

acumatica_cli-0.10.0/src/acumatica_cli/templates/target

@@ -0,0 +1,6 @@
+# scaffolded by `acu config init` — verified target matrix for this dataset.
+# Edit when you re-verify against a new ERP build or Default API generation.
+# default_api is the version half only (ACU_API_VERSION spelling), not Default/<ver>.
+# Must match ACU_API_VERSION / --api-version (default 25.200.001) or live cmds fail.
+erp: "26.101.0225"
+default_api: "25.200.001"