{ "schema": "cityscroll.api_capability_catalog.v1", "generated_from": "capabilities/registry.mjs + capabilities/mcp_tool_declarations.mjs", "endpoint": "https://api.cityscroll.org", "operations": [ { "reference": "notice.search@1", "id": "notice.search", "version": "1.0.0", "title": "Notice Search", "description": "Search NYC City Record notices (the daily-refreshed mirror). Keyword terms are OR-matched; add structured filters to narrow. Amounts are validity-filtered (data-entry errors excluded); rolling placeholder deadlines are labeled, never shown as dates.", "owner": "notices", "operation": "read", "authority": { "class": "public-read", "sideEffect": "none", "approval": "none" }, "cost": { "class": "bounded-d1-read", "machineFanOut": "low" }, "input_schema": "cityscroll.capability.notice_search.input.v1", "input_contract": { "schema": "cityscroll.capability.notice_search.input.v1", "termGroups": "bounded AND-of-OR term arrays", "limits": { "minimum": 1, "maximum": 100 }, "termBounds": { "maximumTermGroups": 64, "maximumTermsPerGroup": 64, "maximumTermLength": 500 }, "orderings": [ "start_date", "contract_amount", "score" ], "adapterDefaults": true }, "output_schema": "cityscroll.capability.notice_search.output.v1", "output_contract": { "schema": "cityscroll.capability.notice_search.output.v1", "fields": [ "terms_used", "total_matches", "retrieval", "results" ], "availability": [ "complete", "empty", "unavailable" ], "privateFieldsForbidden": [ "_haystack" ] }, "bounds": { "input": { "maximumTermGroups": 64, "maximumTermsPerGroup": 64, "maximumTermLength": 500, "minimum": 1, "maximum": 100 }, "output": { "maximumResults": 100 } }, "examples": [ { "input": { "termGroups": [ [ "construction", "scaffolding" ] ], "limit": 10 }, "output": { "availability": "complete", "maximumResults": 10 } }, { "input": { "termGroups": [], "openOnly": true, "limit": 1 }, "output": { "availability": "empty", "maximumResults": 1 } } ], "provenance": { "recordIdentity": "request_id", "matchEvidence": "match_provenance", "rawQueryLogging": false }, "freshness": { "owner": "D1 notice-mirror read model", "projection": "adapter-owned" }, "provider": { "id": "worker-d1.notice-search", "module": "worker/src/lib/notices.mjs", "export": "workerD1NoticeSearch", "store": "Cloudflare D1", "readModel": "recent notices mirror" }, "transports": [ { "id": "worker-http.search.notice-lane@1", "module": "worker/src/search.mjs", "kind": "http-lane", "route": "GET /search", "surface": "Universal search" }, { "id": "mcp.search_notices@1", "module": "worker/src/mcp.mjs", "kind": "mcp-tool", "tool": "search_notices", "route": "POST /mcp", "surface": "MCP" } ] }, { "reference": "notice.get@1", "id": "notice.get", "version": "1.0.0", "title": "Notice Get", "description": "Get one public City Record notice by its exact RequestID. The result preserves materialized-source freshness and distinguishes a missing public notice from a read that cannot be served.", "owner": "notices", "operation": "read", "authority": { "class": "public-read", "sideEffect": "none", "approval": "none" }, "cost": { "class": "bounded-public-source-read", "machineFanOut": "low" }, "input_schema": "cityscroll.capability.notice_get.input.v1", "input_contract": { "schema": "cityscroll.capability.notice_get.input.v1", "identity": "exact City Record RequestID", "limits": { "requestIdMaximumLength": 80, "maximum": 1 } }, "output_schema": "cityscroll.capability.notice_get.output.v1", "output_contract": { "schema": "cityscroll.capability.notice_get.output.v1", "fields": [ "capability_reference", "availability", "notice", "source", "generated_at", "stale", "error" ], "availability": [ "available", "not_yet_public", "unavailable" ], "representations": [ { "id": "json", "mediaType": "application/json", "projection": "public notice read envelope" }, { "id": "text-summary", "mediaType": "text/plain", "projection": "bounded public notice summary" } ] }, "bounds": { "input": { "requestIdMaximumLength": 80, "maximum": 1 }, "output": { "oneNotice": true } }, "examples": [ { "input": { "requestId": "20260807001" }, "output": { "availability": "available", "source": "materialized", "stale": false } }, { "input": { "requestId": "20260807999" }, "output": { "availability": "not_yet_public", "error": "not-found" } } ], "provenance": { "noticeIdentity": "notice.request_id", "sourceIdentity": "source + notice.request_id", "observationClock": "generated_at", "staleSnapshotPreserved": true }, "freshness": { "owner": "materialized notice mirror with public-source fallback", "projection": "generated_at plus stale" }, "provider": { "id": "worker-notices.notice-get", "module": "worker/src/notice.mjs", "export": "workerNoticeGet", "store": "Cloudflare D1 with City Record fallback", "readModel": "public City Record notice row" }, "transports": [ { "id": "worker-http.notice-get@1", "module": "worker/src/notice.mjs", "kind": "http-route", "route": "GET /notice", "surface": "Notice detail", "representations": [ { "id": "json", "mediaType": "application/json", "projection": "public notice read envelope" }, { "id": "text-summary", "mediaType": "text/plain", "projection": "bounded public notice summary" } ] }, { "id": "mcp.get_notice@1", "module": "worker/src/mcp.mjs", "kind": "mcp-tool", "tool": "get_notice", "route": "POST /mcp", "surface": "MCP", "representations": [ { "id": "json", "mediaType": "application/json", "projection": "public notice read envelope" }, { "id": "text-summary", "mediaType": "text/plain", "projection": "bounded public notice summary" } ] } ] }, { "reference": "entity.dossier.get@1", "id": "entity.dossier.get", "version": "1.0.0", "title": "Entity Dossier Get", "description": "Get the bounded public dossier for one exact canonical CityScroll entity. Preserves attributed disagreements, availability, provenance, and public redaction.", "owner": "entity-resolution", "operation": "read", "authority": { "class": "public-read", "sideEffect": "none", "approval": "none", "redaction": "public dossier serializer allowlist" }, "cost": { "class": "bounded-d1-read", "machineFanOut": "low" }, "input_schema": "cityscroll.capability.entity_dossier_get.input.v1", "input_contract": { "schema": "cityscroll.capability.entity_dossier_get.input.v1", "identity": "exact canonical entity id", "limits": { "entityIdMaximumLength": 300, "recordLimit": 250 } }, "output_schema": "cityscroll.capability.entity_dossier_get.output.v1", "output_contract": { "schema": "cityscroll.capability.entity_dossier_get.output.v1", "dossierSchema": "public_entity_dossier_v1", "fields": [ "capability_reference", "availability", "dossier", "error" ], "availability": [ "available", "not_yet_public", "unavailable" ], "representations": [ { "id": "json", "mediaType": "application/json", "projection": "public dossier object" }, { "id": "html", "mediaType": "text/html", "projection": "existing attributed dossier document" } ], "privateFieldsForbidden": [ "raw_snapshot", "normalized_snapshot", "content_hash", "source_record_id", "link_confidence_score", "matcher_version", "evidence_json", "resolution_run_id", "review_status" ] }, "bounds": { "input": { "entityIdMaximumLength": 300, "recordLimit": 250 }, "output": { "maximumLinkedRecords": 250 } }, "examples": [ { "input": { "entityId": "vendor:stem:ACME CONSTRUCTION" }, "output": { "availability": "available", "maximumLinkedRecords": 250 } }, { "input": { "entityId": "vendor:unknown" }, "output": { "availability": "not_yet_public", "error": "not-found" } } ], "provenance": { "entityIdentity": "entity.id", "sourceIdentity": "linked_records[].source + assertions[].provenance.source", "observationClock": "scope.observed_from + scope.observed_through", "disagreementsPreserved": true }, "freshness": { "owner": "D1 entity-resolution read model", "projection": "public serializer and adapter-owned representation" }, "provider": { "id": "worker-d1.entity-dossier", "module": "worker/src/entity_dossier.mjs", "export": "workerD1EntityDossier", "store": "Cloudflare D1", "readModel": "canonical entities plus accepted source-record links" }, "transports": [ { "id": "worker-http.entity-dossier@1", "module": "worker/src/entity_dossier.mjs", "kind": "http-route", "route": "GET /entity-dossier", "surface": "Entity dossier", "representations": [ { "id": "json", "mediaType": "application/json", "projection": "public dossier object" }, { "id": "html", "mediaType": "text/html", "projection": "existing attributed dossier document" } ] }, { "id": "mcp.get_entity_dossier@1", "module": "worker/src/mcp.mjs", "kind": "mcp-tool", "tool": "get_entity_dossier", "route": "POST /mcp", "surface": "MCP" } ] }, { "reference": "entity.relationships.get@1", "id": "entity.relationships.get", "version": "1.1.0", "title": "Entity Relationships Get", "description": "Traverse bounded, evidence-bearing public relationships from one exact canonical CityScroll entity. Only the closed node and edge vocabularies are returned. Published agency graphs give person-leader nodes available_detail: separate dossier availability, an exact leadership read path when available, observation date, confidence, and source limitation.", "owner": "entity-resolution", "operation": "read", "authority": { "class": "public-read", "sideEffect": "none", "approval": "none", "redaction": "public relationship graph serializer allowlist" }, "cost": { "class": "bounded-d1-read", "machineFanOut": "bounded-graph" }, "input_schema": "cityscroll.capability.entity_relationships_get.input.v1", "input_contract": { "schema": "cityscroll.capability.entity_relationships_get.input.v1", "identity": "exact canonical entity id", "traversal": "incident edges from one root; no graph query language", "nodeTypes": [ "vendor", "agency", "solicitation", "contract", "award", "official", "committee", "community-board", "community-board-committee", "person-leader", "mandate", "project", "procedure", "borough", "community-district", "council-district" ], "leaderDetail": "published agency graph person-leader.available_detail preserves opaque identity, declares no separate dossier, and links the canonical agency dossier leadership field only when the published person identity agrees; observed_on, confidence, and source_limitation bound the assertion", "edgeTypes": [ "named_vendor_on_award", "named_vendor_on_solicitation", "published_by_agency", "references_contract", "votes_on", "member_of", "agency_led_by", "mandate_governs_procedure", "project_participates_in_procedure", "located_in", "covers", "intersects", "has_committee" ], "limits": { "entityIdMaximumLength": 300, "recordLimit": 250, "defaultDepth": 2, "maximumDepth": 2, "defaultFanOut": 12, "maximumFanOut": 25 } }, "output_schema": "cityscroll.capability.entity_relationships_get.output.v1", "output_contract": { "schema": "cityscroll.capability.entity_relationships_get.output.v1", "graphSchema": "public_relationship_graph_v3", "fields": [ "capability_reference", "availability", "graph", "error" ], "availability": [ "available", "not_yet_public", "unavailable" ], "representations": [ { "id": "json", "mediaType": "application/json", "projection": "public relationship graph object" }, { "id": "html", "mediaType": "text/html", "projection": "existing evidence-bearing relationship document" } ], "privateFieldsForbidden": [ "raw_snapshot", "normalized_snapshot", "content_hash", "source_record_id", "link_confidence_score", "matcher_version", "evidence_json", "resolution_run_id", "review_status", "attrs_json" ] }, "bounds": { "input": { "entityIdMaximumLength": 300, "recordLimit": 250, "defaultDepth": 2, "maximumDepth": 2, "defaultFanOut": 12, "maximumFanOut": 25 }, "output": { "maximumEdges": 250 } }, "examples": [ { "input": { "entityId": "vendor:stem:ACME CONSTRUCTION", "depth": 2, "fanOut": 12 }, "output": { "availability": "available", "maximumDepth": 2, "maximumFanOut": 25 } }, { "input": { "entityId": "vendor:unknown" }, "output": { "availability": "not_yet_public", "error": "not-found" } } ], "provenance": { "entityIdentity": "graph.root.id", "relationshipIdentity": "graph.edges[].id", "sourceIdentity": "graph.edges[].provenance.source", "observationClock": "graph.edges[].provenance.observed_at", "evidenceFields": "graph.edges[].provenance.source_fields", "confidence": "graph.edges[].confidence status and basis; no private score" }, "freshness": { "owner": "D1 entity-resolution read model plus committed public graph overlays", "projection": "public serializer and adapter-owned representation" }, "provider": { "id": "worker-d1.entity-relationships", "module": "worker/src/public_relationship_graph.mjs", "export": "workerD1EntityRelationships", "store": "Cloudflare D1 plus committed public graph overlay", "readModel": "canonical entities plus accepted source-record and evaluated public edges" }, "transports": [ { "id": "worker-http.entity-relationships@1", "module": "worker/src/public_relationship_graph.mjs", "kind": "http-route", "route": "GET /entity-relationships", "surface": "Public relationship graph", "representations": [ { "id": "json", "mediaType": "application/json", "projection": "public relationship graph object" }, { "id": "html", "mediaType": "text/html", "projection": "existing evidence-bearing relationship document" } ] }, { "id": "mcp.get_entity_relationships@1", "module": "worker/src/mcp.mjs", "kind": "mcp-tool", "tool": "get_entity_relationships", "route": "POST /mcp", "surface": "MCP" } ] }, { "reference": "cited.passages.retrieve@1", "id": "cited.passages.retrieve", "version": "1.1.0", "title": "Cited Passages Retrieve", "description": "Retrieve source passages with stable citations and exact source joins. Returns source text only. hard_scope.corpus includes observed_on, source_families with coverage and source publication-date bounds, record_count, and passage_count even when no citations match. It does not generate an answer or infer civic relationships.", "owner": "semantic-retrieval", "operation": "read", "authority": { "class": "public-read", "sideEffect": "none", "approval": "none", "semantics": "retrieval evidence only; no answer or inferred civic relationship" }, "cost": { "class": "bounded-committed-corpus-read", "machineFanOut": "low" }, "input_schema": "cityscroll.capability.cited_passages_retrieve.input.v1", "input_contract": { "schema": "cityscroll.capability.cited_passages_retrieve.input.v1", "query": "resident search terms plus closed structured scope", "sourceFamilies": [ "attachment_text", "city_record_notice", "community_board_minutes" ], "limits": { "queryMaximumLength": 240, "bodyIdMaximumLength": 120, "defaultResults": 10, "maximumResults": 20 } }, "output_schema": "cityscroll.semantic_retrieval.cited_passage_response.v1", "output_contract": { "schema": "cityscroll.semantic_retrieval.cited_passage_response.v1", "contractVersion": 1, "fields": [ "schema", "contract_version", "query", "retrieval", "hard_scope", "coverage", "citations" ], "availability": [ "partial", "complete", "unknown" ], "representations": [ { "id": "structured-content", "mediaType": "application/json", "projection": "byte-identical cited passage response" }, { "id": "text-summary", "mediaType": "text/plain", "projection": "meaning-compatible bounded result count" } ], "forbiddenSemantics": [ "answer", "synthesis", "action", "legal_conclusion", "graph_edge", "relationship", "score" ] }, "bounds": { "input": { "queryMaximumLength": 240, "bodyIdMaximumLength": 120, "defaultResults": 10, "maximumResults": 20 }, "output": { "maximumCitations": 20 } }, "examples": [ { "input": { "query": "energy conservation", "filters": { "source_family": "city_record_notice" }, "limit": 5 }, "output": { "availability": "partial", "maximumCitations": 5, "exactJoin": "matched-or-unknown" } }, { "input": { "query": "public hearing", "limit": 10 }, "output": { "availability": "complete-or-partial-or-unknown", "maximumCitations": 10, "exactJoin": "matched-or-unknown" } } ], "provenance": { "citationIdentity": "citations[].citation_id", "sourceIdentity": "citations[].source.id + citations[].source.url", "passageIdentity": "citations[].passage.id", "exactJoinEvidence": "citations[].exact_join_evidence", "corpusScope": "hard_scope.corpus.source_families: per-family observed_on, coverage bounds, retained record counts, and source publication date bounds; hard_scope.corpus includes total record_count and passage_count even for empty results", "corpusReceipt": "retrieval.corpus.manifest_sha256 + retrieval.corpus.content_sha256", "passageMapReceipt": "retrieval.index.version + retrieval.index.corpus_sha256" }, "freshness": { "owner": "committed semantic retrieval corpus manifest and source-passage map", "projection": "citation freshness plus corpus and passage-map observation clocks" }, "provider": { "id": "worker-semantic.cited-passages", "module": "worker/src/cited_retrieval.mjs", "export": "workerCitedPassages", "store": "committed semantic retrieval corpus", "readModel": "typed candidates joined exactly to source passages and corpus manifest records" }, "transports": [ { "id": "worker-http.retrieve-cited-passages@1", "module": "worker/src/cited_retrieval.mjs", "kind": "http-route", "route": "GET /cited-passages", "surface": "Cited passage retrieval", "representations": [ { "id": "structured-content", "mediaType": "application/json", "projection": "byte-identical cited passage response" }, { "id": "text-summary", "mediaType": "text/plain", "projection": "meaning-compatible bounded result count" } ] }, { "id": "mcp.retrieve_cited_passages@1", "module": "worker/src/mcp.mjs", "kind": "mcp-tool", "tool": "retrieve_cited_passages", "route": "POST /mcp", "surface": "MCP", "representations": [ { "id": "structured-content", "mediaType": "application/json", "projection": "byte-identical cited passage response" }, { "id": "text-summary", "mediaType": "text/plain", "projection": "meaning-compatible bounded result count" } ] } ] }, { "reference": "search.federated@1", "id": "search.federated", "version": "1.1.0", "title": "Search Federated", "description": "Search the registered public CityScroll lenses in one bounded result set. Optional scope selects only allowlisted registered lenses. Preserves per-lens coverage, source observations, exact object routes, and federated ranking; it does not expose a raw store or arbitrary query language.", "owner": "universal-search", "operation": "read", "authority": { "class": "public-read", "sideEffect": "none", "approval": "none", "semantics": "bounded SearchDocument federation; no raw store or query language" }, "cost": { "class": "bounded-multi-lens-read", "machineFanOut": "registered-lenses-only" }, "input_schema": "cityscroll.capability.search_federated.input.v1", "input_contract": { "schema": "cityscroll.capability.search_federated.input.v1", "query": "bounded resident search text; no arbitrary filter or store query", "scope": { "schema": "cityscroll.capability.search_federated.scope.v1", "omitted": "legacy all-registered-lens federation, including auxiliary legal-code recall", "lenses": [ "notices", "people", "agencies", "vendors", "committees", "community_boards", "exams", "parcels", "land", "meetings" ], "mapping": "closed allowlist of registered federation lenses; presentation lanes and store queries are rejected" }, "lenses": [ "notices", "people", "agencies", "vendors", "committees", "community_boards", "exams", "parcels", "land", "meetings" ], "limits": { "queryMaximumLength": 240, "defaultResults": 40, "maximumResults": 100, "maximumCards": 8 } }, "output_schema": "cityscroll.universal_search_federator.v1", "output_contract": { "schema": "cityscroll.universal_search_federator.v1", "resultSchema": "cityscroll.universal_search_result.v1", "coverageSchema": "cityscroll.universal_search_coverage.v1", "requestedScopeSchema": "cityscroll.universal_search_requested_scope.v1", "fields": [ "schema", "query", "ranking_policy", "results", "coverage", "requested_scope" ], "coverageStates": [ "matched", "empty", "partial", "stale", "not_indexed", "provider_unavailable", "out_of_scope" ], "requestedCoverageStates": [ "matched", "empty", "partial", "stale", "not_indexed", "provider_unavailable" ], "availability": [ "matched", "empty", "partial", "stale", "not_indexed", "provider_unavailable", "out_of_scope" ], "coverageSemantics": { "matched": "one or more admitted documents were observed", "empty": "the participating indexed lens observed zero matches", "partial": "the lens participated using the available portion of its registered source index", "stale": "the lens result is retained with an out-of-date source clock", "not_indexed": "the lens has no registered served index for this request", "provider_unavailable": "the registered lens provider failed; absence is not an empty result", "out_of_scope": "the lens was not in the requested allowlist and was not queried" }, "representations": [ { "id": "structured-content", "mediaType": "application/json", "projection": "federated result envelope" }, { "id": "http-search", "mediaType": "application/json", "projection": "existing /search lane projection" } ] }, "bounds": { "input": { "queryMaximumLength": 240, "defaultResults": 40, "maximumResults": 100, "maximumCards": 8 }, "output": { "maximumResults": 100, "maximumCardsPerLane": 8 } }, "examples": [ { "input": { "query": "parks", "limit": 10 }, "output": { "coverageStates": [ "matched", "empty", "partial", "stale", "not_indexed", "provider_unavailable", "out_of_scope" ], "maximumResults": 10, "maximumCardsPerLane": 8, "requestedScope": "all_registered_lenses" } }, { "input": { "query": "parks", "limit": 10, "scope": { "schema": "cityscroll.capability.search_federated.scope.v1", "lenses": [ "agencies" ] } }, "output": { "requestedLenses": [ "agencies" ], "unrequestedState": "out_of_scope", "maximumResults": 10 } }, { "input": { "query": "public hearing", "limit": 100 }, "output": { "registeredLenses": [ "notices", "people", "agencies", "vendors", "committees", "community_boards", "exams", "parcels", "land", "meetings" ], "maximumResults": 100, "provenance": "source-observation refs retained" } } ], "provenance": { "objectIdentity": "results[].object_ref", "sourceObservations": "results[].source_observation_refs and results[].edge_provenance.matches[]", "matchEvidence": "results[].match_fields", "exactSourceRoute": "results[].canonical_href", "coverageByLens": "coverage.by_lens[].state and coverage.by_lens[].source", "requestedScope": "requested_scope.lenses and requested_scope.by_lens[].state" }, "freshness": { "owner": "registered lens read models", "projection": "per-lens as_of and coverage state are retained; incomplete coverage is not collapsed" }, "provider": { "id": "worker-federated-search", "module": "worker/src/search.mjs", "export": "workerFederatedSearch", "store": "registered public lens read models", "readModel": "SearchDocument producers plus universal search federator" }, "transports": [ { "id": "worker-http.search.federated@1", "module": "worker/src/search.mjs", "kind": "http-route", "route": "GET /search", "surface": "Universal search" }, { "id": "mcp.search_federated@1", "module": "worker/src/mcp.mjs", "kind": "mcp-tool", "tool": "search_federated", "route": "POST /mcp", "surface": "MCP" } ] }, { "reference": "contract.get@1", "id": "contract.get", "version": "1.0.0", "title": "Contract Get", "description": "Get one public contract by its exact ID. Uses the same Contracts record as CityScroll. Includes source links, coverage, freshness, amount validity, and lifecycle facts when available.", "owner": "procurement", "operation": "read", "authority": { "class": "public-read", "sideEffect": "none", "approval": "none" }, "cost": { "class": "bounded-static-read-model", "machineFanOut": "low" }, "input_schema": "cityscroll.capability.contract_get.input.v1", "input_contract": { "schema": "cityscroll.capability.contract_get.input.v1", "identity": "exact canonical procurement_id", "limits": { "procurementIdMaximumLength": 320, "maximum": 1 } }, "output_schema": "cityscroll.capability.contract_get.output.v1", "output_contract": { "schema": "cityscroll.capability.contract_get.output.v1", "fields": [ "capability_reference", "availability", "contract", "error" ], "availability": [ "available", "not_yet_public", "unavailable" ], "representations": [ { "id": "json", "mediaType": "application/json", "projection": "public procurement object or bounded browse envelope" }, { "id": "text-summary", "mediaType": "text/plain", "projection": "bounded public procurement summary" } ], "privateFieldsForbidden": [ "raw_snapshot", "normalized_snapshot", "content_hash", "evidence_json", "resolution_run_id", "review_status" ] }, "bounds": { "input": { "procurementIdMaximumLength": 320, "maximum": 1 }, "output": { "oneContract": true } }, "examples": [ { "input": { "procurementId": "procurement:contract:20211201861" }, "output": { "availability": "available", "exactIdentity": true, "lifecycle": "preserved when present" } }, { "input": { "procurementId": "procurement:contract:not-published" }, "output": { "availability": "not_yet_public", "error": "not-found" } } ], "provenance": { "identity": "contract.procurement_id (materialized from exact publisher identifiers)", "sourceIdentity": "contract.provenance.source_observations[].source_observation_ref", "observationClock": "contract.freshness.as_of plus source_observations[].ingested_at", "identityAuthority": "site/procurement_object_contract.mjs exact identity gate" }, "freshness": { "owner": "shared procurement read model", "projection": "read-model generated_at, checked_at, and source envelopes" }, "provider": { "id": "worker-static.procurement-contract.get", "module": "worker/src/contracts.mjs", "export": "workerProcurementContracts", "store": "precomputed shared procurement read model", "readModel": "observation-fed procurement objects" }, "transports": [ { "id": "worker-http.contract-get@1", "module": "worker/src/contracts.mjs", "kind": "http-route", "route": "GET /contract", "surface": "Contract detail", "representations": [ { "id": "json", "mediaType": "application/json", "projection": "public procurement object or bounded browse envelope" }, { "id": "text-summary", "mediaType": "text/plain", "projection": "bounded public procurement summary" } ] }, { "id": "mcp.get_contract@1", "module": "worker/src/mcp.mjs", "kind": "mcp-tool", "tool": "get_contract", "route": "POST /mcp", "surface": "MCP", "representations": [ { "id": "json", "mediaType": "application/json", "projection": "public procurement object or bounded browse envelope" }, { "id": "text-summary", "mediaType": "text/plain", "projection": "bounded public procurement summary" } ] } ] }, { "reference": "contracts.browse@1", "id": "contracts.browse", "version": "1.1.0", "title": "Contracts Browse", "description": "List public Contracts records with bounded filters and pages. Results keep exact contract IDs separate, including records that share a PIN. Use population=registered with the analysis continuation arguments for exact analytical groups: this returns registration id, procurement_id and href, including registrations with no detail record.", "owner": "procurement", "operation": "read", "authority": { "class": "public-read", "sideEffect": "none", "approval": "none" }, "cost": { "class": "bounded-static-read-model", "machineFanOut": "low" }, "input_schema": "cityscroll.capability.contracts_browse.input.v1", "input_contract": { "schema": "cityscroll.capability.contracts_browse.input.v1", "identity": "one result per exact canonical procurement_id", "filters": { "population": "registered selects exact analytical rows and returns id/procurement_id/href references, including rows without detail records; groupBy/groupLabel restrict an exact group including unknown labels", "query": "case-insensitive token match over the existing Contracts browse projection", "agency": "case-insensitive substring", "vendor": "case-insensitive substring", "stage": "exact stage value", "sourceSystem": "exact source-system value", "minAmount": "inclusive valid public amount floor", "maxAmount": "inclusive valid public amount ceiling" }, "ordering": "canonical procurement_id ascending", "pagination": "opaque cursor after the last canonical procurement_id", "limits": { "filterMaximumLength": 240, "cursorMaximumLength": 320, "minimum": 1, "maximum": 100, "default": 25 } }, "output_schema": "cityscroll.capability.contracts_browse.output.v1", "output_contract": { "schema": "cityscroll.capability.contracts_browse.output.v1", "fields": [ "capability_reference", "availability", "results", "total_matches", "pagination", "coverage", "freshness", "error" ], "availability": [ "complete", "empty", "unavailable" ], "representations": [ { "id": "json", "mediaType": "application/json", "projection": "public procurement object or bounded browse envelope" }, { "id": "text-summary", "mediaType": "text/plain", "projection": "bounded public procurement summary" } ], "privateFieldsForbidden": [ "raw_snapshot", "normalized_snapshot", "content_hash", "evidence_json", "resolution_run_id", "review_status" ] }, "bounds": { "input": { "filterMaximumLength": 240, "cursorMaximumLength": 320, "minimum": 1, "maximum": 100, "default": 25 }, "output": { "maximumResults": 100 } }, "examples": [ { "input": { "agency": "design and construction", "stage": "award", "limit": 10 }, "output": { "availability": "complete", "maximumResults": 10, "oneRowPer": "exact procurement_id" } }, { "input": { "sourceSystem": "passport_public_contracts", "limit": 25 }, "output": { "availability": "complete", "pagination": "cursor when more rows remain" } } ], "provenance": { "identity": "contract.procurement_id (materialized from exact publisher identifiers)", "sourceIdentity": "contract.provenance.source_observations[].source_observation_ref", "observationClock": "contract.freshness.as_of plus source_observations[].ingested_at", "identityAuthority": "site/procurement_object_contract.mjs exact identity gate" }, "freshness": { "owner": "shared procurement read model", "projection": "read-model generated_at, checked_at, and source envelopes" }, "provider": { "id": "worker-static.procurement-contracts.browse", "module": "worker/src/contracts.mjs", "export": "workerProcurementContracts", "store": "precomputed shared procurement read model", "readModel": "observation-fed procurement objects" }, "transports": [ { "id": "worker-http.contracts-browse@1", "module": "worker/src/contracts.mjs", "kind": "http-route", "route": "GET /contracts", "surface": "Contracts browse", "representations": [ { "id": "json", "mediaType": "application/json", "projection": "public procurement object or bounded browse envelope" }, { "id": "text-summary", "mediaType": "text/plain", "projection": "bounded public procurement summary" } ] }, { "id": "mcp.browse_contracts@1", "module": "worker/src/mcp.mjs", "kind": "mcp-tool", "tool": "browse_contracts", "route": "POST /mcp", "surface": "MCP", "representations": [ { "id": "json", "mediaType": "application/json", "projection": "public procurement object or bounded browse envelope" }, { "id": "text-summary", "mediaType": "text/plain", "projection": "bounded public procurement summary" } ] } ] }, { "reference": "contracts.analysis@1", "id": "contracts.analysis", "version": "1.2.0", "title": "Contracts Analysis", "description": "Rank groups by agency, vendor, fiscal year, or amount band. Uses the registered-contract population. Reports registered value or contract count, a scope denominator, and coverage. Each group gives contract_count, contract_sample (default 10, maximum 50; id, procurement_id, canonical href), and an exact browse_contracts continuation. Null procurement_id/href means no individual detail record is published. Groups are paginated in filters.pagination to keep research responses below 64 KiB; repeat the same filters with next_cursor. Does not report payments or spending. Omit agency to discover filters.discovery.agency.accepted_labels; retry an unrecognized label using a suggested exact label. fiscal_year is derived from registration date, July 1 through June 30.", "owner": "procurement", "operation": "read", "authority": { "class": "public-read", "sideEffect": "none", "approval": "none" }, "cost": { "class": "bounded-static-read-model", "machineFanOut": "low" }, "input_schema": "cityscroll.capability.contracts_analysis.input.v1", "input_contract": { "schema": "cityscroll.capability.contracts_analysis.input.v1", "identity": "one row per exact prime_contract_id in the registered-contract projection", "groupings": [ "agency", "vendor", "registration_fiscal_year", "amount_band" ], "measures": [ "current", "original", "count" ], "filters": { "agency": "case-sensitive exact projected agency label; call without agency and read filters.discovery.agency.accepted_labels before filtering", "vendor": "case-sensitive exact projected prime-vendor label", "fiscalYear": "NYC registration fiscal year derived from registration date: July 1 of the preceding year through June 30; not award, payment, or source partition year", "amountBand": "exact versioned current registered-value band", "minAmount": "inclusive current registered-value floor", "maxAmount": "inclusive current registered-value ceiling", "retroactive": "only rows with a published registration/start-date comparison", "cityRecordMatch": "exact, none, or cannot_evaluate_missing_pin" }, "limits": { "filterMaximumLength": 240, "minimumGroups": 1, "maximumGroups": 100, "defaultGroups": 10, "defaultSample": 10, "maximumSample": 50, "maximumResponseBytes": 57344 } }, "output_schema": "cityscroll.capability.contracts_analysis.output.v1", "output_contract": { "schema": "cityscroll.capability.contracts_analysis.output.v1", "fields": [ "capability_reference", "availability", "group_by", "measure", "groups", "denominator", "population", "coverage", "contract_detail", "filters", "freshness", "error" ], "filterDiscovery": "filters.discovery publishes accepted agency labels, suggestions for unrecognized labels, and registration fiscal-year semantics independently of the selected result population", "availability": [ "complete", "empty", "unavailable" ], "representations": [ { "id": "json", "mediaType": "application/json", "projection": "bounded grouped registered-contract analysis" }, { "id": "text-summary", "mediaType": "text/plain", "projection": "bounded grouped registered-contract analysis summary" } ], "privateFieldsForbidden": [ "raw_snapshot", "normalized_snapshot", "content_hash", "evidence_json", "resolution_run_id", "review_status" ] }, "bounds": { "input": { "filterMaximumLength": 240, "minimumGroups": 1, "maximumGroups": 100, "defaultGroups": 10, "defaultSample": 10, "maximumSample": 50, "maximumResponseBytes": 57344 }, "output": { "maximumGroups": 100, "maximumSample": 50, "maximumBytes": 57344, "pagination": "filters.pagination; pages may be shorter than limit to fit the byte budget", "legacyIdentifiers": "HTTP identifiers=full only; outside the research response budget" } }, "examples": [ { "input": { "groupBy": "agency", "measure": "current", "fiscalYear": 2027, "limit": 10 }, "output": { "availability": "complete", "measure": "current registered contract value in USD", "denominator": "selected filtered population value" } }, { "input": { "groupBy": "vendor", "measure": "count", "agency": "Department of Education" }, "output": { "availability": "complete", "measure": "unique registered contracts", "drillThrough": "contract_sample and exact registered-population contracts.browse@1 continuation" } } ], "provenance": { "population": "site/data/analytics_registered_contracts.json", "identity": "prime_contract_id (exact registered-contract identity)", "drillThrough": "ordinary Contracts scope with exact contributing contract identifiers", "contractDetail": "each contributing registration identifier is resolved to the canonical procurement id contract.get@1 accepts, or reported as not individually retrievable with a reason" }, "freshness": { "owner": "committed registered-contract analytical projection", "projection": "generated_at and snapshot_date" }, "provider": { "id": "worker-static.procurement-contracts.analysis", "module": "worker/src/contracts.mjs", "export": "workerContractsAnalysis", "store": "precomputed registered-contract analytical projection", "readModel": "site/data/analytics_registered_contracts.json" }, "transports": [ { "id": "worker-http.contracts-analysis@1", "module": "worker/src/contracts.mjs", "kind": "http-route", "route": "GET /contracts/analysis", "surface": "Contracts analysis", "representations": [ { "id": "json", "mediaType": "application/json", "projection": "bounded grouped registered-contract analysis" }, { "id": "text-summary", "mediaType": "text/plain", "projection": "bounded grouped registered-contract analysis summary" } ] }, { "id": "mcp.analyze_contracts@1", "module": "worker/src/mcp.mjs", "kind": "mcp-tool", "tool": "analyze_contracts", "route": "POST /mcp", "surface": "MCP", "representations": [ { "id": "json", "mediaType": "application/json", "projection": "bounded grouped registered-contract analysis" }, { "id": "text-summary", "mediaType": "text/plain", "projection": "bounded grouped registered-contract analysis summary" } ] } ] }, { "reference": "people.get@1", "id": "people.get", "version": "1.0.0", "title": "People Get", "description": "Get one exact typed person or organization row from the published People and organizations read model. Display names never create identity; relation states and source fields are preserved.", "owner": "people-organizations", "operation": "read", "authority": { "class": "public-read", "sideEffect": "none", "approval": "none" }, "cost": { "class": "bounded-static-read-model", "machineFanOut": "low" }, "input_schema": "cityscroll.capability.people_get.input.v1", "input_contract": { "schema": "cityscroll.capability.people_get.input.v1", "identity": "exact canonical people/organization row id", "limits": { "entityIdMaximumLength": 320, "maximum": 1 } }, "output_schema": "cityscroll.capability.people_get.output.v1", "output_contract": { "schema": "cityscroll.capability.people_get.output.v1", "fields": [ "capability_reference", "availability", "person_or_organization", "error" ], "availability": [ "available", "not_yet_public", "unavailable" ], "representations": [ { "id": "json", "mediaType": "application/json", "projection": "typed public people or organization row" }, { "id": "text-summary", "mediaType": "text/plain", "projection": "bounded public row summary" } ], "privateFieldsForbidden": [ "raw_snapshot", "normalized_snapshot", "content_hash", "evidence_json", "resolution_run_id" ], "presentationOnlyOmitted": [ "search_text" ] }, "bounds": { "input": { "entityIdMaximumLength": 320, "maximum": 1 }, "output": { "oneRow": true } }, "examples": [ { "input": { "entityId": "official:example" }, "output": { "availability": "available", "exactIdentity": true } }, { "input": { "entityId": "agency:id:not-published" }, "output": { "availability": "not_yet_public", "error": "not-found" } } ], "provenance": { "identity": "row.id from site/people_organizations_read_model.mjs; display names never mint identity", "sourceIdentity": "row.source_record_id when the source publishes one; otherwise the source-specific identity fields are retained", "observationClock": "read-model generated_at", "identityAuthority": "site/people_organizations_read_model.mjs exact row construction" }, "freshness": { "owner": "people and organizations read model", "projection": "read-model generated_at" }, "provider": { "id": "worker-static.people-organizations.get", "module": "worker/src/people_organizations.mjs", "export": "workerPeopleOrganizations", "store": "precomputed people and organizations read model", "readModel": "typed People + organizations rows" }, "transports": [ { "id": "worker-http.people-get@1", "module": "worker/src/people_organizations.mjs", "kind": "http-route", "route": "GET /people-organizations?id=", "surface": "People and organizations", "representations": [ { "id": "json", "mediaType": "application/json", "projection": "typed public people or organization row" }, { "id": "text-summary", "mediaType": "text/plain", "projection": "bounded public row summary" } ] }, { "id": "mcp.get_person_or_organization@1", "module": "worker/src/mcp.mjs", "kind": "mcp-tool", "tool": "get_person_or_organization", "route": "POST /mcp", "surface": "MCP", "representations": [ { "id": "json", "mediaType": "application/json", "projection": "typed public people or organization row" }, { "id": "text-summary", "mediaType": "text/plain", "projection": "bounded public row summary" } ] } ] }, { "reference": "organizations.browse@1", "id": "organizations.browse", "version": "1.1.0", "title": "Organizations Browse", "description": "Browse the bounded typed People and organizations snapshot with exact row-kind and token filters. Results retain published, empty, or unknown relation states and read-model freshness.", "owner": "people-organizations", "operation": "read", "authority": { "class": "public-read", "sideEffect": "none", "approval": "none" }, "cost": { "class": "bounded-static-read-model", "machineFanOut": "low" }, "input_schema": "cityscroll.capability.organizations_browse.input.v1", "input_contract": { "schema": "cityscroll.capability.organizations_browse.input.v1", "filters": { "query": "case-insensitive token match over the existing read-model search_text projection", "kind": "exact row kind from the closed vocabulary" }, "ordering": "row kind order, then label, then exact row id (the existing read-model order)", "pagination": "opaque cursor after the last exact row id", "limits": { "queryMaximumLength": 240, "kindMaximumLength": 80, "cursorMaximumLength": 320, "minimum": 1, "maximum": 100, "default": 25 } }, "output_schema": "cityscroll.capability.organizations_browse.output.v1", "output_contract": { "schema": "cityscroll.capability.organizations_browse.output.v1", "fields": [ "capability_reference", "availability", "results", "total_matches", "pagination", "coverage", "freshness", "error" ], "availability": [ "complete", "empty", "unavailable" ], "representations": [ { "id": "json", "mediaType": "application/json", "projection": "typed public people or organization row" }, { "id": "text-summary", "mediaType": "text/plain", "projection": "bounded public row summary" } ], "privateFieldsForbidden": [ "raw_snapshot", "normalized_snapshot", "content_hash", "evidence_json", "resolution_run_id" ], "presentationOnlyOmitted": [ "search_text" ] }, "bounds": { "input": { "queryMaximumLength": 240, "kindMaximumLength": 80, "cursorMaximumLength": 320, "minimum": 1, "maximum": 100, "default": 25 }, "output": { "maximumResults": 100 } }, "examples": [ { "input": { "kind": "agency", "limit": 10 }, "output": { "availability": "complete", "maximumResults": 10, "oneRowPer": "exact read-model row id" } }, { "input": { "query": "community board", "limit": 25 }, "output": { "availability": "complete", "pagination": "cursor when more rows remain" } } ], "provenance": { "identity": "row.id from site/people_organizations_read_model.mjs; display names never mint identity", "sourceIdentity": "row.source_record_id when the source publishes one; otherwise the source-specific identity fields are retained", "observationClock": "read-model generated_at", "identityAuthority": "site/people_organizations_read_model.mjs exact row construction" }, "freshness": { "owner": "people and organizations read model", "projection": "read-model generated_at" }, "provider": { "id": "worker-static.people-organizations.browse", "module": "worker/src/people_organizations.mjs", "export": "workerPeopleOrganizations", "store": "precomputed people and organizations read model", "readModel": "typed People + organizations rows" }, "transports": [ { "id": "worker-http.organizations-browse@1", "module": "worker/src/people_organizations.mjs", "kind": "http-route", "route": "GET /people-organizations", "surface": "People and organizations browse", "representations": [ { "id": "json", "mediaType": "application/json", "projection": "typed public people or organization row" }, { "id": "text-summary", "mediaType": "text/plain", "projection": "bounded public row summary" } ] }, { "id": "mcp.browse_organizations@1", "module": "worker/src/mcp.mjs", "kind": "mcp-tool", "tool": "browse_organizations", "route": "POST /mcp", "surface": "MCP", "representations": [ { "id": "json", "mediaType": "application/json", "projection": "typed public people or organization row" }, { "id": "text-summary", "mediaType": "text/plain", "projection": "bounded public row summary" } ] } ] }, { "reference": "meeting.get@1", "id": "meeting.get", "version": "1.1.0", "title": "Meeting Get", "description": "Get one exact source-qualified meeting from the shared CityScroll meeting read model. Preserves source receipt, coverage, freshness, and attached meeting documents. source_presence, source_observation, minutes, and city_record_join are independent states; no notice join does not mean no source meeting.", "owner": "meetings", "operation": "read", "authority": { "class": "public-read", "sideEffect": "none", "approval": "none" }, "cost": { "class": "bounded-static-read-model", "machineFanOut": "one-record" }, "input_schema": "cityscroll.capability.meeting_get.input.v1", "input_contract": { "schema": "cityscroll.capability.meeting_get.input.v1", "identity": "exact source-qualified meeting_id; legacy City Record ids are adapter compatibility only", "limits": { "meetingIdMaximumLength": 320, "maximum": 1 } }, "output_schema": "cityscroll.capability.meeting_get.output.v1", "output_contract": { "schema": "cityscroll.capability.meeting_get.output.v1", "recordStates": "meeting.source_presence (present), source_observation (observed_at/observed_on), minutes (publisher status or unknown), city_record_join (source_record/matched/none/unknown); absent joins never erase publisher meeting identity or board_ref", "fields": [ "capability_reference", "availability", "meeting", "source", "coverage", "freshness", "error" ], "availability": [ "available", "not_yet_public", "unavailable" ], "representations": [ { "id": "json", "mediaType": "application/json", "projection": "one shared meeting row" }, { "id": "text-summary", "mediaType": "text/plain", "projection": "one shared meeting summary" } ] }, "bounds": { "input": { "meetingIdMaximumLength": 320, "maximum": 1 }, "output": { "maximumResults": 1 } }, "examples": [ { "input": { "meetingId": "meeting:city_record:20260810053" }, "output": { "availability": "available", "source": "city_record", "exactIdentity": true } }, { "input": { "meetingId": "meeting:community_board:unpublished" }, "output": { "availability": "not_yet_public", "error": "not-found" } } ], "provenance": { "identity": "meeting.meeting_id", "sourceObservation": "meeting.source_record and meeting.source_receipt", "coverage": "source and freshness envelopes from shared meeting read model" }, "freshness": { "owner": "committed shared meeting read model", "projection": "generated_at, checked_at, and per-source status" }, "provider": { "id": "worker-static.shared-meeting.get", "module": "worker/src/hearings.mjs", "export": "workerMeetingGet", "store": "precomputed shared meeting read model in KV or Pages", "readModel": "cityscroll.shared_meeting_read_model.v1" }, "transports": [ { "id": "worker-http.meeting-get@1", "module": "worker/src/hearings.mjs", "kind": "http-route", "route": "GET /hearings?id=…", "surface": "Meeting detail", "representations": [ { "id": "json", "mediaType": "application/json", "projection": "one shared meeting row" }, { "id": "text-summary", "mediaType": "text/plain", "projection": "one shared meeting summary" } ] }, { "id": "mcp.get_meeting@1", "module": "worker/src/mcp.mjs", "kind": "mcp-tool", "tool": "get_meeting", "route": "POST /mcp", "surface": "MCP", "representations": [ { "id": "json", "mediaType": "application/json", "projection": "one shared meeting row" }, { "id": "text-summary", "mediaType": "text/plain", "projection": "one shared meeting summary" } ] } ] }, { "reference": "land.project.get@1", "id": "land.project.get", "version": "1.0.0", "title": "Land Project Get", "description": "Get one exact Land (ZAP) project by its ZAP project id. Includes its deep link, status, geography, applicant, review procedure, exact actions and ids, environmental facts, milestones, outcomes, sources, and any conflicts, when known.", "owner": "land", "operation": "read", "authority": { "class": "public-read", "sideEffect": "none", "approval": "none" }, "cost": { "class": "bounded-static-read-model", "machineFanOut": "low" }, "input_schema": "cityscroll.capability.land_project_get.input.v1", "input_contract": { "schema": "cityscroll.capability.land_project_get.input.v1", "identity": "exact publisher ZAP project_id", "limits": { "projectIdMaximumLength": 32, "maximum": 1 } }, "output_schema": "cityscroll.capability.land_project_get.output.v1", "output_contract": { "schema": "cityscroll.capability.land_project_get.output.v1", "fields": [ "capability_reference", "availability", "project", "error" ], "availability": [ "available", "not_yet_public", "unavailable" ], "representations": [ { "id": "json", "mediaType": "application/json", "projection": "public Land project object or bounded browse envelope" }, { "id": "text-summary", "mediaType": "text/plain", "projection": "bounded public Land project summary" } ], "privateFieldsForbidden": [ "raw_snapshot", "content_hash", "resolution_run_id", "review_status" ] }, "bounds": { "input": { "projectIdMaximumLength": 32, "maximum": 1 }, "output": { "oneProject": true } }, "examples": [ { "input": { "projectId": "2024Q0356" }, "output": { "availability": "available", "exactIdentity": true, "procedureResolution": "preserved when resolvable" } }, { "input": { "projectId": "not-a-real-project" }, "output": { "availability": "not_yet_public", "error": "not-found" } } ], "provenance": { "identity": "project.project_id (exact publisher ZAP project identity)", "sourceIdentity": "project.source_observations[].source_system", "observationClock": "project.freshness.as_of plus source_observations[].generated_at", "identityAuthority": "site/land_action_procedure_resolution.mjs resolveLandActionProcedures" }, "freshness": { "owner": "shared Land ZAP read model", "projection": "committed warehouse materialized_at plus per-source generated_at" }, "provider": { "id": "worker-static.land-project.get", "module": "worker/src/land_projects.mjs", "export": "workerLandProjects", "store": "precomputed shared Land ZAP read model", "readModel": "warehouse-materialized ZAP projects, overlaid with exact materialized ZAP outcome evidence" }, "transports": [ { "id": "worker-http.land-project-get@1", "module": "worker/src/land_projects.mjs", "kind": "http-route", "route": "GET /land-project", "surface": "Land project detail", "representations": [ { "id": "json", "mediaType": "application/json", "projection": "public Land project object or bounded browse envelope" }, { "id": "text-summary", "mediaType": "text/plain", "projection": "bounded public Land project summary" } ] }, { "id": "mcp.get_land_project@1", "module": "worker/src/mcp.mjs", "kind": "mcp-tool", "tool": "get_land_project", "route": "POST /mcp", "surface": "MCP", "representations": [ { "id": "json", "mediaType": "application/json", "projection": "public Land project object or bounded browse envelope" }, { "id": "text-summary", "mediaType": "text/plain", "projection": "bounded public Land project summary" } ] } ] }, { "reference": "land.projects.browse@1", "id": "land.projects.browse", "version": "1.0.0", "title": "Land Projects Browse", "description": "List public Land (ZAP) projects using the same filters as the Land page: review procedure, action type, stage, effect, and geography. Reads the full warehouse, not just active projects, so completed and past projects stay reachable too.", "owner": "land", "operation": "read", "authority": { "class": "public-read", "sideEffect": "none", "approval": "none" }, "cost": { "class": "bounded-static-read-model", "machineFanOut": "low" }, "input_schema": "cityscroll.capability.land_projects_browse.input.v1", "input_contract": { "schema": "cityscroll.capability.land_projects_browse.input.v1", "identity": "one result per exact canonical project_id", "filters": { "status": "resident Land status vocabulary (site/land_filter_parity.mjs LAND_FILTER_DIMENSIONS); defaults to every status, never active-only", "stage": "resident Land review-stage facet (any, active, public_review, pre_certification, community_board, borough_president, cpc, city_council, completed)", "procedure": "ULURP/ELURP/Non-ULURP review-procedure facet (review, ulurp, elurp, non_ulurp)", "family": "closed action-family facet (any, acquisition, disposition, certification, renewal, major_concession, legal_document, rezoning, special_permit, authorization, site_selection, mapping, demapping, urban_renewal, landmark, follow_up, office_space, bid, franchise_consent, housing_plan, pops, landfill)", "regulatoryEffect": "closed regulatory-effect facet (any, upzone, downzone, mixed, no_density_change)", "borough": "exact borough name", "communityDistrict": "borough-lettered community district", "councilDistrict": "council district 1-51", "query": "case-insensitive free text over the row", "corpus": "'live' reads the current committed complete warehouse; 'historical' reads the frozen expedited-procedure regression corpus" }, "ordering": "same ordering as the resident Land query (site/resident_snapshot_queries.mjs filterLandSnapshot)", "pagination": "opaque cursor after the last canonical project_id", "limits": { "filterMaximumLength": 240, "cursorMaximumLength": 320, "minimum": 1, "maximum": 100, "default": 25 } }, "output_schema": "cityscroll.capability.land_projects_browse.output.v1", "output_contract": { "schema": "cityscroll.capability.land_projects_browse.output.v1", "fields": [ "capability_reference", "availability", "results", "total_matches", "pagination", "coverage", "freshness", "error" ], "availability": [ "complete", "empty", "unavailable" ], "representations": [ { "id": "json", "mediaType": "application/json", "projection": "public Land project object or bounded browse envelope" }, { "id": "text-summary", "mediaType": "text/plain", "projection": "bounded public Land project summary" } ], "privateFieldsForbidden": [ "raw_snapshot", "content_hash", "resolution_run_id", "review_status" ] }, "bounds": { "input": { "filterMaximumLength": 240, "cursorMaximumLength": 320, "minimum": 1, "maximum": 100, "default": 25 }, "output": { "maximumResults": 100 } }, "examples": [ { "input": { "procedure": "elurp", "corpus": "historical" }, "output": { "availability": "complete", "oneRowPer": "exact project_id", "fixedPopulation": "the frozen four-project expedited corpus" } }, { "input": { "procedure": "elurp", "limit": 25 }, "output": { "availability": "complete", "pagination": "cursor when more rows remain", "fixedPopulation": "none — reflects the current committed warehouse" } } ], "provenance": { "identity": "project.project_id (exact publisher ZAP project identity)", "sourceIdentity": "project.source_observations[].source_system", "observationClock": "project.freshness.as_of plus source_observations[].generated_at", "identityAuthority": "site/land_action_procedure_resolution.mjs resolveLandActionProcedures" }, "freshness": { "owner": "shared Land ZAP read model", "projection": "committed warehouse materialized_at plus per-source generated_at" }, "provider": { "id": "worker-static.land-projects.browse", "module": "worker/src/land_projects.mjs", "export": "workerLandProjects", "store": "precomputed shared Land ZAP read model", "readModel": "complete warehouse-materialized ZAP projects (every publisher status, not an active-only slice)" }, "transports": [ { "id": "worker-http.land-projects-browse@1", "module": "worker/src/land_projects.mjs", "kind": "http-route", "route": "GET /land-projects", "surface": "Land projects browse", "representations": [ { "id": "json", "mediaType": "application/json", "projection": "public Land project object or bounded browse envelope" }, { "id": "text-summary", "mediaType": "text/plain", "projection": "bounded public Land project summary" } ] }, { "id": "mcp.browse_land_projects@1", "module": "worker/src/mcp.mjs", "kind": "mcp-tool", "tool": "browse_land_projects", "route": "POST /mcp", "surface": "MCP", "representations": [ { "id": "json", "mediaType": "application/json", "projection": "public Land project object or bounded browse envelope" }, { "id": "text-summary", "mediaType": "text/plain", "projection": "bounded public Land project summary" } ] } ] }, { "reference": "land.decision_path.get@1", "id": "land.decision_path.get", "version": "1.0.0", "title": "Land Decision Path Get", "description": "Get the typed Land decision path for one exact project. Observed milestones and events remain separate from the reviewed normative procedure stages, actors, effects, and parallel review groups; absent and unknown stages stay explicit.", "owner": "land", "operation": "read", "authority": { "class": "public-read", "sideEffect": "none", "approval": "none" }, "cost": { "class": "bounded-static-read-model", "machineFanOut": "low" }, "input_schema": "cityscroll.capability.land_decision_path_get.input.v1", "input_contract": { "schema": "cityscroll.capability.land_decision_path_get.input.v1", "identity": "exact publisher ZAP project_id", "limits": { "projectIdMaximumLength": 32, "maximum": 1 } }, "output_schema": "cityscroll.capability.land_decision_path_get.output.v1", "output_contract": { "schema": "cityscroll.capability.land_decision_path_get.output.v1", "fields": [ "capability_reference", "availability", "project_id", "decision_path", "error" ], "availability": [ "available", "not_yet_public", "unavailable" ], "resolutions": [ "uniform", "mixed", "unknown" ], "representations": [ { "id": "json", "mediaType": "application/json", "projection": "observed and normative Land decision-path view" }, { "id": "text-summary", "mediaType": "text/plain", "projection": "bounded Land decision-path summary" } ], "privateFieldsForbidden": [ "raw_snapshot", "content_hash", "resolution_run_id", "review_status" ], "layerContract": { "observed": [ "observed_current_phase", "observed_events", "observed.gaps" ], "normative": [ "normative_current_stage", "current_actors", "expected_next_transition", "parallel_review_groups", "normative_stages" ], "groupedProjection": { "observed": [ "current_phase", "events", "gaps" ], "normative": [ "current_stage", "current_actors", "expected_next_transition", "parallel_review_groups", "stages" ] }, "rule": "observed events never appear under normative keys and normative stages never appear under observed keys" } }, "bounds": { "input": { "projectIdMaximumLength": 32, "maximum": 1 }, "output": { "oneProject": true } }, "examples": [ { "input": { "projectId": "2024Q0356" }, "output": { "availability": "available", "procedureResolution": "uniform", "parallelReviewGroups": 1 } }, { "input": { "projectId": "not-a-real-project" }, "output": { "availability": "not_yet_public", "error": "not-found" } } ], "provenance": { "identity": "decision_path.project_id (exact publisher ZAP project identity)", "sourceIdentity": "evidence[].source_id", "observationClock": "observed.current_phase and observed.events source times", "identityAuthority": "site/land_decision_path.mjs buildLandDecisionPathView" }, "freshness": { "owner": "shared Land ZAP read model", "projection": "committed warehouse materialized_at plus per-source generated_at" }, "provider": { "id": "worker-static.land-decision-path.get", "module": "worker/src/land_projects.mjs", "export": "workerLandProjects", "store": "precomputed shared Land ZAP read model", "readModel": "the same resident Land phase spine and reviewed procedure profile used by the detail interface" }, "transports": [ { "id": "worker-http.land-decision-path-get@1", "module": "worker/src/land_projects.mjs", "kind": "http-route", "route": "GET /land-decision-path", "surface": "Land project decision path", "representations": [ { "id": "json", "mediaType": "application/json", "projection": "observed and normative Land decision-path view" }, { "id": "text-summary", "mediaType": "text/plain", "projection": "bounded Land decision-path summary" } ] }, { "id": "mcp.get_land_decision_path@1", "module": "worker/src/mcp.mjs", "kind": "mcp-tool", "tool": "get_land_decision_path", "route": "POST /mcp", "surface": "MCP", "representations": [ { "id": "json", "mediaType": "application/json", "projection": "observed and normative Land decision-path view" }, { "id": "text-summary", "mediaType": "text/plain", "projection": "bounded Land decision-path summary" } ] } ] } ] }