gowalk-cicd 1.0.0

package/action/scripts/lookup_app_id.py

@@ -0,0 +1,51 @@
+#!/usr/bin/env python3
+"""
+Resolve the App Store Connect numeric app id for a bundle id.
+
+Environment:
+    ASC_KEY_ID     - API key ID
+    ASC_ISSUER_ID  - API issuer ID
+    ASC_KEY_PATH   - Path to the .p8 key file
+    BUNDLE_ID      - Application bundle identifier
+
+Prints the app id to stdout on success. On 0 or >1 matches, exits 1 with a
+guidance message on stderr.
+"""
+
+from __future__ import annotations
+
+import os
+
+from asc_common import get_json, make_jwt
+from cfg_io import fail
+
+
+def env(name: str) -> str:
+    val = os.environ.get(name)
+    if not val:
+        fail(f"missing env var: {name}")
+    return val
+
+
+def main() -> None:
+    bundle_id = env("BUNDLE_ID")
+    token = make_jwt(env("ASC_KEY_ID"), env("ASC_ISSUER_ID"), env("ASC_KEY_PATH"))
+    data = get_json("/apps", token, params={"filter[bundleId]": bundle_id, "limit": "10"})
+    apps = data.get("data", [])
+    if not apps:
+        fail(
+            f"No ASC app found for bundleId={bundle_id}. "
+            "Run `fastlane create_app_ios` once manually to register the app, "
+            "or set app.app_store_apple_id in ci.config.yaml."
+        )
+    if len(apps) > 1:
+        ids = ", ".join(a.get("id", "?") for a in apps)
+        fail(
+            f"Multiple ASC apps match bundleId={bundle_id} (ids: {ids}). "
+            "Set app.app_store_apple_id in ci.config.yaml to disambiguate."
+        )
+    print(apps[0]["id"])
+
+
+if __name__ == "__main__":
+    main()

package/action/scripts/manage_marketing_version.py

@@ -0,0 +1,337 @@
+#!/usr/bin/env python3
+"""
+Resolve the App Store Connect version slot for this run.
+
+The project's MARKETING_VERSION build setting is the single source of truth
+for the marketing version. CI does not bump it. This script finds-or-creates
+the App Store Connect (ASC) row matching that exact version, and only the
+build number is bumped automatically (see next_build_number.py).
+
+Algorithm:
+  1. Read MARKETING_VERSION from env (set by action.yml from
+     xcodebuild -showBuildSettings or PlistBuddy).
+  2. Floor-check (non-strict): target >= combined floor across
+     appStoreVersions + preReleaseVersions + builds->preReleaseVersion.
+  3. If the target row already exists in /appStoreVersions:
+       - any non-editable match (terminal/blocking) -> SystemExit(2);
+         the slot is taken by a shipped or in-review row.
+       - editable-only match -> REUSE its id (steady-state TestFlight
+         iteration at unchanged MARKETING_VERSION).
+  4. CREATE path: floor-check (strict, target > floor); PATCH-rename any
+     stale editable to target; or POST a new row.
+
+This module is intentionally thin: floor logic lives in
+``mmv_floor_check``; CREATE wiring (POST/PATCH-rename, stale-editable
+detection) lives in ``mmv_decide_create``. Both submodules re-bind back
+through this one so test patches at ``mmv.<seam>`` keep winning.
+
+Env: ASC_KEY_ID, ASC_ISSUER_ID, ASC_KEY_PATH, APP_STORE_APPLE_ID,
+     MARKETING_VERSION (project source of truth, set by action.yml).
+Stdout: {"decision":"REUSE|CREATE","versionString":"...","appStoreVersionId":"..."}
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+
+from asc_common import (
+    BLOCKING_STATES,
+    IN_REVIEW_STATES,
+    REUSABLE_STATES,
+    TERMINAL_STATES,
+    make_jwt,
+)
+
+from mmv_floor_check import (
+    BUILD_SETTING_SOURCES,
+    MIGRATION_HINT,
+    SEM_RE,
+    assert_target_meets_floor,
+    bump_patch_for_message,
+    fetch_versions,
+    get_combined_floor,
+    get_ground_truth_floor,
+    maybe_auto_bump,
+    semver_tuple,
+)
+from mmv_decide_create import (
+    create_or_reuse,
+    create_or_reuse_with_stale,
+    create_version,
+    decide_create,
+)
+
+# Re-export the public seams so tests that patch ``mmv.<name>`` keep
+# working. The submodules look these up through this module at call
+# time, so a patch on ``mmv.fetch_versions`` propagates correctly.
+__all__ = (
+    "SEM_RE",
+    "create_or_reuse",
+    "create_version",
+    "decide_for_version",
+    "env",
+    "fetch_versions",
+    "get_combined_floor",
+    "get_ground_truth_floor",
+    "main",
+    "make_jwt",
+    "semver_tuple",
+)
+
+
+_APP_ID_MISSING_HINT = (
+    "::error::APP_STORE_APPLE_ID is empty. This usually means auto-detect "
+    "could not resolve PRODUCT_BUNDLE_IDENTIFIER from your Xcode project "
+    "(check the auto-detect: ... log lines in the 'Resolve credentials + "
+    "auto-detect' step above). Fix options: (1) commit your .xcodeproj or "
+    "add an xcodegen project.yml; (2) pass `app-store-apple-id:` explicitly "
+    "via the action's `with:` block."
+)
+
+_MARKETING_VERSION_MISSING_HINT = (
+    "::error::MARKETING_VERSION env var is missing or invalid. The "
+    "action.yml step that reads it from xcodebuild -showBuildSettings "
+    "(or PlistBuddy fallback) must set it before this script runs. "
+    + MIGRATION_HINT
+)
+
+
+def _log(msg: str) -> None:
+    print(f"[decision] {msg}", file=sys.stderr)
+
+
+def _result(decision: str, version: str, vid: str, state: str = "") -> dict:
+    out = {
+        "decision": decision,
+        "versionString": version,
+        "appStoreVersionId": vid,
+    }
+    if state:
+        out["state"] = state
+    return out
+
+
+def env(name: str) -> str:
+    val = os.environ.get(name)
+    if not val:
+        if name == "APP_STORE_APPLE_ID":
+            msg = _APP_ID_MISSING_HINT
+        elif name == "MARKETING_VERSION":
+            msg = _MARKETING_VERSION_MISSING_HINT
+        else:
+            msg = f"::error::Missing required env var: {name}"
+        print(msg, file=sys.stderr)
+        raise SystemExit(1)
+    return val
+
+
+def _validate_target(target_version: str) -> None:
+    """SystemExit(1) when target is not a parseable semver."""
+    if SEM_RE.match(target_version or ""):
+        return
+    print(
+        f"::error::MARKETING_VERSION {target_version!r} is not a "
+        f"valid semantic version (expected MAJOR.MINOR[.PATCH]). "
+        f"Set MARKETING_VERSION in " + BUILD_SETTING_SOURCES + ". "
+        + MIGRATION_HINT,
+        file=sys.stderr,
+    )
+    raise SystemExit(1)
+
+
+def _classify_match_at_target(
+    versions: list[dict], target: str,
+) -> tuple[str, dict | None, bool]:
+    """Classify rows at ``target`` -> ``(status, match, also_editable)``.
+
+    Status values: ``"none"`` (no match -> CREATE), ``"reuse"`` (editable
+    -> REUSE its id), ``"terminal"`` (settled, slot locked -- caller may
+    auto-roll), ``"in_review"`` (under Apple Review or awaiting dev
+    release click -- caller MUST reject), ``"unknown"`` (matched but
+    state is in NO allowlist -- caller MUST reject; round 12 fail-closed
+    so an unfamiliar ASC state can't silently 409 on CREATE). The state
+    taxonomy lives in ``asc_common.py`` next to the constant set
+    definitions; positive allowlists (round 11) replaced the historical
+    ``not in EDITABLE_STATES`` test that misclassified
+    PENDING_DEVELOPER_RELEASE as terminal."""
+    matches = [v for v in versions if v.get("versionString") == target]
+    if not matches:
+        return "none", None, False
+    in_review = [
+        v for v in matches
+        if v.get("state") in IN_REVIEW_STATES
+        or v.get("state") in BLOCKING_STATES
+    ]
+    if in_review:
+        return "in_review", in_review[0], False
+    terminal = [v for v in matches if v.get("state") in TERMINAL_STATES]
+    if terminal:
+        return "terminal", terminal[0], len(matches) > 1
+    reusable = [v for v in matches if v.get("state") in REUSABLE_STATES]
+    if reusable:
+        return "reuse", reusable[0], False
+    # Round 12: matches exist but no state is recognized -- fail closed.
+    return "unknown", matches[0], len(matches) > 1
+
+
+def _reject_match(
+    target: str, match: dict, *,
+    also_editable: bool = False, unknown: bool = False,
+) -> None:
+    """Reject a non-reusable match at ``target``. When ``unknown`` is
+    True the matched row's ASC state is in none of our allowlists --
+    bail rather than guess (round 12: silently CREATEing would 409;
+    silently REUSEing could interfere with whatever Apple is doing
+    with the row). Otherwise this is the historical terminal-collision
+    rejection path."""
+    state, vid = match.get("state", ""), match.get("id", "")
+    if unknown:
+        print(
+            f"::error::MARKETING_VERSION {target} exists in App Store "
+            f"Connect in unrecognized state {state!r} (id={vid}); "
+            f"bailing rather than guessing whether to REUSE or CREATE. "
+            f"Update mmv classifier (asc_common.TERMINAL_STATES / "
+            f"IN_REVIEW_STATES / BLOCKING_STATES / REUSABLE_STATES) to "
+            f"cover {state!r}, or bump MARKETING_VERSION manually to a "
+            f"fresh value in your project's build settings ("
+            + BUILD_SETTING_SOURCES + "). " + MIGRATION_HINT,
+            file=sys.stderr,
+        )
+        raise SystemExit(2)
+    suffix = (
+        " (an editable row at the same versionString also exists)"
+        if also_editable else ""
+    )
+    print(
+        f"::error::MARKETING_VERSION {target} already exists in App "
+        f"Store Connect in state {state} (id={vid}){suffix}. REUSE/CREATE "
+        f"both require a fresh marketing version. Bump MARKETING_VERSION "
+        f"in your project's build settings (" + BUILD_SETTING_SOURCES +
+        "). " + MIGRATION_HINT,
+        file=sys.stderr,
+    )
+    raise SystemExit(2)
+
+
+def _reject_in_review_match(target: str, match: dict) -> None:
+    """Issue 13: REUSE/CREATE must NOT touch a row Apple is reviewing
+    OR a row awaiting the developer's manual release click
+    (PENDING_DEVELOPER_RELEASE). Both states require human action;
+    auto-rolling past them would either race App Review or bypass the
+    developer's release decision."""
+    state, vid = match.get("state", ""), match.get("id", "")
+    if state == "PENDING_DEVELOPER_RELEASE":
+        situation = (
+            "is approved by App Review and awaiting your manual release. "
+            "Either release the existing build via App Store Connect, or"
+        )
+    else:
+        situation = (
+            "is currently in App Review and cannot be modified. Either "
+            "wait for review to complete, or"
+        )
+    print(
+        f"::error::MARKETING_VERSION {target} exists in App Store Connect "
+        f"in state {state} (id={vid}). The version {situation} "
+        f"bump MARKETING_VERSION to a fresh value in your project's "
+        f"build settings (" + BUILD_SETTING_SOURCES + "). "
+        + MIGRATION_HINT,
+        file=sys.stderr,
+    )
+    raise SystemExit(2)
+
+
+def _auto_roll_past_locked(
+    target_version: str, versions: list[dict],
+) -> tuple[str, str, dict | None, bool]:
+    """Try to auto-roll past a TERMINAL row at target.
+
+    Classifies the row(s) at target. When the match is terminal
+    (READY_FOR_SALE / PROCESSING_FOR_APP_STORE / PENDING_APPLE_RELEASE
+    etc.), fires ``maybe_auto_bump`` to advance the project's
+    MARKETING_VERSION to the next patch and re-classifies against the
+    rolled value. When auto-bump is disabled (policy='none') or the
+    write target is unreachable, returns the original locked
+    classification so the caller can surface the historical
+    SystemExit(2) rejection.
+
+    DESIGN DECISION: in-review collisions (WAITING_FOR_REVIEW /
+    IN_REVIEW / PENDING_DEVELOPER_RELEASE) are deliberately NOT
+    auto-rolled. Apple is either actively reviewing the row at
+    ``target`` or has approved it and is waiting on the developer's
+    manual release click; advancing the project to a new version would
+    either submit a competing build while review is in flight or
+    bypass the developer's release decision -- both states require
+    human action. The historical SystemExit(2) rejection at these
+    states surfaces the conflict loudly so a human can resolve it.
+
+    Returns ``(effective_target, status, match, also_editable)``."""
+    status, match, also_editable = _classify_match_at_target(
+        versions, target_version,
+    )
+    if status != "terminal":
+        return target_version, status, match, also_editable
+    rolled = maybe_auto_bump(target_version, target_version)
+    if rolled is None or rolled == target_version:
+        return target_version, status, match, also_editable
+    _log(f"auto-roll: {target_version} is {match.get('state', '')}, "
+         f"advancing project to {rolled}")
+    new_status, new_match, new_also = _classify_match_at_target(
+        versions, rolled,
+    )
+    return rolled, new_status, new_match, new_also
+
+
+def decide_for_version(
+    target_version: str, versions: list[dict],
+    app_id: str, token: str,
+) -> dict:
+    """Find-or-create the ASC row at exactly ``target_version``.
+
+    Validates semver, runs the non-strict floor check (auto-bump
+    rewrites MARKETING_VERSION when below the ASC floor; the returned
+    effective target is what downstream uses), then classifies any
+    row(s) at target. Terminal collisions auto-roll to the next patch
+    (or reject when policy='none'); in-review and unknown-state
+    collisions reject loudly (see ``_classify_match_at_target`` for
+    the full taxonomy). No match -> CREATE; reusable editable -> REUSE."""
+    _validate_target(target_version)
+    target_version = assert_target_meets_floor(
+        target_version, app_id, token,
+        appstore_versions=versions, strict=False,
+    )
+    target_version, status, match, also_editable = _auto_roll_past_locked(
+        target_version, versions,
+    )
+    if status == "terminal":
+        _reject_match(target_version, match, also_editable=also_editable)
+    if status == "in_review":
+        _reject_in_review_match(target_version, match)
+    if status == "unknown":
+        _reject_match(target_version, match, unknown=True)
+    if status == "none":
+        return decide_create(target_version, versions, app_id, token)
+    vid = match.get("id", "")
+    state = match.get("state", "")
+    _log(f"decision=REUSE versionString={target_version} "
+         f"(matches MARKETING_VERSION; state={state}, id={vid})")
+    return _result("REUSE", target_version, vid, state)
+
+
+def main() -> None:
+    key_id = env("ASC_KEY_ID")
+    issuer_id = env("ASC_ISSUER_ID")
+    key_path = env("ASC_KEY_PATH")
+    app_id = env("APP_STORE_APPLE_ID")
+    target_version = env("MARKETING_VERSION")
+
+    token = make_jwt(key_id, issuer_id, key_path)
+    versions = fetch_versions(app_id, token)
+    result = decide_for_version(target_version, versions, app_id, token)
+    print(json.dumps(result))
+
+
+if __name__ == "__main__":
+    main()

package/action/scripts/metadata_constants.py

@@ -0,0 +1,102 @@
+#!/usr/bin/env python3
+"""
+Shared constants and tiny helpers for AI-driven App Store metadata automation.
+
+Used by asc_metadata_detector.py, asc_metadata_applier.py, app_context_scanner.py
+and their tests. Keep this file small and dependency-free -- it is the contract
+between the read-side (detector), write-side (applier), and context scanner.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+
+
+def warn(msg: str) -> None:
+    """Emit a GitHub-Actions-formatted warning on stderr."""
+    print(f"::warning::{msg}", file=sys.stderr)
+
+
+def log(msg: str) -> None:
+    """Emit a plain stderr log line (not parsed by GitHub Actions)."""
+    print(msg, file=sys.stderr)
+
+
+def require_env(name: str) -> str:
+    """Return a non-empty env var or raise SystemExit with a GHA error line."""
+    value = os.environ.get(name, "").strip()
+    if not value:
+        raise SystemExit(f"::error::{name} env var is required")
+    return value
+
+
+# Fields owned by appInfoLocalizations (the "app-level" metadata resource).
+# These persist across version submissions -- editing them requires an
+# editable appInfo state (see EDITABLE_APP_INFO_STATES below).
+APP_LEVEL_FIELDS = ("name", "subtitle")
+
+# Fields owned by appStoreVersionLocalizations (per-version metadata).
+# Edited through the version slot resolved by manage_marketing_version.py.
+VERSION_LEVEL_FIELDS = (
+    "description",
+    "keywords",
+    "promotionalText",
+    "whatsNew",
+)
+
+# URL-typed metadata fields, grouped by owning resource. Never generated by AI,
+# never PATCHed by the applier, never reported by the detector as "empty".
+APP_LEVEL_URL_FIELDS = ("privacyPolicyUrl", "privacyChoicesUrl")
+VERSION_LEVEL_URL_FIELDS = ("supportUrl", "marketingUrl")
+
+# Unioned skip set used by both detector and applier as a single gate.
+SKIP_URL_FIELDS = frozenset(APP_LEVEL_URL_FIELDS + VERSION_LEVEL_URL_FIELDS)
+
+# Full per-resource field lists (editable + URL) as fetched from the ASC API.
+APP_INFO_LOC_FIELDS = APP_LEVEL_FIELDS + APP_LEVEL_URL_FIELDS
+VERSION_LOC_FIELDS = VERSION_LEVEL_FIELDS + VERSION_LEVEL_URL_FIELDS
+
+
+# Apple allows editing appInfoLocalizations only while the parent appInfo
+# record is in one of these states. Outside of these, the applier must
+# no-op (the API would reject the PATCH).
+#
+# Mirrors asc_common.EDITABLE_STATES but narrowed -- IN_REVIEW /
+# WAITING_FOR_REVIEW lock the appInfo resource even though they permit
+# some version-level edits.
+EDITABLE_APP_INFO_STATES = frozenset({
+    "PREPARE_FOR_SUBMISSION",
+    "REJECTED",
+    "METADATA_REJECTED",
+    "DEVELOPER_REJECTED",
+    "WAITING_FOR_REVIEW",
+})
+
+
+# App Store version states that accept PATCHes on appStoreVersionLocalizations
+# (description, keywords, promotionalText, whatsNew). Outside of these, Apple's
+# API returns 409 Conflict. Narrower than asc_common.EDITABLE_STATES -- we
+# exclude IN_REVIEW and INVALID_BINARY which reject localization edits.
+EDITABLE_VERSION_STATES = frozenset({
+    "PREPARE_FOR_SUBMISSION",
+    "DEVELOPER_REJECTED",
+    "METADATA_REJECTED",
+    "REJECTED",
+    "WAITING_FOR_REVIEW",
+    "READY_FOR_REVIEW",
+})
+
+
+# Per-field character caps enforced by Apple's App Store submission review.
+# IMPORTANT: these are CHARACTER counts (len(str)) not BYTE counts. Apple's
+# UI and API both measure by character, which matters for CJK locales
+# where one character is often 3+ UTF-8 bytes. Validate with len(value).
+CHAR_LIMITS = {
+    "name": 30,
+    "subtitle": 30,
+    "keywords": 100,
+    "description": 4000,
+    "promotionalText": 170,
+    "whatsNew": 4000,
+}

package/action/scripts/mmv_decide_create.py

@@ -0,0 +1,181 @@
+#!/usr/bin/env python3
+"""
+CREATE-path helpers for manage_marketing_version.
+
+This module owns the wiring that turns a target versionString into either
+a fresh /appStoreVersions POST or a PATCH-rename of a stale editable. The
+``_no_bump`` sentinel disarms ``asc_version_create.create_or_reuse``'s
+bump-retry loop because the project's MARKETING_VERSION is the single
+source of truth -- CI must never invent a new versionString.
+
+The ``_via_module`` helper provides a late-binding seam back through
+``manage_marketing_version`` so test patches at ``mmv.fetch_versions`` /
+``mmv.create_version`` keep winning even though the call originates here.
+"""
+
+from __future__ import annotations
+
+import sys
+
+from asc_common import EDITABLE_STATES, REUSABLE_STATES
+import asc_build_history
+import asc_version_create
+from mmv_floor_check import assert_target_meets_floor, semver_tuple
+
+
+def _no_bump(current: str) -> str:
+    """Default bump_fn: never bump. CI must not invent a marketing
+    version because the project's build setting is authoritative."""
+    print(
+        f"::error::POST /appStoreVersions returned 409 for {current}; "
+        f"ASC reports this versionString already exists but it was not "
+        f"visible in /appStoreVersions/preReleaseVersions/builds. "
+        f"Inspect the app in App Store Connect manually.",
+        file=sys.stderr,
+    )
+    raise SystemExit(4)
+
+
+def _via_module(name: str):
+    """Late-binding seam for tests that patch attributes on
+    ``manage_marketing_version``. Returns a wrapper that defers attribute
+    lookup to call time so ``mock.patch.object(mmv, name)`` keeps winning."""
+    def _call(*args, **kwargs):
+        import manage_marketing_version
+        return getattr(manage_marketing_version, name)(*args, **kwargs)
+    return _call
+
+
+def create_version(app_id: str, version: str, token: str):
+    return asc_version_create.create_version(app_id, version, token)
+
+
+def create_or_reuse(
+    app_id: str, version: str, token: str,
+    *, bump_fn=None,
+) -> str:
+    """POST a new version at exactly `version`. Caller passes a `bump_fn`
+    that disarms the bump-retry path by raising; this script never wants
+    a server-side bump because the project's MARKETING_VERSION is the
+    single source of truth."""
+    return create_or_reuse_with_stale(
+        app_id, version, token, bump_fn=bump_fn,
+    )
+
+
+def create_or_reuse_with_stale(
+    app_id: str, version: str, token: str,
+    *, bump_fn=None, stale_editable_id: str | None = None,
+) -> str:
+    """``create_or_reuse`` plus the optional stale-editable PATCH-rename
+    seam so ``decide_for_version`` can promote a leftover editable row at
+    a different versionString to the project's freshly-bumped target."""
+    return asc_version_create.create_or_reuse(
+        app_id, version, token,
+        bump_fn=bump_fn or _no_bump,
+        fetch_versions=_via_module("fetch_versions"),
+        fetch_prerelease_versions=asc_build_history.fetch_prerelease_versions,
+        fetch_builds_prerelease_versions=(
+            asc_build_history.fetch_builds_prerelease_versions
+        ),
+        post_fn=_via_module("create_version"),
+        stale_editable_id=stale_editable_id,
+        patch_fn=asc_version_create.patch_version,
+        delete_fn=asc_version_create.delete_version,
+    )
+
+
+def _refuse_downgrade(target: str, version_string: str, vid: str, state: str) -> None:
+    """Emit a SystemExit(2) error when an editable exists at versionString >= target.
+
+    PATCH-renaming a higher-or-equal editable would silently downgrade an
+    in-progress draft. The CREATE-path floor check does NOT catch this
+    because editable rows do not contribute to combined_floor."""
+    print(
+        f"::error::Cannot CREATE MARKETING_VERSION {target}: an "
+        f"editable App Store version exists at {version_string} "
+        f"(id={vid}, state={state}). Renaming a "
+        f"higher or equal-version editable would downgrade an "
+        f"in-progress draft. Either bump MARKETING_VERSION to "
+        f">= {version_string} in your project's build settings "
+        f"(project.yml [xcodegen], the .xcodeproj's "
+        f"MARKETING_VERSION xcconfig, or Info.plist's "
+        f"CFBundleShortVersionString), or manually delete or "
+        f"rename the existing draft in App Store Connect. "
+        f"See .github/actions/swift-app/MIGRATION.md "
+        f"for the migration procedure.",
+        file=sys.stderr,
+    )
+    raise SystemExit(2)
+
+
+def _stale_editable_id(versions: list[dict], target: str) -> str | None:
+    """Return the id of a REUSABLE row at a versionString strictly LESS
+    than target (a leftover lower-version draft to PATCH-rename onto the
+    project's freshly-bumped MARKETING_VERSION). Returns None when no
+    rename is needed.
+
+    SystemExit(2) when an editable exists at a versionString >= target:
+    PATCH-renaming it would silently downgrade an in-progress draft.
+    The CREATE-path floor check does NOT catch this because editable
+    rows do not contribute to combined_floor.
+
+    Issue 13: rows currently under Apple Review (WAITING_FOR_REVIEW /
+    IN_REVIEW) are EDITABLE in ASC's broad sense but mutating them would
+    interfere with the review process. They are still subject to the
+    >= target downgrade check (Issue 10 still applies), but they are
+    NOT candidates for PATCH-rename when version < target — the CREATE
+    path falls through to a plain POST instead, leaving the in-review
+    row alone."""
+    target_t = semver_tuple(target)
+    candidates: list[str] = []
+    for v in versions:
+        state = v.get("state")
+        if state not in EDITABLE_STATES:
+            continue
+        version_string = v.get("versionString") or ""
+        if version_string == target:
+            continue
+        vid = v.get("id")
+        if not vid:
+            continue
+        if semver_tuple(version_string) >= target_t:
+            _refuse_downgrade(target, version_string, vid, state)
+        # In-review rows (WAITING_FOR_REVIEW / IN_REVIEW) are editable
+        # but not safe to rename — leave them alone and POST a fresh row.
+        if state in REUSABLE_STATES:
+            candidates.append(vid)
+    return candidates[0] if candidates else None
+
+
+def decide_create(
+    target_version: str, versions: list[dict],
+    app_id: str, token: str,
+) -> dict:
+    """CREATE path: enforce strict floor, PATCH-rename any stale editable,
+    then POST. SystemExit(2) when target is not strictly above the floor.
+
+    Late-binds ``mmv.create_or_reuse_with_stale`` and ``mmv._result`` so
+    test patches at the parent module win."""
+    import manage_marketing_version as mmv
+    # The strict floor-check may also auto-bump (e.g. on a CREATE-path
+    # call where the project is below the floor and the non-strict
+    # pre-check did not fire because the prior caller skipped it). Use
+    # the returned value for all subsequent reasoning.
+    target_version = assert_target_meets_floor(
+        target_version, app_id, token,
+        appstore_versions=versions, strict=True,
+    )
+    stale_id = _stale_editable_id(versions, target_version)
+    new_id = mmv.create_or_reuse_with_stale(
+        app_id, target_version, token, stale_editable_id=stale_id,
+    )
+    if stale_id:
+        msg = (f"decision=CREATE versionString={target_version} "
+               f"(PATCH-rename of stale editable id={stale_id}) "
+               f"-> appStoreVersion id={new_id}")
+    else:
+        msg = (f"decision=CREATE versionString={target_version} "
+               f"-> appStoreVersion id={new_id}")
+    print(f"[decision] {msg}", file=sys.stderr)
+    return mmv._result("CREATE", target_version, new_id)