@urbankitstudio/atlas 0.5.2 → 0.6.0

package/README.md

@@ -92,6 +92,42 @@ atlas.totals;           // { states, counties, endpoints }
 atlas.byStateSlug;      // Map<stateSlug, StateFile>
 ```
 
+## `status` is a publish-time claim, not a live signal
+
+This package ships static JSON and makes no network calls, so `status` and
+`lastVerified` on every endpoint describe what was true **when the version you
+installed was published**. `status: "live"` means a check passed before publish —
+not that the endpoint is up right now. A county can go down the day after a
+release and every installed copy keeps saying `"live"` until the next one.
+
+The distinction is not hypothetical: on 2026-08-04 a county was being served as
+`"live"` from its registry entry while the liveness probe had it down that same
+afternoon.
+
+For the current answer, ask the health endpoint — no API key, refreshed every
+two hours:
+
+```ts
+import { LIVE_STATUS_URL } from "@urbankitstudio/atlas";
+
+const res = await fetch(`${LIVE_STATUS_URL}?fips=17089`);
+const health = await res.json();
+// { ok: true, found: true, county_fips: "17089",
+//   status: "ok" | "degraded" | "down" | "unknown",
+//   consecutive_failures, last_ok_at, checked_at }
+```
+
+Two cases to handle rather than ignore:
+
+- **`found: false`** means no observation exists — the county may be untracked or
+  never probed. It is *not* a statement that the endpoint is healthy.
+- **A `503`** means the health store itself was unreachable. Also not a health
+  claim.
+
+Treat both as *unknown*. Neither should render as "up".
+
+Omit `?fips=` to get every tracked county in one call.
+
 ## Coverage today
 
 The atlas currently bundles **155 counties across all 50 US states**, covering the largest counties in each. Call `listStates()` to enumerate the full set; every state is now populated with at least one verified county endpoint.

package/data/california.json

@@ -44,7 +44,7 @@
         "url": "https://egis-lacounty.hub.arcgis.com/",
         "email": null
       },
-      "notes": "Los Angeles County is the most populous US county (pop. 10M+) and contains 88 incorporated cities plus a large unincorporated area. The Assessor Identification Number (AIN) is a 10-digit numeric code unique to each parcel. The public LACounty_Cache/LACounty_Parcel MapServer layer exposes AIN, APN, and SitusFullAddress (no owner name), per California Government Code §7928.205, which broadly restricts owner name and mailing address from public REST endpoints across California. For ownership data, use the LA County Assessor's portal at assessor.lacounty.gov; the Assessor's office manages roughly 2.5 million parcels and publishes annual assessment rolls. Re-verified live 2026-06-04, a sample AIN query returned a real parcel. The EGIS open-data hub at egis-lacounty.hub.arcgis.com has downloadable parcel shapefiles. AIN queries use exact match: AIN='4321002009' (no dashes)."
+      "notes": "Los Angeles County is the most populous US county (pop. 10M+) and contains 88 incorporated cities plus a large unincorporated area. The Assessor Identification Number (AIN) is a 10-digit numeric code unique to each parcel. The public LACounty_Cache/LACounty_Parcel MapServer layer exposes AIN, APN, and SitusFullAddress (no owner name), because the county does not publish an owner column on this layer. California Government Code 7928.205 is often cited for this, but that section protects the home address of elected and appointed officials rather than owner data generally, and California counties differ: San Diego publishes owner names on its public layer while San Bernardino returns a redaction notice in every row. For ownership data, use the LA County Assessor's portal at assessor.lacounty.gov; the Assessor's office manages roughly 2.5 million parcels and publishes annual assessment rolls. Re-verified live 2026-06-04, a sample AIN query returned a real parcel. The EGIS open-data hub at egis-lacounty.hub.arcgis.com has downloadable parcel shapefiles. AIN queries use exact match: AIN='4321002009' (no dashes)."
     },
     {
       "id": "ca-sacramento",
@@ -205,7 +205,27 @@
         "url": "https://data-sbcounty.opendata.arcgis.com/",
         "email": null
       },
-      "notes": "San Bernardino County is the largest county by land area in the contiguous United States (20,000+ sq mi, extending from the Inland Empire to the Nevada and Arizona borders), with a population of approximately 2.2M. 21 fields confirmed including ParcelNumber (the APN), OwnerName, LandValue, ImprovementValue, PersonalPropertyValue, ExemptionValue, HomeOwnerExemption, Acreage, TaxStatus, TaxRateArea, Zoning, ZoningDescription, Jurisdiction. Critical limitation: the OwnerName field exists in the schema and is returned in query results, but its value is redacted to the string 'Protected Per CA Gov Code 7928.205' on every public record. This is a deliberate redaction applied server-side under California Assembly Bill 1785 (effective January 2023), not a field that varies by parcel. ParcelNumber, LandValue, ImprovementValue, Zoning, and Acreage remain accessible and unredacted. Hosted on ArcGIS Online (services.arcgis.com/aA3snZwJfFkVyDuP). The county Assessor portal at arc.sbcounty.gov/property-information/ provides ownership data by APN. The Geographic Information Management Systems (GIMS) division manages the spatial data. Open-data hub: data-sbcounty.opendata.arcgis.com."
+      "notes": "San Bernardino County is the largest county by land area in the contiguous United States (20,000+ sq mi, extending from the Inland Empire to the Nevada and Arizona borders), with a population of approximately 2.2M. 21 fields confirmed including ParcelNumber (the APN), OwnerName, LandValue, ImprovementValue, PersonalPropertyValue, ExemptionValue, HomeOwnerExemption, Acreage, TaxStatus, TaxRateArea, Zoning, ZoningDescription, Jurisdiction. Critical limitation: the OwnerName field exists in the schema and is returned in query results, but its value is redacted to the string 'Protected Per CA Gov Code 7928.205' on every public record. This is a deliberate redaction applied server-side under California Assembly Bill 1785 (effective January 2023), not a field that varies by parcel. ParcelNumber, LandValue, ImprovementValue, Zoning, and Acreage remain accessible and unredacted. Hosted on ArcGIS Online (services.arcgis.com/aA3snZwJfFkVyDuP). The county Assessor portal at arc.sbcounty.gov/property-information/ provides ownership data by APN. The Geographic Information Management Systems (GIMS) division manages the spatial data. Open-data hub: data-sbcounty.opendata.arcgis.com.",
+      "ownerFieldNote": {
+        "body": "San Bernardino County's public parcel layer returns an OwnerName field, but every row's value is the literal string \"Protected Per CA Gov Code 7928.205\" rather than a name. The redaction is applied server-side to the whole layer, so no query can retrieve ownership here. Parcel number, land and improvement value, zoning, and acreage are unredacted and searchable; ownership by APN is available from the county Assessor's own portal.",
+        "source": {
+          "label": "San Bernardino County Assessor property information",
+          "url": "https://arc.sbcounty.gov/property-information/"
+        }
+      },
+      "capabilityOverrides": {
+        "owner_name": {
+          "status": "restricted",
+          "basis": {
+            "type": "county_cited_statute",
+            "note": "Every row's OwnerName value is the literal string \"Protected Per CA Gov Code 7928.205\" rather than a name. The county applies the redaction server-side to the whole layer and cites that section itself. The section protects the home address of elected and appointed officials, so this is the county's own reading applied to every parcel, not a statewide rule: San Diego County publishes owner names on its public layer.",
+            "citation": "Cal. Gov. Code 7928.205",
+            "attributedTo": "San Bernardino County",
+            "sourceUrl": "https://leginfo.legislature.ca.gov/faces/codes_displaySection.xhtml?sectionNum=7928.205&lawCode=GOV"
+          },
+          "lawfulAlternativeUrl": "https://arc.sbcounty.gov/property-information/"
+        }
+      }
     },
     {
       "id": "ca-san-diego",

package/dist/index.cjs

@@ -1,5 +1,17 @@
 'use strict';
 
+// src/capability.ts
+function reviewedCapability(county, field) {
+  return county.capabilityOverrides?.[field] ?? null;
+}
+function isReviewedUnservable(county, field) {
+  const reviewed = reviewedCapability(county, field);
+  return reviewed?.status === "restricted" || reviewed?.status === "not_published";
+}
+
+// src/types.ts
+var LIVE_STATUS_URL = "https://urbankitstudio.com/api/atlas/status";
+
 // data/index.json
 var data_default = {
   version: "0.3.0",
@@ -913,7 +925,7 @@ var california_default = {
         url: "https://egis-lacounty.hub.arcgis.com/",
         email: null
       },
-      notes: "Los Angeles County is the most populous US county (pop. 10M+) and contains 88 incorporated cities plus a large unincorporated area. The Assessor Identification Number (AIN) is a 10-digit numeric code unique to each parcel. The public LACounty_Cache/LACounty_Parcel MapServer layer exposes AIN, APN, and SitusFullAddress (no owner name), per California Government Code \xA77928.205, which broadly restricts owner name and mailing address from public REST endpoints across California. For ownership data, use the LA County Assessor's portal at assessor.lacounty.gov; the Assessor's office manages roughly 2.5 million parcels and publishes annual assessment rolls. Re-verified live 2026-06-04, a sample AIN query returned a real parcel. The EGIS open-data hub at egis-lacounty.hub.arcgis.com has downloadable parcel shapefiles. AIN queries use exact match: AIN='4321002009' (no dashes)."
+      notes: "Los Angeles County is the most populous US county (pop. 10M+) and contains 88 incorporated cities plus a large unincorporated area. The Assessor Identification Number (AIN) is a 10-digit numeric code unique to each parcel. The public LACounty_Cache/LACounty_Parcel MapServer layer exposes AIN, APN, and SitusFullAddress (no owner name), because the county does not publish an owner column on this layer. California Government Code 7928.205 is often cited for this, but that section protects the home address of elected and appointed officials rather than owner data generally, and California counties differ: San Diego publishes owner names on its public layer while San Bernardino returns a redaction notice in every row. For ownership data, use the LA County Assessor's portal at assessor.lacounty.gov; the Assessor's office manages roughly 2.5 million parcels and publishes annual assessment rolls. Re-verified live 2026-06-04, a sample AIN query returned a real parcel. The EGIS open-data hub at egis-lacounty.hub.arcgis.com has downloadable parcel shapefiles. AIN queries use exact match: AIN='4321002009' (no dashes)."
     },
     {
       id: "ca-sacramento",
@@ -1074,7 +1086,27 @@ var california_default = {
         url: "https://data-sbcounty.opendata.arcgis.com/",
         email: null
       },
-      notes: "San Bernardino County is the largest county by land area in the contiguous United States (20,000+ sq mi, extending from the Inland Empire to the Nevada and Arizona borders), with a population of approximately 2.2M. 21 fields confirmed including ParcelNumber (the APN), OwnerName, LandValue, ImprovementValue, PersonalPropertyValue, ExemptionValue, HomeOwnerExemption, Acreage, TaxStatus, TaxRateArea, Zoning, ZoningDescription, Jurisdiction. Critical limitation: the OwnerName field exists in the schema and is returned in query results, but its value is redacted to the string 'Protected Per CA Gov Code 7928.205' on every public record. This is a deliberate redaction applied server-side under California Assembly Bill 1785 (effective January 2023), not a field that varies by parcel. ParcelNumber, LandValue, ImprovementValue, Zoning, and Acreage remain accessible and unredacted. Hosted on ArcGIS Online (services.arcgis.com/aA3snZwJfFkVyDuP). The county Assessor portal at arc.sbcounty.gov/property-information/ provides ownership data by APN. The Geographic Information Management Systems (GIMS) division manages the spatial data. Open-data hub: data-sbcounty.opendata.arcgis.com."
+      notes: "San Bernardino County is the largest county by land area in the contiguous United States (20,000+ sq mi, extending from the Inland Empire to the Nevada and Arizona borders), with a population of approximately 2.2M. 21 fields confirmed including ParcelNumber (the APN), OwnerName, LandValue, ImprovementValue, PersonalPropertyValue, ExemptionValue, HomeOwnerExemption, Acreage, TaxStatus, TaxRateArea, Zoning, ZoningDescription, Jurisdiction. Critical limitation: the OwnerName field exists in the schema and is returned in query results, but its value is redacted to the string 'Protected Per CA Gov Code 7928.205' on every public record. This is a deliberate redaction applied server-side under California Assembly Bill 1785 (effective January 2023), not a field that varies by parcel. ParcelNumber, LandValue, ImprovementValue, Zoning, and Acreage remain accessible and unredacted. Hosted on ArcGIS Online (services.arcgis.com/aA3snZwJfFkVyDuP). The county Assessor portal at arc.sbcounty.gov/property-information/ provides ownership data by APN. The Geographic Information Management Systems (GIMS) division manages the spatial data. Open-data hub: data-sbcounty.opendata.arcgis.com.",
+      ownerFieldNote: {
+        body: `San Bernardino County's public parcel layer returns an OwnerName field, but every row's value is the literal string "Protected Per CA Gov Code 7928.205" rather than a name. The redaction is applied server-side to the whole layer, so no query can retrieve ownership here. Parcel number, land and improvement value, zoning, and acreage are unredacted and searchable; ownership by APN is available from the county Assessor's own portal.`,
+        source: {
+          label: "San Bernardino County Assessor property information",
+          url: "https://arc.sbcounty.gov/property-information/"
+        }
+      },
+      capabilityOverrides: {
+        owner_name: {
+          status: "restricted",
+          basis: {
+            type: "county_cited_statute",
+            note: `Every row's OwnerName value is the literal string "Protected Per CA Gov Code 7928.205" rather than a name. The county applies the redaction server-side to the whole layer and cites that section itself. The section protects the home address of elected and appointed officials, so this is the county's own reading applied to every parcel, not a statewide rule: San Diego County publishes owner names on its public layer.`,
+            citation: "Cal. Gov. Code 7928.205",
+            attributedTo: "San Bernardino County",
+            sourceUrl: "https://leginfo.legislature.ca.gov/faces/codes_displaySection.xhtml?sectionNum=7928.205&lawCode=GOV"
+          },
+          lawfulAlternativeUrl: "https://arc.sbcounty.gov/property-information/"
+        }
+      }
     },
     {
       id: "ca-san-diego",
@@ -8225,6 +8257,7 @@ function countyPath(stateSlug, countySlug) {
   return `/parcel-atlas/${stateSlug}/${countySlug}`;
 }
 
+exports.LIVE_STATUS_URL = LIVE_STATUS_URL;
 exports.atlas = atlas;
 exports.atlasIndex = atlasIndex;
 exports.buildParcelLookupDeepLink = buildParcelLookupDeepLink;
@@ -8233,7 +8266,9 @@ exports.countySlugFromName = countySlugFromName;
 exports.findCounty = findCounty;
 exports.findCountyByFips = findCountyByFips;
 exports.findState = findState;
+exports.isReviewedUnservable = isReviewedUnservable;
 exports.listCountiesByState = listCountiesByState;
 exports.listStates = listStates;
+exports.reviewedCapability = reviewedCapability;
 exports.slugify = slugify;
 exports.statePath = statePath;

package/dist/index.d.cts

@@ -1,7 +1,29 @@
 type ServiceType = "FeatureServer" | "MapServer";
 type LicenseType = "public" | "open-data" | "restricted" | "unknown";
+/**
+ * The registry's curation stamp for an endpoint, AS OF THE MOMENT THIS PACKAGE
+ * WAS PUBLISHED. It is not a live signal and cannot be — this package ships
+ * static JSON and makes no network calls.
+ *
+ * So `"live"` here means "a check passed before publish", not "this endpoint is
+ * up right now". A county can go down the day after a release and every
+ * installed copy will keep reporting `"live"` until the next one.
+ *
+ * For the current answer, query the public health endpoint, which reports what
+ * the liveness probe last observed (every two hours) and requires no API key:
+ *
+ *     GET https://urbankitstudio.com/api/atlas/status?fips=17089
+ *
+ * A `found: false` there means no observation exists — which is not the same as
+ * healthy. See LIVE_STATUS_URL below.
+ */
 type EndpointStatus = "live" | "stale" | "unreachable" | "unverified";
 type VerifiedBy = "manual" | "arcgis-hub-seed" | "automated";
+/**
+ * Where to ask whether an endpoint is actually up right now. Keyless.
+ * Omit the query string for every tracked county.
+ */
+declare const LIVE_STATUS_URL = "https://urbankitstudio.com/api/atlas/status";
 interface SearchField {
     name: string;
     label: string;
@@ -18,7 +40,10 @@ interface EndpointRecord {
     sampleQuery: string | null;
     license: LicenseType;
     licenseUrl: string | null;
+    /** Publish-time claim, NOT live. See {@link EndpointStatus}. */
     status: EndpointStatus;
+    /** ISO date this entry was last verified before publish — a human curation
+     *  date, not a probe result, and always at least as old as this release. */
     lastVerified: string;
     verifiedBy: VerifiedBy;
 }
@@ -27,6 +52,58 @@ interface ContactInfo {
     url: string | null;
     email: string | null;
 }
+/** A short curated caveat about a county, written by a human. */
+interface CountyAdvisory {
+    body: string;
+    source?: {
+        label: string;
+        url: string;
+    };
+}
+/** The fields a caller can ask a county about. */
+type CapabilityField = "apn" | "owner_name" | "owner_mailing_address" | "situs_address" | "geometry" | "land_use" | "zoning";
+type CapabilityStatus = "available" | "not_published" | "restricted" | "unverified";
+/**
+ * Where a non-available status comes from. The type matters more than the
+ * prose, because it tells you whether you are reading a fact about a service, a
+ * claim the COUNTY makes, or a claim we make.
+ *
+ * `county_cited_statute` is the one to read carefully. It means the county
+ * publishes that citation as its own reason, reported here attributed to them
+ * rather than adopted as our reading of the law. San Bernardino County returns
+ * the literal string "Protected Per CA Gov Code 7928.205" in every owner-name
+ * row; that section protects the home address of elected and appointed
+ * officials, and San Diego County publishes owner names on its public layer.
+ * One statute, different county behaviour, so the attribution is not a
+ * formality.
+ */
+type CapabilityBasisType = "endpoint_schema" | "county_cited_statute" | "statute" | "county_policy";
+interface CapabilityBasis {
+    type: CapabilityBasisType;
+    /** One sentence you could show a user without editing. */
+    note: string;
+    citation?: string;
+    sourceUrl?: string;
+    /** Who makes the claim, when it is not us. Always set for county_cited_statute. */
+    attributedTo?: string;
+}
+/**
+ * REVIEWED capability assertions, per field. Only entries a human entered and
+ * checked appear here, which is exactly the knowledge you cannot compute from
+ * the bundled data yourself.
+ *
+ * What is NOT here is the mechanical half. Whether a field is simply absent
+ * from an endpoint's documented `searchFields` is derivable, and this package
+ * deliberately does not derive it: a second implementation of that
+ * classification would drift from the one the API bills against, and you would
+ * have no way to tell which was right. Read `endpoints[].searchFields` for the
+ * mechanical answer, and treat an entry here as outranking it.
+ */
+type CapabilityOverrides = Partial<Record<CapabilityField, {
+    status: CapabilityStatus;
+    basis: CapabilityBasis;
+    lawfulAlternativeUrl?: string | null;
+}>>;
 interface CountyRecord {
     id: string;
     state: string;
@@ -39,6 +116,14 @@ interface CountyRecord {
     contact: ContactInfo | null;
     hasPublicRest: boolean;
     notes: string | null;
+    /** Curated caveat about owner data on this county's public layer. */
+    ownerFieldNote?: CountyAdvisory | null;
+    /** Curated caveat about how old the county's published data is. */
+    dataVintage?: CountyAdvisory | null;
+    /** Reviewed, per-field capability assertions. See {@link CapabilityOverrides}. */
+    capabilityOverrides?: CapabilityOverrides | null;
+    relatedZoningCitySlug?: string | null;
+    relatedPropertyCitySlug?: string | null;
 }
 interface StateFile {
     stateSlug: string;
@@ -66,6 +151,31 @@ interface AtlasIndex {
     };
 }
 
+/**
+ * The reviewed capability assertion for one field, or null when none exists.
+ *
+ * Null is the common answer and it is not a failure: it means nobody has had to
+ * write anything down about that field for that county, so the ordinary rules
+ * apply. Read `county.endpoints[].searchFields` to see what the layer actually
+ * documents.
+ *
+ * A non-null answer is the part worth branching on. It was entered by a human
+ * who checked something a field list cannot show, and it outranks whatever the
+ * field list implies. The clearest case: San Bernardino County publishes an
+ * `OwnerName` column, so the field list says owner names are available, and
+ * every row's value is the literal string "Protected Per CA Gov Code 7928.205".
+ * Only the reviewed record can tell you that.
+ */
+declare function reviewedCapability(county: Pick<CountyRecord, "capabilityOverrides">, field: CapabilityField): NonNullable<CapabilityOverrides[CapabilityField]> | null;
+/**
+ * True when a reviewed record says this field cannot be served, whatever the
+ * reason. Use it to decide whether to promise a user the field at all.
+ *
+ * False does NOT mean "available". It means no reviewed record says otherwise,
+ * so fall back to the endpoint's documented `searchFields`.
+ */
+declare function isReviewedUnservable(county: Pick<CountyRecord, "capabilityOverrides">, field: CapabilityField): boolean;
+
 /**
  * Look up a county by state slug and county slug.
  * Returns undefined if the state isn't populated yet or the county doesn't exist.
@@ -121,4 +231,4 @@ interface Atlas {
 }
 declare const atlas: Atlas;
 
-export { type Atlas, type AtlasIndex, type ContactInfo, type CountyRecord, type EndpointRecord, type EndpointStatus, type LicenseType, type SearchField, type ServiceType, type StateFile, type StateIndexEntry, type VerifiedBy, atlas, atlasIndex, buildParcelLookupDeepLink, countyPath, countySlugFromName, findCounty, findCountyByFips, findState, listCountiesByState, listStates, slugify, statePath };
+export { type Atlas, type AtlasIndex, type CapabilityBasis, type CapabilityBasisType, type CapabilityField, type CapabilityOverrides, type CapabilityStatus, type ContactInfo, type CountyAdvisory, type CountyRecord, type EndpointRecord, type EndpointStatus, LIVE_STATUS_URL, type LicenseType, type SearchField, type ServiceType, type StateFile, type StateIndexEntry, type VerifiedBy, atlas, atlasIndex, buildParcelLookupDeepLink, countyPath, countySlugFromName, findCounty, findCountyByFips, findState, isReviewedUnservable, listCountiesByState, listStates, reviewedCapability, slugify, statePath };

package/dist/index.d.ts

@@ -1,7 +1,29 @@
 type ServiceType = "FeatureServer" | "MapServer";
 type LicenseType = "public" | "open-data" | "restricted" | "unknown";
+/**
+ * The registry's curation stamp for an endpoint, AS OF THE MOMENT THIS PACKAGE
+ * WAS PUBLISHED. It is not a live signal and cannot be — this package ships
+ * static JSON and makes no network calls.
+ *
+ * So `"live"` here means "a check passed before publish", not "this endpoint is
+ * up right now". A county can go down the day after a release and every
+ * installed copy will keep reporting `"live"` until the next one.
+ *
+ * For the current answer, query the public health endpoint, which reports what
+ * the liveness probe last observed (every two hours) and requires no API key:
+ *
+ *     GET https://urbankitstudio.com/api/atlas/status?fips=17089
+ *
+ * A `found: false` there means no observation exists — which is not the same as
+ * healthy. See LIVE_STATUS_URL below.
+ */
 type EndpointStatus = "live" | "stale" | "unreachable" | "unverified";
 type VerifiedBy = "manual" | "arcgis-hub-seed" | "automated";
+/**
+ * Where to ask whether an endpoint is actually up right now. Keyless.
+ * Omit the query string for every tracked county.
+ */
+declare const LIVE_STATUS_URL = "https://urbankitstudio.com/api/atlas/status";
 interface SearchField {
     name: string;
     label: string;
@@ -18,7 +40,10 @@ interface EndpointRecord {
     sampleQuery: string | null;
     license: LicenseType;
     licenseUrl: string | null;
+    /** Publish-time claim, NOT live. See {@link EndpointStatus}. */
     status: EndpointStatus;
+    /** ISO date this entry was last verified before publish — a human curation
+     *  date, not a probe result, and always at least as old as this release. */
     lastVerified: string;
     verifiedBy: VerifiedBy;
 }
@@ -27,6 +52,58 @@ interface ContactInfo {
     url: string | null;
     email: string | null;
 }
+/** A short curated caveat about a county, written by a human. */
+interface CountyAdvisory {
+    body: string;
+    source?: {
+        label: string;
+        url: string;
+    };
+}
+/** The fields a caller can ask a county about. */
+type CapabilityField = "apn" | "owner_name" | "owner_mailing_address" | "situs_address" | "geometry" | "land_use" | "zoning";
+type CapabilityStatus = "available" | "not_published" | "restricted" | "unverified";
+/**
+ * Where a non-available status comes from. The type matters more than the
+ * prose, because it tells you whether you are reading a fact about a service, a
+ * claim the COUNTY makes, or a claim we make.
+ *
+ * `county_cited_statute` is the one to read carefully. It means the county
+ * publishes that citation as its own reason, reported here attributed to them
+ * rather than adopted as our reading of the law. San Bernardino County returns
+ * the literal string "Protected Per CA Gov Code 7928.205" in every owner-name
+ * row; that section protects the home address of elected and appointed
+ * officials, and San Diego County publishes owner names on its public layer.
+ * One statute, different county behaviour, so the attribution is not a
+ * formality.
+ */
+type CapabilityBasisType = "endpoint_schema" | "county_cited_statute" | "statute" | "county_policy";
+interface CapabilityBasis {
+    type: CapabilityBasisType;
+    /** One sentence you could show a user without editing. */
+    note: string;
+    citation?: string;
+    sourceUrl?: string;
+    /** Who makes the claim, when it is not us. Always set for county_cited_statute. */
+    attributedTo?: string;
+}
+/**
+ * REVIEWED capability assertions, per field. Only entries a human entered and
+ * checked appear here, which is exactly the knowledge you cannot compute from
+ * the bundled data yourself.
+ *
+ * What is NOT here is the mechanical half. Whether a field is simply absent
+ * from an endpoint's documented `searchFields` is derivable, and this package
+ * deliberately does not derive it: a second implementation of that
+ * classification would drift from the one the API bills against, and you would
+ * have no way to tell which was right. Read `endpoints[].searchFields` for the
+ * mechanical answer, and treat an entry here as outranking it.
+ */
+type CapabilityOverrides = Partial<Record<CapabilityField, {
+    status: CapabilityStatus;
+    basis: CapabilityBasis;
+    lawfulAlternativeUrl?: string | null;
+}>>;
 interface CountyRecord {
     id: string;
     state: string;
@@ -39,6 +116,14 @@ interface CountyRecord {
     contact: ContactInfo | null;
     hasPublicRest: boolean;
     notes: string | null;
+    /** Curated caveat about owner data on this county's public layer. */
+    ownerFieldNote?: CountyAdvisory | null;
+    /** Curated caveat about how old the county's published data is. */
+    dataVintage?: CountyAdvisory | null;
+    /** Reviewed, per-field capability assertions. See {@link CapabilityOverrides}. */
+    capabilityOverrides?: CapabilityOverrides | null;
+    relatedZoningCitySlug?: string | null;
+    relatedPropertyCitySlug?: string | null;
 }
 interface StateFile {
     stateSlug: string;
@@ -66,6 +151,31 @@ interface AtlasIndex {
     };
 }
 
+/**
+ * The reviewed capability assertion for one field, or null when none exists.
+ *
+ * Null is the common answer and it is not a failure: it means nobody has had to
+ * write anything down about that field for that county, so the ordinary rules
+ * apply. Read `county.endpoints[].searchFields` to see what the layer actually
+ * documents.
+ *
+ * A non-null answer is the part worth branching on. It was entered by a human
+ * who checked something a field list cannot show, and it outranks whatever the
+ * field list implies. The clearest case: San Bernardino County publishes an
+ * `OwnerName` column, so the field list says owner names are available, and
+ * every row's value is the literal string "Protected Per CA Gov Code 7928.205".
+ * Only the reviewed record can tell you that.
+ */
+declare function reviewedCapability(county: Pick<CountyRecord, "capabilityOverrides">, field: CapabilityField): NonNullable<CapabilityOverrides[CapabilityField]> | null;
+/**
+ * True when a reviewed record says this field cannot be served, whatever the
+ * reason. Use it to decide whether to promise a user the field at all.
+ *
+ * False does NOT mean "available". It means no reviewed record says otherwise,
+ * so fall back to the endpoint's documented `searchFields`.
+ */
+declare function isReviewedUnservable(county: Pick<CountyRecord, "capabilityOverrides">, field: CapabilityField): boolean;
+
 /**
  * Look up a county by state slug and county slug.
  * Returns undefined if the state isn't populated yet or the county doesn't exist.
@@ -121,4 +231,4 @@ interface Atlas {
 }
 declare const atlas: Atlas;
 
-export { type Atlas, type AtlasIndex, type ContactInfo, type CountyRecord, type EndpointRecord, type EndpointStatus, type LicenseType, type SearchField, type ServiceType, type StateFile, type StateIndexEntry, type VerifiedBy, atlas, atlasIndex, buildParcelLookupDeepLink, countyPath, countySlugFromName, findCounty, findCountyByFips, findState, listCountiesByState, listStates, slugify, statePath };
+export { type Atlas, type AtlasIndex, type CapabilityBasis, type CapabilityBasisType, type CapabilityField, type CapabilityOverrides, type CapabilityStatus, type ContactInfo, type CountyAdvisory, type CountyRecord, type EndpointRecord, type EndpointStatus, LIVE_STATUS_URL, type LicenseType, type SearchField, type ServiceType, type StateFile, type StateIndexEntry, type VerifiedBy, atlas, atlasIndex, buildParcelLookupDeepLink, countyPath, countySlugFromName, findCounty, findCountyByFips, findState, isReviewedUnservable, listCountiesByState, listStates, reviewedCapability, slugify, statePath };

package/dist/index.js

@@ -1,3 +1,15 @@
+// src/capability.ts
+function reviewedCapability(county, field) {
+  return county.capabilityOverrides?.[field] ?? null;
+}
+function isReviewedUnservable(county, field) {
+  const reviewed = reviewedCapability(county, field);
+  return reviewed?.status === "restricted" || reviewed?.status === "not_published";
+}
+
+// src/types.ts
+var LIVE_STATUS_URL = "https://urbankitstudio.com/api/atlas/status";
+
 // data/index.json
 var data_default = {
   version: "0.3.0",
@@ -911,7 +923,7 @@ var california_default = {
         url: "https://egis-lacounty.hub.arcgis.com/",
         email: null
       },
-      notes: "Los Angeles County is the most populous US county (pop. 10M+) and contains 88 incorporated cities plus a large unincorporated area. The Assessor Identification Number (AIN) is a 10-digit numeric code unique to each parcel. The public LACounty_Cache/LACounty_Parcel MapServer layer exposes AIN, APN, and SitusFullAddress (no owner name), per California Government Code \xA77928.205, which broadly restricts owner name and mailing address from public REST endpoints across California. For ownership data, use the LA County Assessor's portal at assessor.lacounty.gov; the Assessor's office manages roughly 2.5 million parcels and publishes annual assessment rolls. Re-verified live 2026-06-04, a sample AIN query returned a real parcel. The EGIS open-data hub at egis-lacounty.hub.arcgis.com has downloadable parcel shapefiles. AIN queries use exact match: AIN='4321002009' (no dashes)."
+      notes: "Los Angeles County is the most populous US county (pop. 10M+) and contains 88 incorporated cities plus a large unincorporated area. The Assessor Identification Number (AIN) is a 10-digit numeric code unique to each parcel. The public LACounty_Cache/LACounty_Parcel MapServer layer exposes AIN, APN, and SitusFullAddress (no owner name), because the county does not publish an owner column on this layer. California Government Code 7928.205 is often cited for this, but that section protects the home address of elected and appointed officials rather than owner data generally, and California counties differ: San Diego publishes owner names on its public layer while San Bernardino returns a redaction notice in every row. For ownership data, use the LA County Assessor's portal at assessor.lacounty.gov; the Assessor's office manages roughly 2.5 million parcels and publishes annual assessment rolls. Re-verified live 2026-06-04, a sample AIN query returned a real parcel. The EGIS open-data hub at egis-lacounty.hub.arcgis.com has downloadable parcel shapefiles. AIN queries use exact match: AIN='4321002009' (no dashes)."
     },
     {
       id: "ca-sacramento",
@@ -1072,7 +1084,27 @@ var california_default = {
         url: "https://data-sbcounty.opendata.arcgis.com/",
         email: null
       },
-      notes: "San Bernardino County is the largest county by land area in the contiguous United States (20,000+ sq mi, extending from the Inland Empire to the Nevada and Arizona borders), with a population of approximately 2.2M. 21 fields confirmed including ParcelNumber (the APN), OwnerName, LandValue, ImprovementValue, PersonalPropertyValue, ExemptionValue, HomeOwnerExemption, Acreage, TaxStatus, TaxRateArea, Zoning, ZoningDescription, Jurisdiction. Critical limitation: the OwnerName field exists in the schema and is returned in query results, but its value is redacted to the string 'Protected Per CA Gov Code 7928.205' on every public record. This is a deliberate redaction applied server-side under California Assembly Bill 1785 (effective January 2023), not a field that varies by parcel. ParcelNumber, LandValue, ImprovementValue, Zoning, and Acreage remain accessible and unredacted. Hosted on ArcGIS Online (services.arcgis.com/aA3snZwJfFkVyDuP). The county Assessor portal at arc.sbcounty.gov/property-information/ provides ownership data by APN. The Geographic Information Management Systems (GIMS) division manages the spatial data. Open-data hub: data-sbcounty.opendata.arcgis.com."
+      notes: "San Bernardino County is the largest county by land area in the contiguous United States (20,000+ sq mi, extending from the Inland Empire to the Nevada and Arizona borders), with a population of approximately 2.2M. 21 fields confirmed including ParcelNumber (the APN), OwnerName, LandValue, ImprovementValue, PersonalPropertyValue, ExemptionValue, HomeOwnerExemption, Acreage, TaxStatus, TaxRateArea, Zoning, ZoningDescription, Jurisdiction. Critical limitation: the OwnerName field exists in the schema and is returned in query results, but its value is redacted to the string 'Protected Per CA Gov Code 7928.205' on every public record. This is a deliberate redaction applied server-side under California Assembly Bill 1785 (effective January 2023), not a field that varies by parcel. ParcelNumber, LandValue, ImprovementValue, Zoning, and Acreage remain accessible and unredacted. Hosted on ArcGIS Online (services.arcgis.com/aA3snZwJfFkVyDuP). The county Assessor portal at arc.sbcounty.gov/property-information/ provides ownership data by APN. The Geographic Information Management Systems (GIMS) division manages the spatial data. Open-data hub: data-sbcounty.opendata.arcgis.com.",
+      ownerFieldNote: {
+        body: `San Bernardino County's public parcel layer returns an OwnerName field, but every row's value is the literal string "Protected Per CA Gov Code 7928.205" rather than a name. The redaction is applied server-side to the whole layer, so no query can retrieve ownership here. Parcel number, land and improvement value, zoning, and acreage are unredacted and searchable; ownership by APN is available from the county Assessor's own portal.`,
+        source: {
+          label: "San Bernardino County Assessor property information",
+          url: "https://arc.sbcounty.gov/property-information/"
+        }
+      },
+      capabilityOverrides: {
+        owner_name: {
+          status: "restricted",
+          basis: {
+            type: "county_cited_statute",
+            note: `Every row's OwnerName value is the literal string "Protected Per CA Gov Code 7928.205" rather than a name. The county applies the redaction server-side to the whole layer and cites that section itself. The section protects the home address of elected and appointed officials, so this is the county's own reading applied to every parcel, not a statewide rule: San Diego County publishes owner names on its public layer.`,
+            citation: "Cal. Gov. Code 7928.205",
+            attributedTo: "San Bernardino County",
+            sourceUrl: "https://leginfo.legislature.ca.gov/faces/codes_displaySection.xhtml?sectionNum=7928.205&lawCode=GOV"
+          },
+          lawfulAlternativeUrl: "https://arc.sbcounty.gov/property-information/"
+        }
+      }
     },
     {
       id: "ca-san-diego",
@@ -8223,4 +8255,4 @@ function countyPath(stateSlug, countySlug) {
   return `/parcel-atlas/${stateSlug}/${countySlug}`;
 }
 
-export { atlas, atlasIndex, buildParcelLookupDeepLink, countyPath, countySlugFromName, findCounty, findCountyByFips, findState, listCountiesByState, listStates, slugify, statePath };
+export { LIVE_STATUS_URL, atlas, atlasIndex, buildParcelLookupDeepLink, countyPath, countySlugFromName, findCounty, findCountyByFips, findState, isReviewedUnservable, listCountiesByState, listStates, reviewedCapability, slugify, statePath };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@urbankitstudio/atlas",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "description": "JS SDK for the UrbanKit County Parcel REST API Atlas — public ArcGIS REST endpoints for US county parcel data, with searchable field metadata, sample queries, and license info.",
   "keywords": [
     "parcel",
@@ -57,7 +57,7 @@
   "devDependencies": {
     "tsup": "^8.3.5",
     "typescript": "^5.8.3",
-    "vitest": "^2.1.8"
+    "vitest": "^4.1.10"
   },
   "publishConfig": {
     "access": "public"