Tree Identity Contract
======================

Purpose
-------

This note defines the new client/server contract for customer-scoped tree
identity.

Operational rule
----------------

A job has two identifiers:
- ``job_number`` identifies the job
- ``tree_number`` identifies the tree for that customer

Multiple job numbers may refer to the same tree number.

Authoritative source
--------------------

The server is authoritative for ``tree_number``.

Rules:

- for server-created or assigned jobs, the tree number may already be set
- for phone-started jobs, the server resolves or allocates the tree number on
  the first accepted submit
- no GPS-based or fuzzy matching is used

Resolution rule
---------------

For a given customer:

- if a valid ``tree_number`` is supplied, reuse or create that tree identity
- otherwise allocate the next available tree number

Database model
--------------

- ``customers``
- ``trees``
- ``jobs``

Key constraints:

- ``trees`` are unique by ``(customer_id, tree_number)``
- ``jobs`` reference ``tree_id`` and also store ``tree_number`` for operational
  convenience

Client contract impact
----------------------

The client should treat ``tree_number`` as server-authoritative.

This means:

- the client may begin without a final tree number for a phone-started job
- after submit/review return, the client must accept and display the server
  value
- later jobs for the same tree may have different ``job_number`` values but the
  same ``tree_number``

Runtime API contract
--------------------

The live server now exposes tree identity through the operational job endpoints.

``POST /v1/jobs``
    Request accepts:

    - ``customer_name`` (optional but strongly preferred)
    - ``tree_number`` (optional provisional customer-scoped tree number)

    Response returns:

    - authoritative ``job_number``
    - authoritative ``tree_number``

``GET /v1/jobs/assigned``
    Each assigned job row includes ``tree_number``.

``GET /v1/jobs/{job_id}``
    Status payload includes ``tree_number``.

``POST /v1/jobs/{job_id}/rounds/{round_id}/submit``
    The server reads any provisional ``client_tree_details.tree_number`` in the
    submitted form, resolves the authoritative tree identity, writes that value
    back into the working form payload, and returns top-level ``tree_number`` in
    the submit response.

``GET /v1/jobs/{job_id}/rounds/{round_id}/review``
    Review payload includes top-level ``tree_number`` and the canonical
    ``client_tree_details.tree_number`` inside the returned form payload.

``POST /v1/jobs/{job_id}/rounds/{round_id}/reprocess``
    Reprocess response includes top-level ``tree_number``.

``POST /v1/jobs/{job_id}/final``
    Final submission resolves the authoritative tree identity one last time from
    the submitted form payload, writes it back into the finalized form, and then
    generates final artifacts.

Implementation status
---------------------

Current status:

- schema support added
- tree allocation helper added
- importer seeds tree identities from legacy final form data where available
- runtime job/create/status/review/submit/final paths now return or enforce the
  authoritative tree number