tax_conformance_kit 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a30a2eddf0c383ace1ac9ad16038f9dd531c92ef577cb95c0a8c01f5ec6a7baf
-  data.tar.gz: 21061dff0f74ab49a0f194304e645d2c015e71352b7bdd32f9e4d47454b7376a
+  metadata.gz: 6f7af37d7149859cbb18692e8040e9a710027fbef9f0716eacca6ed9c491c301
+  data.tar.gz: 2dc3af404778b6b2e4c8939aa3e5b49b8fb2040ec0cba3ffd07987dea906e294
 SHA512:
-  metadata.gz: 5dd8edd5f14f151ace599d3cc088b85ee8be81326280e4d0752c295578c8b665a0257aa87f87536698595a668ddab06f984d33dae4d380e3d331f68d80e89268
-  data.tar.gz: edd8bcb53f6740ee483389afc0e799f6e54dfc16215e14f5dd7220372bfbbe734eef85cad9e9e4873dd2f227484862964483afa1bfdef4ec56f37403d5e1fbb4
+  metadata.gz: 9fb939964451a20c444da3f8ecab844203cca7472a11eb331229c8bb1623cc5ad5fa7c18bcec40abe0e1040f3ac5c03354eb4f17e186e6331dc34f08688d9a76
+  data.tar.gz: 5fbc537124e7698d4276b0b5b13d4ffe0197d437f90160283640a37c1274e5cfb7e0e996e9ef82483fdde2c0ec8fc12516de7d33573d815569f4ecfc021f6f93

data/README.md

@@ -4,7 +4,13 @@ Thin Ruby client for the `tax-conformance-kit` Go runtime.
 
 ## Install
 
-Path dependency:
+Bundler (RubyGems):
+
+```ruby
+gem "tax_conformance_kit", "~> 0.2.0"
+```
+
+Path dependency (for local development):
 
 ```ruby
 gem "tax_conformance_kit", path: "../tax-conformance-kit/clients/ruby"
@@ -13,28 +19,32 @@ gem "tax_conformance_kit", path: "../tax-conformance-kit/clients/ruby"
 Git dependency:
 
 ```ruby
-gem "tax_conformance_kit", git: "https://github.com/ramones/tax-conformance-kit.git", glob: "clients/ruby/*.gemspec"
+gem "tax_conformance_kit", git: "https://github.com/odeva-labs/tax-conformance-kit.git", glob: "clients/ruby/*.gemspec"
 ```
 
 ## Usage
 
+Zero-config — the gem ships with the bundled `taxctl` binary and the kind registry:
+
 ```ruby
 require "tax_conformance_kit"
 
-client = TaxConformanceKit::TaxctlClient.new(
-  command: ["/path/to/taxctl"],
-  registry_path: "/path/to/kind-registry.v1.json"
-)
-
-response = client.evaluate(
-  ruleset: ruleset_hash,
-  booking_input: booking_input_hash
-)
+client = TaxConformanceKit::TaxctlClient.new
+response = client.evaluate(ruleset: ruleset_hash, booking_input: booking_input_hash)
 ```
 
+### Advanced: override `command:`
+
 `command:` may be either:
 
 - a binary path string, for example `"/usr/local/bin/taxctl"`
 - a full argv array, for example `["go", "run", "./cmd/taxctl"]`
 
+```ruby
+client = TaxConformanceKit::TaxctlClient.new(
+  command: ["/path/to/taxctl"],
+  registry_path: "/path/to/kind-registry.v1.json"
+)
+```
+
 The client does not implement the evaluator. It shells out to the canonical Go runtime and exchanges JSON over stdin/stdout.

data/data/kind-registry.v1.json

@@ -0,0 +1,316 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://tax-conformance.dev/schemas/kind-registry.v1.json",
+  "title": "KindRegistry",
+  "description": "Canonical list of calculation.kind and predicate.kind values with their params schemas. Every engine port MUST reject rulesets referencing kinds not present here. Ports MAY implement a subset, but MUST fail loudly on unimplemented-but-registered kinds encountered during evaluation.",
+  "type": "object",
+  "required": ["registry_version", "calculations", "predicates"],
+  "properties": {
+    "registry_version": { "const": "v1" },
+    "calculations": {
+      "type": "object",
+      "additionalProperties": { "$ref": "#/$defs/KindEntry" }
+    },
+    "predicates": {
+      "type": "object",
+      "additionalProperties": { "$ref": "#/$defs/KindEntry" }
+    }
+  },
+  "$defs": {
+    "KindEntry": {
+      "type": "object",
+      "required": ["description", "params_schema"],
+      "properties": {
+        "description": { "type": "string" },
+        "since": { "type": "string", "description": "Schema version when introduced" },
+        "params_schema": {
+          "type": "object",
+          "description": "JSON Schema (draft 2020-12) for the kind's params object"
+        },
+        "examples": {
+          "type": "array",
+          "items": { "type": "object" }
+        }
+      }
+    }
+  },
+
+  "registry_version": "v1",
+  "calculations": {
+    "generic.per_night": {
+      "description": "Flat amount per night.",
+      "since": "v1",
+      "params_schema": {
+        "type": "object",
+        "required": ["amount"],
+        "properties": {
+          "amount": { "type": "number", "minimum": 0 }
+        },
+        "additionalProperties": false
+      }
+    },
+    "generic.per_person_per_night": {
+      "description": "Flat amount per guest per night. Guests = adults + children unless a predicate narrows the set.",
+      "since": "v1",
+      "params_schema": {
+        "type": "object",
+        "required": ["amount"],
+        "properties": {
+          "amount": { "type": "number", "minimum": 0 }
+        },
+        "additionalProperties": false
+      }
+    },
+    "generic.fixed_amount": {
+      "description": "Flat amount per booking.",
+      "since": "v1",
+      "params_schema": {
+        "type": "object",
+        "required": ["amount"],
+        "properties": {
+          "amount": { "type": "number", "minimum": 0 }
+        },
+        "additionalProperties": false
+      }
+    },
+    "generic.percentage_of_base": {
+      "description": "Percentage of a configurable base. IMPORTANT: 'accommodation_fee_exclusive_of_tax' means the taxable base excludes the tourist tax itself (NL ordinances commonly define it this way).",
+      "since": "v1",
+      "params_schema": {
+        "type": "object",
+        "required": ["rate_pct", "base"],
+        "properties": {
+          "rate_pct": { "type": "number", "minimum": 0 },
+          "base": {
+            "type": "string",
+            "enum": [
+              "accommodation_fee_exclusive_of_tax",
+              "gross_booking_total",
+              "subtotal"
+            ]
+          }
+        },
+        "additionalProperties": false
+      }
+    },
+    "nl.tiered_by_stay_duration": {
+      "description": "Step function over stay length in nights. Tiers are closed-open on max_nights; final tier may omit max_nights. Each tier's amount is the total for the booking (not per-night).",
+      "since": "v1",
+      "params_schema": {
+        "type": "object",
+        "required": ["tiers"],
+        "properties": {
+          "tiers": {
+            "type": "array",
+            "minItems": 1,
+            "items": {
+              "type": "object",
+              "required": ["amount"],
+              "properties": {
+                "min_nights": { "type": "integer", "minimum": 0 },
+                "max_nights": { "type": "integer", "minimum": 1 },
+                "amount": { "type": "number", "minimum": 0 }
+              },
+              "additionalProperties": false
+            }
+          }
+        },
+        "additionalProperties": false
+      },
+      "examples": [
+        {
+          "tiers": [
+            { "max_nights": 30, "amount": 0 },
+            { "min_nights": 30, "max_nights": 120, "amount": 50 },
+            { "min_nights": 120, "max_nights": 240, "amount": 100 },
+            { "min_nights": 240, "amount": 150 }
+          ]
+        }
+      ]
+    },
+    "nl.fixed_per_pitch_per_year": {
+      "description": "Per-pitch annual levy. Requires pitch_count on input. Primarily used with the annual_operator_assessment mode; included here so that per-booking engines can at least validate and reject explicitly.",
+      "since": "v1",
+      "params_schema": {
+        "type": "object",
+        "required": ["amount_per_pitch"],
+        "properties": {
+          "amount_per_pitch": { "type": "number", "minimum": 0 },
+          "season": {
+            "type": "string",
+            "enum": ["full_year", "pre_season", "post_season", "per_month"]
+          }
+        },
+        "additionalProperties": false
+      }
+    },
+    "nl.forfait_per_person_per_night": {
+      "description": "Per-person-per-night rate applied to DEEMED inputs (nights and persons derived from ordinance-defined forfaits, e.g. Roerdalen: yearly pitch = 80 nights x 2.4 persons). Concrete forfait table lives in params; engine multiplies rate * deemed_nights * deemed_persons * pitch_count.",
+      "since": "v1",
+      "params_schema": {
+        "type": "object",
+        "required": ["amount", "forfait"],
+        "properties": {
+          "amount": { "type": "number", "minimum": 0 },
+          "forfait": {
+            "type": "object",
+            "required": ["nights", "persons_per_pitch"],
+            "properties": {
+              "nights": { "type": "number", "minimum": 0 },
+              "persons_per_pitch": { "type": "number", "minimum": 0 },
+              "regime": {
+                "type": "string",
+                "enum": ["yearly_pitch", "seasonal_pitch", "bed_rental"]
+              }
+            },
+            "additionalProperties": false
+          }
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "predicates": {
+    "guest.resident_of_same_municipality": {
+      "description": "True when main_guest_municipality_code equals property_municipality_code (case-insensitive).",
+      "since": "v1",
+      "params_schema": { "type": "object", "additionalProperties": false }
+    },
+    "guest.age_below": {
+      "description": "True when at least one (or N, if params.count set) guest is younger than max_age on the reference night.",
+      "since": "v1",
+      "params_schema": {
+        "type": "object",
+        "required": ["max_age"],
+        "properties": {
+          "max_age": { "type": "integer", "minimum": 0 },
+          "night_index": {
+            "type": "string",
+            "enum": ["first", "any", "each"],
+            "default": "any",
+            "description": "Which night the age is evaluated against. Roerdalen 'under 2 first night' uses 'first'."
+          },
+          "count": { "type": "integer", "minimum": 1, "default": 1 }
+        },
+        "additionalProperties": false
+      }
+    },
+    "stay.purpose_in": {
+      "description": "True when booking_input.stay_purpose is in the allowed list.",
+      "since": "v1",
+      "params_schema": {
+        "type": "object",
+        "required": ["values"],
+        "properties": {
+          "values": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "enum": ["school_group", "youth_group", "leisure", "business", "medical", "asylum", "government_ordered"]
+            },
+            "minItems": 1
+          }
+        },
+        "additionalProperties": false
+      }
+    },
+    "stay.wtza_care_institution": {
+      "description": "Stay is at a Wtza-registered care institution. Short-circuit exemption in all four sampled NL ordinances.",
+      "since": "v1",
+      "params_schema": { "type": "object", "additionalProperties": false }
+    },
+    "stay.coa_asylum_housing": {
+      "description": "Stay is COA asylum-seeker housing.",
+      "since": "v1",
+      "params_schema": { "type": "object", "additionalProperties": false }
+    },
+    "stay.accommodation_brought_by": {
+      "description": "Guest brings their own accommodation vs operator provides (Breda camping vs bungalow distinction).",
+      "since": "v1",
+      "params_schema": {
+        "type": "object",
+        "required": ["value"],
+        "properties": {
+          "value": { "type": "string", "enum": ["guest", "operator"] }
+        },
+        "additionalProperties": false
+      }
+    },
+    "stay.pricing_arrangement": {
+      "description": "Operator-elected pricing regime. 'per_night' = charged per person per night; 'arrangement' = tiered flat amount by stay-duration bucket. Breda allows camping operators to elect either. Input must assert the chosen regime.",
+      "since": "v1",
+      "params_schema": {
+        "type": "object",
+        "required": ["value"],
+        "properties": {
+          "value": { "type": "string", "enum": ["per_night", "arrangement"] }
+        },
+        "additionalProperties": false
+      }
+    },
+    "stay.supervised_minor_group": {
+      "description": "True when the booking is an organized minor group with enough minors and adult supervisors. Breda exempts groups of more than 10 minors accompanied by 18+ supervisors.",
+      "since": "v1",
+      "params_schema": {
+        "type": "object",
+        "required": ["min_minors", "min_supervisors", "supervisor_min_age"],
+        "properties": {
+          "min_minors": { "type": "integer", "minimum": 1 },
+          "min_supervisors": { "type": "integer", "minimum": 1 },
+          "supervisor_min_age": { "type": "integer", "minimum": 0 },
+          "allowed_purposes": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "enum": ["school_group", "youth_group", "leisure", "business", "medical", "asylum", "government_ordered"]
+            },
+            "minItems": 1
+          }
+        },
+        "additionalProperties": false
+      }
+    },
+    "stay.seasonal_window": {
+      "description": "Stay date falls within a recurring month-day window (wraps year). Schouwen-Duiveland seasonal surcharges.",
+      "since": "v1",
+      "params_schema": {
+        "type": "object",
+        "required": ["start_mmdd", "end_mmdd"],
+        "properties": {
+          "start_mmdd": { "type": "string", "pattern": "^\\d{2}-\\d{2}$" },
+          "end_mmdd": { "type": "string", "pattern": "^\\d{2}-\\d{2}$" }
+        },
+        "additionalProperties": false
+      }
+    },
+    "pitch.ownership_restriction": {
+      "description": "Schouwen-Duiveland: pitch reserved for owner + household; non-owner guests excluded.",
+      "since": "v1",
+      "params_schema": {
+        "type": "object",
+        "properties": {
+          "allowed": {
+            "type": "array",
+            "items": { "type": "string", "enum": ["owner", "owner_household"] }
+          }
+        },
+        "additionalProperties": false
+      }
+    },
+    "cross_tax.already_subject_to": {
+      "description": "Booking is already subject to another named tax (Roerdalen: forensenbelasting). Engine does not verify; input must assert it.",
+      "since": "v1",
+      "params_schema": {
+        "type": "object",
+        "required": ["tax"],
+        "properties": {
+          "tax": {
+            "type": "string",
+            "enum": ["forensenbelasting", "watertoeristenbelasting", "vat", "corporate"]
+          }
+        },
+        "additionalProperties": false
+      }
+    }
+  }
+}

data/data/regulation/nl/gemeentelijke_verordening/aa_en_hunze/2024-11-29.json

@@ -0,0 +1,64 @@
+{
+  "id": "nl-aa_en_hunze-2024-11-29",
+  "domain": "tourist_tax",
+  "lifecycle": "draft",
+  "jurisdiction": {
+    "country_code": "NL",
+    "country_name": "Netherlands",
+    "region_code": "",
+    "region_name": ""
+  },
+  "notes": "Auto-generated from CVDR publication analysis. Source-backed draft only; review required before conformance use.",
+  "assessment_policy": {
+    "period": "calendar_year",
+    "minimum_assessment_amount": {
+      "amount": 10,
+      "currency": "EUR"
+    },
+    "notes": "Assessment period inferred from the belastingtijdvak article. Minimum assessment amount inferred from the aanslaggrens article."
+  },
+  "rules": [
+    {
+      "id": "2024-11-29-rate-1",
+      "municipality_code": "1680",
+      "municipality_name": "Aa en Hunze",
+      "region_code": "",
+      "valid_from": "2024-11-29",
+      "valid_to": "2025-11-27",
+      "applies_to": {
+        "accommodation_types": []
+      },
+      "calculation": {
+        "kind": "generic.per_person_per_night",
+        "params": {
+          "amount": 1.55
+        },
+        "currency": "EUR"
+      },
+      "predicates": [],
+      "exemptions": [
+        {
+          "kind": "guest.resident_of_same_municipality",
+          "params": null
+        },
+        {
+          "kind": "stay.wtza_care_institution",
+          "params": null
+        },
+        {
+          "kind": "stay.coa_asylum_housing",
+          "params": null
+        }
+      ],
+      "source": {
+        "source_url": "https://lokaleregelgeving.overheid.nl/CVDR727133/1",
+        "cvdr_id": "CVDR727133",
+        "scraped_at": "2026-04-17T12:09:56Z",
+        "reviewed_at": null,
+        "reviewer": ""
+      },
+      "confidence": "scraped",
+      "notes": "Generated from tariff article. Reviewer must confirm category boundaries and exclusions. Evidence articles: 6"
+    }
+  ]
+}

data/data/regulation/nl/gemeentelijke_verordening/aa_en_hunze/2025-11-28.json

@@ -0,0 +1,64 @@
+{
+  "id": "nl-aa_en_hunze-2025-11-28",
+  "domain": "tourist_tax",
+  "lifecycle": "draft",
+  "jurisdiction": {
+    "country_code": "NL",
+    "country_name": "Netherlands",
+    "region_code": "",
+    "region_name": ""
+  },
+  "notes": "Auto-generated from CVDR publication analysis. Source-backed draft only; review required before conformance use.",
+  "assessment_policy": {
+    "minimum_assessment_amount": {
+      "amount": 10,
+      "currency": "EUR"
+    },
+    "notes": "Assessment period inferred from the belastingtijdvak article. Minimum assessment amount inferred from the aanslaggrens article.",
+    "period": "calendar_year"
+  },
+  "rules": [
+    {
+      "applies_to": {
+        "accommodation_types": []
+      },
+      "calculation": {
+        "currency": "EUR",
+        "kind": "generic.per_person_per_night",
+        "params": {
+          "amount": 1.55
+        }
+      },
+      "confidence": "scraped",
+      "exemptions": [
+        {
+          "kind": "guest.resident_of_same_municipality",
+          "params": null
+        },
+        {
+          "kind": "stay.wtza_care_institution",
+          "params": null
+        },
+        {
+          "kind": "stay.coa_asylum_housing",
+          "params": null
+        }
+      ],
+      "id": "2025-11-28-rate-1",
+      "municipality_code": "1680",
+      "municipality_name": "Aa en Hunze",
+      "notes": "Generated from tariff article. Reviewer must confirm category boundaries and exclusions. Evidence articles: 6",
+      "predicates": [],
+      "region_code": "",
+      "source": {
+        "cvdr_id": "CVDR747131",
+        "reviewed_at": null,
+        "reviewer": "",
+        "scraped_at": "2026-04-17T12:09:56Z",
+        "source_url": "https://lokaleregelgeving.overheid.nl/CVDR747131/1"
+      },
+      "valid_from": "2025-11-28",
+      "valid_to": null
+    }
+  ]
+}

data/data/regulation/nl/gemeentelijke_verordening/aalten/2024-12-23.json

@@ -0,0 +1,70 @@
+{
+  "id": "nl-aalten-2024-12-23",
+  "domain": "tourist_tax",
+  "lifecycle": "draft",
+  "jurisdiction": {
+    "country_code": "NL",
+    "country_name": "Netherlands",
+    "region_code": "",
+    "region_name": ""
+  },
+  "notes": "Auto-generated from CVDR publication analysis. Source-backed draft only; review required before conformance use.",
+  "assessment_policy": {
+    "period": "calendar_year",
+    "minimum_assessment_amount": {
+      "amount": 10,
+      "currency": "EUR"
+    },
+    "notes": "Assessment period inferred from the belastingtijdvak article. Minimum assessment amount inferred from the aanslaggrens article."
+  },
+  "rules": [
+    {
+      "id": "2024-12-23-rate-1",
+      "municipality_code": "0197",
+      "municipality_name": "Aalten",
+      "region_code": "",
+      "valid_from": "2024-12-23",
+      "valid_to": "2025-12-19",
+      "applies_to": {
+        "accommodation_types": []
+      },
+      "calculation": {
+        "kind": "generic.per_person_per_night",
+        "params": {
+          "amount": 1.55
+        },
+        "currency": "EUR"
+      },
+      "predicates": [],
+      "exemptions": [
+        {
+          "kind": "guest.resident_of_same_municipality",
+          "params": null
+        },
+        {
+          "kind": "stay.wtza_care_institution",
+          "params": null
+        },
+        {
+          "kind": "stay.coa_asylum_housing",
+          "params": null
+        },
+        {
+          "kind": "cross_tax.already_subject_to",
+          "params": {
+            "tax": "forensenbelasting"
+          }
+        }
+      ],
+      "source": {
+        "source_url": "https://lokaleregelgeving.overheid.nl/CVDR730806/1",
+        "cvdr_id": "CVDR730806",
+        "scraped_at": "2026-04-17T12:09:56Z",
+        "reviewed_at": null,
+        "reviewer": ""
+      },
+      "confidence": "scraped",
+      "notes": "Generated from tariff article. Reviewer must confirm category boundaries and exclusions. Evidence articles: 6"
+    }
+  ]
+}

data/data/regulation/nl/gemeentelijke_verordening/aalten/2025-12-20.json

@@ -0,0 +1,70 @@
+{
+  "id": "nl-aalten-2025-12-20",
+  "domain": "tourist_tax",
+  "lifecycle": "draft",
+  "jurisdiction": {
+    "country_code": "NL",
+    "country_name": "Netherlands",
+    "region_code": "",
+    "region_name": ""
+  },
+  "notes": "Auto-generated from CVDR publication analysis. Source-backed draft only; review required before conformance use.",
+  "assessment_policy": {
+    "minimum_assessment_amount": {
+      "amount": 10,
+      "currency": "EUR"
+    },
+    "notes": "Assessment period inferred from the belastingtijdvak article. Minimum assessment amount inferred from the aanslaggrens article.",
+    "period": "calendar_year"
+  },
+  "rules": [
+    {
+      "applies_to": {
+        "accommodation_types": []
+      },
+      "calculation": {
+        "currency": "EUR",
+        "kind": "generic.per_person_per_night",
+        "params": {
+          "amount": 1.55
+        }
+      },
+      "confidence": "scraped",
+      "exemptions": [
+        {
+          "kind": "guest.resident_of_same_municipality",
+          "params": null
+        },
+        {
+          "kind": "stay.wtza_care_institution",
+          "params": null
+        },
+        {
+          "kind": "stay.coa_asylum_housing",
+          "params": null
+        },
+        {
+          "kind": "cross_tax.already_subject_to",
+          "params": {
+            "tax": "forensenbelasting"
+          }
+        }
+      ],
+      "id": "2025-12-20-rate-1",
+      "municipality_code": "0197",
+      "municipality_name": "Aalten",
+      "notes": "Generated from tariff article. Reviewer must confirm category boundaries and exclusions. Evidence articles: 6",
+      "predicates": [],
+      "region_code": "",
+      "source": {
+        "cvdr_id": "CVDR751414",
+        "reviewed_at": null,
+        "reviewer": "",
+        "scraped_at": "2026-04-17T12:09:56Z",
+        "source_url": "https://lokaleregelgeving.overheid.nl/CVDR751414/1"
+      },
+      "valid_from": "2025-12-20",
+      "valid_to": null
+    }
+  ]
+}