Trace-forward node: Days 1-4 (recursive traversal, regions, authority gates, Tier 3 disclosure)

.env.example

@@ -2,4 +2,8 @@ export DATABASE_URL="YOUR DB LINK"
 export world_shp_file_PATH="./shapefiles/99bfd9e7-bb42-4728-87b5-07f8c8ac631c2020328-1-1vef4ev.lu5nk.shp"
 export JWKS_URL="http://127.0.0.1:8000/.well-known/jwks.json"
 #Only need for running test_api.py test cases
-export TESTKIT_DIR = "YOUR PATH FOR KEYS"
+export TESTKIT_DIR = "YOUR PATH FOR KEYS"
+
+export AR2_INTERNAL_SHARED_SECRET="<YOUR_SHARED_SECRET>"
+export AR_TRUSTED_AUTHORITY_PUBKEY="<PATH_TO_AUTHORITY_PUBKEY_PEM>"
+export AR_TRUSTED_ISSUER_PUBKEY="<PATH_TO_ISSUER_PUBKEY_PEM>"

.github/workflows/ci.yml

@@ -0,0 +1,56 @@
+name: AR2 CI
+
+on: [push, pull_request]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.12'
+    - name: Lint
+      run: |
+        pip install ruff
+        ruff check app
+
+  test:
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres:15
+        env:
+          POSTGRES_USER: postgres
+          POSTGRES_PASSWORD: password
+          POSTGRES_DB: test_db
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.12'
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -r requirements.txt
+        pip install pytest
+
+    - name: Run tests
+      env:
+        DATABASE_URL: "postgresql://postgres:password@localhost:5432/test_db"
+      run: |
+        PYTHONPATH=. pytest app/tests/
+
+

README.md

@@ -6,9 +6,13 @@ It stores high-resolution field boundary geometries and verifies field access cr
 1. **The Hub routes but never authorizes**: The `ar2-hub` gateway forwards requests, but the Node is the ultimate authority that verifies the cryptographic grant.
 2. **L1 requires a grant credential**: High-resolution spatial data (Level 1 Masking) is never exposed without a valid ODRL JWT credential. The owner of the field is automatically the first grantee.
 
+### Key Features
+* **Identity Resolution Engine**: Prevents duplicated fields in the global registry. If a farm is registered twice (overlapping by a configurable `threshold`, defaulting to 95%), the node seamlessly aliases the new registration to the existing `Geo Id`. Furthermore, it supports hierarchical **`child_of`** relationship mapping for sub-plots completely contained within a larger farm boundary.
+* **Trace-Back and Trace-Forward**: Content-derived **ListArtifacts** (Merkle-root `ListID`s over GeoIDs, nested lists, and regions) and **RegionArtifacts** (`RegionID`s over an S2 cover, from WKT or member fields) turn the registry into a recall graph. Neither direction is open: the **node** verifies the caller's credential on every query. Trace-back (product to fields) requires a grant for the product being traced; **trace-forward** (a contaminated field to every downstream product) additionally requires a Hub-issued capability and seed authorization, and revealing downstream *identities* requires an accredited authority credential and is audited. See [TRACEABILITY.md](./TRACEABILITY.md) for the full reasoning, a worked cyclospora recall example, and a contrast with existing traceability platforms.
+
 ## Architecture
 
-Please see [ARCHITECTURE.md](./ARCHITECTURE.md) for a detailed diagram of the Hub-Node-Pancake flow and a deeper dive into the DPI Trust architecture.
+Please see [ARCHITECTURE.md](./ARCHITECTURE.md) for a detailed diagram of the Hub-Node-Pancake flow and a deeper dive into the DPI Trust architecture. For the recall/traceability model built on top of it, see [TRACEABILITY.md](./TRACEABILITY.md).
 
 ## Quickstart (10 Minutes to Run)
 
@@ -58,6 +62,12 @@ Follow these steps to run the Node locally alongside the `ar2-hub` and `Pancake`
 | `GET`  | `/fetch-field-wkt/{geoid}` | Returns L1 high-resolution geometry. | Yes (Grant) |
 | `GET`  | `/fetch-field-centroid/{geoid}` | Returns exact centroid of a field. | Yes (Grant) |
 | `GET`  | `/geoid/{geoid}/eudr-export` | Exports an EUDR-compliant GeoJSON artifact. | Yes (Grant) |
+| `POST` | `/list-artifact` | Registers a content-derived list (a lot/case/pallet/retail item) over GeoIDs, nested lists (`L:`), or regions (`R:`). Append-only. | Yes (Hub JWT) |
+| `POST` | `/region-artifact` | Registers a content-derived region from a WKT boundary (no acreage cap) or from member GeoIDs/lists. | Yes (Hub JWT) |
+| `GET`  | `/list-artifact/{list_id}` | Returns the members of a list artifact. | Yes (Hub JWT) |
+| `GET`  | `/list-artifact/reverse/{geoid}` | Trace-forward: every list/region containing a GeoID, climbed recursively to terminal products. | Yes (Hub JWT + `trace-forward` capability + seed authorization; accredited authority credential for the identity tier) |
+
+See [TRACEABILITY.md](./TRACEABILITY.md) for how these endpoints compose into trace-back and trace-forward.
 
 ## Testing
 
@@ -66,3 +76,13 @@ To run the automated test suite (which overrides the JWKS hub auth for isolation
 ```bash
 python -m pytest app/tests/test_api.py -v
 ```
+
+## Automated End-to-End Demos
+
+There are two separate end-to-end demo scripts, each covering a different capability. Both require the Hub and Pancake servers to be running locally.
+
+1. **Grant Lifecycle (`./demo_e2e.sh`)**
+   Covers the full lifecycle of a standard field grant (registration, issuance, retrieving L1 geometry, verification, and revocation).
+
+2. **Trace-forward (`./scripts/e2e_traceforward.sh`)**
+   Covers the trace-forward recursive graph capability. It registers fields, builds a supply chain list structure, issues an authority credential, and then performs trace-forward queries to demonstrate Tier 1 vs Tier 3 identity disclosure rules, including negative assertions for missing or revoked authority.