sort4circ-dpp 1.3.1__py3-none-any.whl

sort4circ_dpp/__init__.py

@@ -0,0 +1,30 @@
+"""Reference implementation of the SORT4CIRC DPP implementation profile.
+
+Two version numbers matter here and they are not the same thing:
+
+``__version__``
+    the version of this repository, package and GitHub release.
+``sort4circ_dpp.config.PROFILE_VERSION``
+    the version of the normative DPP implementation profile this code implements.
+    Individual specification assets are versioned per asset; see ``config``.
+
+Normative requirements apply only within that published profile. The specification
+originates in SORT4CIRC deliverable D4.3, "DPP Development Guidelines".
+"""
+
+from .canonical import canonicalise, digest, integrity_projection
+from .config import API_MAJOR, ONTOLOGY_VERSION, PROFILE_VERSION, RELEASE_VERSION, SCHEMA_VERSION
+
+#: Repository / package / release version. Not the normative profile version.
+__version__ = RELEASE_VERSION
+
+__all__ = [
+    "canonicalise",
+    "digest",
+    "integrity_projection",
+    "PROFILE_VERSION",
+    "SCHEMA_VERSION",
+    "ONTOLOGY_VERSION",
+    "API_MAJOR",
+    "__version__",
+]

sort4circ_dpp/_spec/access-matrix.json

@@ -0,0 +1,145 @@
+{
+  "$id": "https://data.sort4circ.eu/access-matrix/1.0.0",
+  "version": "1.0.0",
+  "released": "2026-08-10",
+  "policy": "defaultDeny",
+  "note": "Holding a scope is necessary and not sufficient. The view determines what the caller receives. A field the caller may know exists but not read is returned with valueStatus withheld.",
+  "roles": {
+    "public": {
+      "scopes": [
+        "dpp.read"
+      ],
+      "defaultView": "public"
+    },
+    "consumer": {
+      "scopes": [
+        "dpp.read"
+      ],
+      "defaultView": "public"
+    },
+    "brand": {
+      "scopes": [
+        "dpp.read",
+        "dpp.write",
+        "dpp.event",
+        "dpp.resolve",
+        "observation.write",
+        "integrity.read"
+      ],
+      "defaultView": "full"
+    },
+    "collector": {
+      "scopes": [
+        "dpp.read",
+        "dpp.event",
+        "dpp.resolve"
+      ],
+      "defaultView": "partner"
+    },
+    "sortingOperator": {
+      "scopes": [
+        "dpp.read",
+        "dpp.event",
+        "dpp.resolve",
+        "sorting.read"
+      ],
+      "defaultView": "sorting"
+    },
+    "pssrSystem": {
+      "scopes": [
+        "dpp.read",
+        "dpp.resolve",
+        "sorting.read",
+        "observation.write",
+        "dpp.event"
+      ],
+      "defaultView": "sorting"
+    },
+    "recycler": {
+      "scopes": [
+        "dpp.read",
+        "dpp.event",
+        "dpp.resolve"
+      ],
+      "defaultView": "recycler"
+    },
+    "authority": {
+      "scopes": [
+        "dpp.read",
+        "integrity.read",
+        "integrity.verify"
+      ],
+      "defaultView": "authority"
+    },
+    "administrator": {
+      "scopes": [
+        "dpp.read",
+        "dpp.write",
+        "dpp.event",
+        "dpp.resolve",
+        "sorting.read",
+        "observation.write",
+        "integrity.read",
+        "integrity.verify",
+        "admin"
+      ],
+      "defaultView": "full"
+    },
+    "integrityVerifier": {
+      "scopes": [
+        "dpp.read",
+        "integrity.read",
+        "integrity.verify"
+      ],
+      "defaultView": "integrityOnly"
+    }
+  },
+  "views": {
+    "public": [
+      "dppId",
+      "schemaVersion",
+      "recordVersion",
+      "status",
+      "identity.granularity",
+      "product.articleClass",
+      "product.fabricConstruction",
+      "product.technicalFlags",
+      "materialObservations"
+    ],
+    "partner": [
+      "public",
+      "identity.modelId",
+      "identity.batchId",
+      "lifecycleEvents.own"
+    ],
+    "sorting": [
+      "public",
+      "identity.itemId",
+      "identity.epc",
+      "product.colourPrimary",
+      "product.condition",
+      "sortingDecisions",
+      "carriers.active"
+    ],
+    "recycler": [
+      "sorting",
+      "components",
+      "product.mass"
+    ],
+    "authority": [
+      "sorting",
+      "recycler",
+      "lifecycleEvents",
+      "integrity",
+      "identity",
+      "carriers"
+    ],
+    "full": [
+      "*"
+    ],
+    "integrityOnly": [
+      "dppId",
+      "integrity"
+    ]
+  }
+}

sort4circ_dpp/_spec/reason-codes.json

@@ -0,0 +1,232 @@
+{
+  "$id": "https://data.sort4circ.eu/reason-codes/1.0.0",
+  "version": "1.0.0",
+  "released": "2026-08-10",
+  "note": "Reason codes are stable strings. A released code is never reworded or renumbered. Clients dispatch on the code, not on the title.",
+  "safeActions": {
+    "divert": "Route to the manual-review destination; engage no category-specific actuator.",
+    "divertAndAlert": "Divert and raise an operational alert.",
+    "retryOnceThenDivert": "One re-attempt after credential refresh, then divert.",
+    "noCommand": "Emit no new sorting command. Not an error.",
+    "rejectAtClient": "Not on the read path; the client corrects the request.",
+    "quarantine": "Hold the source row for operator review; never discard it.",
+    "noEffectOnSorting": "Sorting continues; evidence remains queued.",
+    "retrySameEvidenceId": "Retry using the same evidence identifier and digest.",
+    "reconcileBeforeResubmit": "Reconcile by evidence identifier before creating another transaction.",
+    "investigate": "A verification verdict, not an error response.",
+    "backOff": "Back off using the Retry-After header.",
+    "rereadAndReapply": "Re-read the current version and reapply the change. Never force the write."
+  },
+  "codes": [
+    {
+      "code": "S4C-IDENT-MALFORMED",
+      "httpStatus": 400,
+      "condition": "Identifier fails syntax or check-digit validation.",
+      "safeAction": "divert",
+      "type": "https://data.sort4circ.eu/problems/s4c-ident-malformed"
+    },
+    {
+      "code": "S4C-IDENT-UNKNOWN",
+      "httpStatus": 404,
+      "condition": "Well-formed identifier with no passport.",
+      "safeAction": "divert",
+      "type": "https://data.sort4circ.eu/problems/s4c-ident-unknown"
+    },
+    {
+      "code": "S4C-IDENT-RETIRED",
+      "httpStatus": 410,
+      "condition": "Passport retired; successor returned where present.",
+      "safeAction": "divert",
+      "type": "https://data.sort4circ.eu/problems/s4c-ident-retired"
+    },
+    {
+      "code": "S4C-IDENT-AMBIGUOUS",
+      "httpStatus": 409,
+      "condition": "More than one tag read within the zone window.",
+      "safeAction": "divert",
+      "type": "https://data.sort4circ.eu/problems/s4c-ident-ambiguous"
+    },
+    {
+      "code": "S4C-IDENT-DUPLICATE-BINDING",
+      "httpStatus": 409,
+      "condition": "One identifier resolves to two active passports.",
+      "safeAction": "divertAndAlert",
+      "type": "https://data.sort4circ.eu/problems/s4c-ident-duplicate-binding"
+    },
+    {
+      "code": "S4C-READ-SUPPRESSED-DUPLICATE",
+      "httpStatus": 200,
+      "condition": "Repeat read inside the suppression window.",
+      "safeAction": "noCommand",
+      "type": "https://data.sort4circ.eu/problems/s4c-read-suppressed-duplicate"
+    },
+    {
+      "code": "S4C-READ-WEAK-SIGNAL",
+      "httpStatus": 200,
+      "condition": "Read below the configured confidence floor.",
+      "safeAction": "divert",
+      "type": "https://data.sort4circ.eu/problems/s4c-read-weak-signal"
+    },
+    {
+      "code": "S4C-AUTH-MISSING-TOKEN",
+      "httpStatus": 401,
+      "condition": "No credential presented.",
+      "safeAction": "divertAndAlert",
+      "type": "https://data.sort4circ.eu/problems/s4c-auth-missing-token"
+    },
+    {
+      "code": "S4C-AUTH-INVALID-TOKEN",
+      "httpStatus": 401,
+      "condition": "Signature, issuer or audience invalid.",
+      "safeAction": "divertAndAlert",
+      "type": "https://data.sort4circ.eu/problems/s4c-auth-invalid-token"
+    },
+    {
+      "code": "S4C-AUTH-EXPIRED-TOKEN",
+      "httpStatus": 401,
+      "condition": "Token outside the stated validity window.",
+      "safeAction": "retryOnceThenDivert",
+      "type": "https://data.sort4circ.eu/problems/s4c-auth-expired-token"
+    },
+    {
+      "code": "S4C-AUTHZ-OPERATION-FORBIDDEN",
+      "httpStatus": 403,
+      "condition": "Caller lacks the required scope.",
+      "safeAction": "divertAndAlert",
+      "type": "https://data.sort4circ.eu/problems/s4c-authz-operation-forbidden"
+    },
+    {
+      "code": "S4C-AUTHZ-VIEW-FORBIDDEN",
+      "httpStatus": 403,
+      "condition": "Caller may not receive the requested view.",
+      "safeAction": "divertAndAlert",
+      "type": "https://data.sort4circ.eu/problems/s4c-authz-view-forbidden"
+    },
+    {
+      "code": "S4C-PAYLOAD-SCHEMA-INVALID",
+      "httpStatus": 422,
+      "condition": "Body fails schema validation; failing paths returned.",
+      "safeAction": "rejectAtClient",
+      "type": "https://data.sort4circ.eu/problems/s4c-payload-schema-invalid"
+    },
+    {
+      "code": "S4C-PAYLOAD-VOCAB-INVALID",
+      "httpStatus": 422,
+      "condition": "Coded value outside the declared vocabulary version.",
+      "safeAction": "rejectAtClient",
+      "type": "https://data.sort4circ.eu/problems/s4c-payload-vocab-invalid"
+    },
+    {
+      "code": "S4C-PAYLOAD-UNIT-INVALID",
+      "httpStatus": 422,
+      "condition": "Unit missing or not permitted for the quantity.",
+      "safeAction": "rejectAtClient",
+      "type": "https://data.sort4circ.eu/problems/s4c-payload-unit-invalid"
+    },
+    {
+      "code": "S4C-PAYLOAD-VERSION-UNSUPPORTED",
+      "httpStatus": 400,
+      "condition": "Schema version not served.",
+      "safeAction": "rejectAtClient",
+      "type": "https://data.sort4circ.eu/problems/s4c-payload-version-unsupported"
+    },
+    {
+      "code": "S4C-STATE-VERSION-CONFLICT",
+      "httpStatus": 412,
+      "condition": "If-Match does not equal the current record version.",
+      "safeAction": "rereadAndReapply",
+      "type": "https://data.sort4circ.eu/problems/s4c-state-version-conflict"
+    },
+    {
+      "code": "S4C-STATE-IDEMPOTENCY-CONFLICT",
+      "httpStatus": 409,
+      "condition": "Same idempotency key, different request body.",
+      "safeAction": "rejectAtClient",
+      "type": "https://data.sort4circ.eu/problems/s4c-state-idempotency-conflict"
+    },
+    {
+      "code": "S4C-STATE-APPEND-ONLY-VIOLATION",
+      "httpStatus": 422,
+      "condition": "Attempt to remove an append-only entry.",
+      "safeAction": "rejectAtClient",
+      "type": "https://data.sort4circ.eu/problems/s4c-state-append-only-violation"
+    },
+    {
+      "code": "S4C-STATE-NOT-FOUND",
+      "httpStatus": 404,
+      "condition": "The addressed resource does not exist.",
+      "safeAction": "rejectAtClient",
+      "type": "https://data.sort4circ.eu/problems/s4c-state-not-found"
+    },
+    {
+      "code": "S4C-MAP-NO-TARGET-RULE",
+      "httpStatus": 422,
+      "condition": "Source field has no approved mapping.",
+      "safeAction": "quarantine",
+      "type": "https://data.sort4circ.eu/problems/s4c-map-no-target-rule"
+    },
+    {
+      "code": "S4C-MAP-UNIT-CONVERSION-FAILED",
+      "httpStatus": 422,
+      "condition": "Conversion undefined or out of range.",
+      "safeAction": "quarantine",
+      "type": "https://data.sort4circ.eu/problems/s4c-map-unit-conversion-failed"
+    },
+    {
+      "code": "S4C-MAP-VOCAB-UNMAPPED",
+      "httpStatus": 422,
+      "condition": "Source term absent from the mapping table.",
+      "safeAction": "quarantine",
+      "type": "https://data.sort4circ.eu/problems/s4c-map-vocab-unmapped"
+    },
+    {
+      "code": "S4C-LEDGER-UNAVAILABLE",
+      "httpStatus": 503,
+      "condition": "Ledger endpoint unreachable.",
+      "safeAction": "noEffectOnSorting",
+      "type": "https://data.sort4circ.eu/problems/s4c-ledger-unavailable"
+    },
+    {
+      "code": "S4C-LEDGER-SUBMIT-REJECTED",
+      "httpStatus": 502,
+      "condition": "Transaction rejected by the network.",
+      "safeAction": "retrySameEvidenceId",
+      "type": "https://data.sort4circ.eu/problems/s4c-ledger-submit-rejected"
+    },
+    {
+      "code": "S4C-LEDGER-TIMEOUT-AFTER-BROADCAST",
+      "httpStatus": 504,
+      "condition": "Outcome unknown after broadcast.",
+      "safeAction": "reconcileBeforeResubmit",
+      "type": "https://data.sort4circ.eu/problems/s4c-ledger-timeout-after-broadcast"
+    },
+    {
+      "code": "S4C-LEDGER-DIGEST-MISMATCH",
+      "httpStatus": 200,
+      "condition": "Recomputed digest differs from the anchored value.",
+      "safeAction": "investigate",
+      "type": "https://data.sort4circ.eu/problems/s4c-ledger-digest-mismatch"
+    },
+    {
+      "code": "S4C-DEP-UNAVAILABLE",
+      "httpStatus": 503,
+      "condition": "A dependency needed for the operation is unavailable.",
+      "safeAction": "divert",
+      "type": "https://data.sort4circ.eu/problems/s4c-dep-unavailable"
+    },
+    {
+      "code": "S4C-RATE-LIMITED",
+      "httpStatus": 429,
+      "condition": "Caller exceeded the applicable quota.",
+      "safeAction": "backOff",
+      "type": "https://data.sort4circ.eu/problems/s4c-rate-limited"
+    },
+    {
+      "code": "S4C-INTERNAL-ERROR",
+      "httpStatus": 500,
+      "condition": "Unclassified server fault.",
+      "safeAction": "divertAndAlert",
+      "type": "https://data.sort4circ.eu/problems/s4c-internal-error"
+    }
+  ]
+}