# INITKOA CONTEXT PACK repository: Rejean-McCormick/Kristal_Farms source_path: C:\mycode\Kristal_Farms\kristal-farms source_commit: 1a542833e81ee1d4297dc9e0fc18368133f8188c source_mode: git working_tree_markdown: clean working_tree_selected: clean selection_mode: curated wiki_source_path: C:\mycode\Kristal_Farms\Kristal_Farms.wiki wiki_source_commit: excluded-by-policy wiki_working_tree_markdown: excluded policy_version: 2026-09-01.11 repo_files: 136 wiki_files: 0 source_files: 136 included_files: 136 excluded_files: 0 duplicate_files: 0 content_bytes: 336464 authority_counts: {"canonical":20,"reference":116} generated_at: 2026-09-10T11:11:47-04:00 files: 136 content_sha256: 1c99b544aaf3e8188b00c9a0b1ac35403e9fbba877d0fdbf8ee9ee20914c337a ================================================================================================ FILE INDEX ================================================================================================ 001. [canonical] README.md 002. [canonical] docs/00-control/DOCUMENT_AUTHORITY.md 003. [canonical] docs/00-control/MASTER_INDEX.md 004. [canonical] docs/00-control/PROJECT_STATE.md 005. [canonical] docs/00-control/STRATEGIC_PRINCIPLES.md 006. [canonical] docs/00-control/SCOPE_BOUNDARIES.md 007. [reference] docs/10-core/deployment/DEPLOYMENT_STRATEGY_EN.md 008. [reference] docs/10-core/tenancy/BLACK_BOX_TENANCY_MODEL_EN.md 009. [reference] docs/architecture/overview.md 010. [reference] docs/architecture/workspace-boundaries.md 011. [reference] docs/domain/kristal-farms-principles.md 012. [reference] docs/product/vision.md 013. [reference] docs/data/data-model.md 014. [reference] docs/data/evidence-model.md 015. [reference] contracts/policy/kristal-farms-policy.yaml 016. [canonical] AGENTS.md 017. [reference] contracts/api/kristal-farms-api.openapi.yaml 018. [reference] contracts/ingestion/import-manifest.schema.json 019. [reference] contracts/layers/layer-catalog.example.yaml 020. [reference] contracts/layers/layer-catalog.schema.json 021. [reference] contracts/policy/international-tenant-governance.yaml 022. [reference] contracts/policy/jurisdiction-eligibility.yaml 023. [reference] contracts/reference/data-classification.yaml 024. [reference] contracts/reference/status-enums.yaml 025. [reference] contracts/releases/release-manifest.example.json 026. [reference] contracts/releases/release-manifest.schema.json 027. [reference] contracts/schemas/electrical-projects.schema.json 028. [reference] contracts/schemas/evidence.schema.json 029. [reference] contracts/schemas/observation.schema.json 030. [reference] contracts/schemas/scenario.schema.json 031. [reference] contracts/schemas/source.schema.json 032. [reference] contracts/schemas/target-village-dossier.schema.json 033. [reference] contracts/schemas/tenant-eligibility-record.schema.json 034. [reference] contracts/story/showcase-story.example.yaml 035. [reference] contracts/story/showcase-story.schema.json 036. [canonical] docs/00-control/CLAIMS_TO_VALIDATE.md 037. [canonical] docs/00-control/CORRIDOR_DOSSIER_STRATEGY.md 038. [canonical] docs/00-control/DECISIONS_REQUIRED.md 039. [canonical] docs/00-control/INTERNATIONAL_TENANT_GOVERNANCE.md 040. [canonical] docs/00-control/QA_REPORT.md 041. [canonical] docs/00-control/RELEASE_STATUS.md 042. [canonical] docs/00-control/SOURCE_TRACEABILITY.md 043. [canonical] docs/00-control/WORKSTREAMS.md 044. [reference] docs/10-core/Architecture_de_reference_du_projet_Kristal_Farms_FR.md 045. [reference] docs/10-core/deployment/STRATEGIE_DE_DEPLOIEMENT_FR.md 046. [reference] docs/10-core/Kristal_Farms_Project_Reference_Architecture_EN.md 047. [reference] docs/10-core/strategy/KRISTAL_FARMS_VISION_EN.md 048. [reference] docs/10-core/strategy/PLAN_MOBILISATION_INTERNATIONALE_KRISTAL_FARMS_FR.md 049. [reference] docs/10-core/strategy/VISION_KRISTAL_FARMS_FR.md 050. [reference] docs/10-core/tenancy/MODELE_LOCATION_BLACK_BOX_FR.md 051. [reference] docs/adr/0000-template.md 052. [reference] docs/adr/0001-maplibre-primary-renderer.md 053. [reference] docs/adr/0002-postgis-source-of-truth.md 054. [reference] docs/adr/0003-evidence-separated-from-geometry.md 055. [reference] docs/adr/0004-open-geospatial-interoperability.md 056. [reference] docs/adr/0005-immutable-public-data-releases.md 057. [reference] docs/adr/0006-ranking-disabled-by-policy.md 058. [reference] docs/adr/0007-cesium-deferred.md 059. [reference] docs/adr/0008-canonical-entity-supertype.md 060. [reference] docs/adr/0009-natural-features-for-hydrology.md 061. [reference] docs/adr/0010-research-layers-are-ingest-artifacts-not-domain-model.md 062. [reference] docs/adr/0011-hydrology-series-are-versioned-source-objects.md 063. [reference] docs/adr/0012-measurement-time-and-knowledge-time-are-distinct.md 064. [reference] docs/adr/0013-design-flow-is-never-an-automatic-hydat-derivation.md 065. [reference] docs/adr/0014-integrated-atlas-uses-relations-not-synthetic-geometry.md 066. [reference] docs/adr/0015-legacy-screening-is-provenance-not-governance.md 067. [reference] docs/adr/0016-public-release-is-immutable-snapshot.md 068. [reference] docs/adr/0017-economic-benchmarks-are-not-site-costs.md 069. [reference] docs/adr/0018-break-even-frontier-before-bankable-economics.md 070. [reference] docs/adr/0019-common-generation-and-tenant-hardware-not-avoided-costs.md 071. [reference] docs/adr/0020-one-monorepo-three-logical-systems.md 072. [reference] docs/adr/0021-content-blind-tenant-environments.md 073. [reference] docs/adr/0022-counterparty-screening-before-tenancy.md 074. [reference] docs/adr/0023-offline-satellite-snapshots.md 075. [reference] docs/adr/README.md 076. [reference] docs/api/authentication.md 077. [reference] docs/api/errors.md 078. [reference] docs/api/kristal-farms-api.md 079. [reference] docs/api/ogc-api.md 080. [reference] docs/api/overview.md 081. [reference] docs/api/tiles.md 082. [reference] docs/architecture/backend.md 083. [reference] docs/architecture/data-architecture.md 084. [reference] docs/architecture/deployment.md 085. [reference] docs/architecture/frontend.md 086. [reference] docs/architecture/information-architecture.md 087. [reference] docs/architecture/observability.md 088. [reference] docs/architecture/performance.md 089. [reference] docs/architecture/repository-structure.md 090. [reference] docs/architecture/security.md 091. [reference] docs/architecture/technology-stack.md 092. [reference] docs/data/application-data-model.md 093. [reference] docs/data/data-quality.md 094. [reference] docs/data/DATA_VALIDATION_PASS_2026-09-01.md 095. [reference] docs/data/economic-data-contract.md 096. [reference] docs/data/evidence-matrix.md 097. [reference] docs/data/hydrology-data-contract.md 098. [reference] docs/data/hydrology-derivation-policy.md 099. [reference] docs/data/hydrology-observation-pipeline.md 100. [reference] docs/data/hydrology-source-versioning-and-time.md 101. [reference] docs/data/ingestion.md 102. [reference] docs/data/integrated-atlas-data-contract.md 103. [reference] docs/data/provenance.md 104. [reference] docs/data/publishing.md 105. [reference] docs/data/release-versioning.md 106. [reference] docs/data/spatial-standards.md 107. [reference] docs/data/temporal-model.md 108. [reference] docs/domain/glossary.md 109. [reference] docs/domain/screening-governance.md 110. [reference] docs/frontend/accessibility.md 111. [reference] docs/frontend/cartography.md 112. [reference] docs/frontend/design-system.md 113. [reference] docs/frontend/layer-catalog.md 114. [reference] docs/frontend/map-observatory-interaction.md 115. [reference] docs/frontend/offline-satellite.md 116. [reference] docs/frontend/state-and-permalinks.md 117. [canonical] docs/index.md 118. [reference] docs/product/explorer-data-contract.md 119. [reference] docs/product/explorer.md 120. [reference] docs/product/integrated-atlas.md 121. [reference] docs/product/scenario-studio.md 122. [reference] docs/product/showcase-data-contract.md 123. [reference] docs/product/showcase.md 124. [reference] docs/reference/source-quality.md 125. [reference] docs/reference/status-enums.md 126. [reference] docs/reference/units.md 127. [reference] docs/scenarios/economic-method.md 128. [reference] docs/scenarios/engine-contract.md 129. [reference] docs/scenarios/reproducibility.md 130. [reference] docs/scenarios/scenario-model.md 131. [reference] docs/security/TENANT_CONFIDENTIALITY_BOUNDARY.md 132. [reference] docs/security/threat-model.md 133. [canonical] GOVERNANCE.md 134. [canonical] ORCHESTRATION.md 135. [canonical] RELEASE_MANIFEST.json 136. [canonical] SECURITY.md ================================================================================================ FILE: README.md AUTHORITY: canonical ================================================================================================ # Kristal Farms Kristal Farms is a northern energy-and-compute infrastructure project built around a simple inversion: > **Bring flexible compute to remote renewable energy and export digital value by fibre instead of defaulting to long roads and long high-voltage export corridors.** The project focuses on northern Québec and Labrador, where hydro resources, marine logistics, community infrastructure and telecommunications can be evaluated as one system. ## What Kristal Farms is Kristal Farms combines seven infrastructure and governance layers: 1. **Remote renewable generation** — primarily hydro where technically, environmentally and socially justified. 2. **Protected community interface** — community and critical loads have priority over flexible compute. 3. **Serviced compute sites** — power, cooling interface, fibre handoff, physical security, metering and logistics; tenants may bring and control their own hardware and software. 4. **Digital export by fibre** — move computation and data products rather than defaulting to long-distance electrical export. 5. **Responsible international tenancy** — screen jurisdictions, legal counterparties, beneficial ownership/control and sanctions/trade exposure before access; the current owner policy excludes United States-based or United States-controlled counterparties from tenant/anchor-offtaker/tenant-operator roles. 6. **Content-blind tenant environments** — tenants control private compute and cryptographic keys; Kristal Farms operates shared physical services without routine inspection of private models, datasets or application content. 7. **International distributed resilience** — diversify eligible tenants, jurisdictions, telecom paths and site dependencies while treating any diplomatic/security benefit as a hypothesis rather than a defence guarantee. The current site doctrine emphasizes **new renewable generation consumed locally + practical marine access + high-capacity standard telecom + comparatively low ecological sensitivity**. Existing dams may support construction where appropriate but are not the long-term commercial resource thesis. Marine access, local roads, heat reuse, storage and short electrical interties remain site-specific components; no individual port, fibre route or hydro project is established merely by this doctrine. ## Application The repository also contains the architecture, data contracts, and an initial Observatory Explorer web implementation for the Kristal Farms application: - **Showcase** — guided public narrative; - **Explorer** — evidence-first professional geospatial workspace; the first MapLibre Observatory vertical slice lives in [`apps/web/`](apps/web/); - **Scenario Studio** — reproducible infrastructure and economic comparisons. The application is data-driven. PostgreSQL/PostGIS is the intended operational source of truth; MapLibre/deck.gl, OGC APIs, QGIS workflows and immutable public releases consume derived views and artifacts. ### Monorepo boundaries Kristal Farms stays in **one canonical repository**, but development is divided into three logical systems: ```text research/ -> pipelines + data + contracts/packages -> apps/services KNOWLEDGE DATA PLATFORM / CONTRACT PRODUCT ``` `apps/web` may consume governed APIs, stable packages/contracts and immutable `data/publish` artifacts. It must not import or execute code from `research/` or `pipelines/`. See [Workspace boundaries](docs/architecture/workspace-boundaries.md) and [ADR-020](docs/adr/0020-one-monorepo-three-logical-systems.md). ## Evidence discipline The repository deliberately separates facts, observations, derived values, assumptions and unknowns. Core rules: - planning margin is **not** validated compute-hosting capacity; - community loads are priority loads; - external projects are references unless explicitly reclassified; - evidence may be valid without geometry; - a gauge point is not a dam site; - terrain drop is not project head; - a benchmark is not a site cost; - unknown or unpriced values remain explicit; - site ranking is disabled until a transparent methodology and governance decision exist. ## Repository layout ```text kristal-farms/ ├── research/ # Active exploratory work; never a product runtime dependency ├── pipelines/ # Reproducible ingest, transformation, validation and publishing ├── database/ # PostGIS migrations, views, functions and seeds ├── contracts/ # Machine-readable API/data/policy contracts ├── packages/ # Schemas, catalog, map style, UI/shared packages ├── data/ # Raw, processed/current and immutable publish artifacts ├── apps/ # Product applications, including Observatory ├── services/ # Domain API, OGC API and tile services ├── docs/ # Project/domain + software/data-platform documentation ├── tools/ # Specialist local/developer utilities ├── sources/ # Controlled source material and project-direction records ├── tests/ # Automated model/data/economic/architecture tests ├── infra/ # Deployment configuration └── archive/ # Superseded material and historical research snapshots ``` ## Start here ### Project and domain - [Project state](docs/00-control/PROJECT_STATE.md) - [Strategic principles](docs/00-control/STRATEGIC_PRINCIPLES.md) - [Project reference architecture — English](docs/10-core/Kristal_Farms_Project_Reference_Architecture_EN.md) - [Architecture de référence du projet — français](docs/10-core/Architecture_de_reference_du_projet_Kristal_Farms_FR.md) - [Deployment strategy — English](docs/10-core/deployment/DEPLOYMENT_STRATEGY_EN.md) - [Stratégie de déploiement — français](docs/10-core/deployment/STRATEGIE_DE_DEPLOIEMENT_FR.md) - [Corridor dossier strategy](docs/00-control/CORRIDOR_DOSSIER_STRATEGY.md) - [Responsible international tenant governance](docs/00-control/INTERNATIONAL_TENANT_GOVERNANCE.md) - [Plan de mobilisation internationale — français](docs/10-core/strategy/PLAN_MOBILISATION_INTERNATIONALE_KRISTAL_FARMS_FR.md) - [Tenant-controlled encrypted environment — English](docs/10-core/tenancy/BLACK_BOX_TENANCY_MODEL_EN.md) - [Environnement chiffré sous contrôle du locataire — français](docs/10-core/tenancy/MODELE_LOCATION_BLACK_BOX_FR.md) ### Application and data - [Documentation index](docs/index.md) - [Product vision](docs/product/vision.md) - [Software & data platform architecture](docs/architecture/overview.md) - [Information architecture](docs/architecture/information-architecture.md) - [Data model](docs/data/data-model.md) - [Evidence model](docs/data/evidence-model.md) - [Explorer](docs/product/explorer.md) - [Map observatory interaction](docs/frontend/map-observatory-interaction.md) - [Showcase](docs/product/showcase.md) - [Scenario Studio](docs/product/scenario-studio.md) ### Research methods - [Hydro Resource Atlas method](docs/30-site-screening/hydro-atlas/HYDRO_RESOURCE_ATLAS_METHOD.md) - [Hydro geometry pipeline](docs/30-site-screening/hydro-atlas/GEOMETRY_PIPELINE_METHOD.md) - [Economic architecture frontier](docs/40-economics/ECONOMIC_ARCHITECTURE_FRONTIER.md) - [Economic benchmark register](docs/40-economics/ECONOMIC_BENCHMARK_REGISTER.md) - [Mine reuse screening method](docs/30-site-screening/mine-reuse/MINE_REUSE_SCREENING_METHOD.md) - [Underground compute / mine infrastructure reuse](docs/30-site-screening/mine-reuse/UNDERGROUND_COMPUTE_REUSE.md) - [Mine-pit reservoir / pumped-storage research](docs/30-site-screening/mine-reuse/MINE_RESERVOIR_PUMPED_STORAGE.md) - [Northern mine-reuse research inventory](docs/50-research/mines/NORTHERN_MINE_REUSE_INVENTORY.md) ## Current status The repository contains a substantial evidence base, current canonical fixtures, reproducible research pipelines, PostGIS schema/migrations, economic sensitivity tooling and public-release artifacts. It does **not** yet establish a selected project site, buildable hydro capacity, environmental authorization, community authorization, fibre route, heavy-lift logistics plan, committed international anchor tenant/offtake agreement or bankable project economics. Development now proceeds through named **corridor and site dossiers** that replace general proxies with real geometry, hydrology, engineering, logistics, rights/governance work, commercial quotations and project-specific economics. A new exploratory mine-reuse workstream also tests whether existing mining assets can reduce new-build scope. It treats **recent underground/care-and-maintenance mines** as potential infrastructure-reuse analogues and **open-pit mines of any age** as possible pumped-storage reservoir research objects where geometry, environment and system value justify study. No mine is selected by this policy. ## Wiki The GitHub Wiki is maintained as a separate repository: `Kristal_Farms.wiki`. It is an explanatory surface, not the technical source of truth. ## Long-horizon concepts Optional human-infrastructure, learning and education concepts are isolated under [`docs/70-long-horizon/`](docs/70-long-horizon/README.md). They are not prerequisites for the first energy/compute project and must not be presented as committed institutions or programs. ## Local Observatory workflow After repository files change, double-click `REBUILD_OBSERVATORY.pyw`. It is the controlled Windows rebuild path: it safely stops the current Kristal dev server, cleans generated caches, creates or repairs `.venv` from `requirements-dev.txt`, republishes governed artifacts, runs `pytest`, runs the web TypeScript typecheck and production build, then starts the Observatory only when all checks pass. Use `START_OBSERVATORY.bat` only for a quick start when repository files have not changed. Specialist diagnostics, Sentinel/watershed acquisition and PMTiles helpers live under `tools/`; see [`tools/README.md`](tools/README.md). ================================================================================================ FILE: docs/00-control/DOCUMENT_AUTHORITY.md AUTHORITY: canonical ================================================================================================ # Document Authority Model This model prevents polished, older or derived documents from overriding current project intent or evidence discipline. ## Authority classes | Class | Meaning | Location / examples | |---|---|---| | **C0 — Project control** | Current scope, principles, state, decisions and release interpretation. | `docs/00-control/` | | **C1 — Project reference architecture** | Current physical/commercial project architecture and deployment strategy. | `docs/10-core/*Project_Reference_Architecture*`, current project vision, deployment and tenancy reference files | | **C2 — Software/data-platform contracts** | Product, data, API, scenario, frontend and software/data-platform architecture rules. | `docs/product/`, `docs/architecture/`, `docs/data/`, `docs/scenarios/`, `contracts/` | | **C3 — Structured evidence** | Controlled datasets and observations, authoritative only for what their sources support. | `data/`, `sources/` | | **C4 — Working research** | Research methods, screening, cost studies and source analyses requiring validation before project claims. | `docs/30-site-screening/`, `docs/40-economics/`, `docs/50-research/` including commercial prospect research | | **C4O — Project direction** | Recorded owner/project intent; authoritative for intent, not independent factual evidence. | `sources/owner-direction/` | | **C4L — Long-horizon concepts** | Optional future human/community/learning concepts; not prerequisites or commitments. | `docs/70-long-horizon/` | | **C5 — Archive** | Superseded narratives, old partner packages, build history and research snapshots. | `archive/` | ## Conflict rule When materials conflict: 1. current project-control documents govern intent and interpretation; 2. current project reference architecture governs the physical/commercial model; 3. source evidence governs factual claims within its scope and date; 4. assumptions remain assumptions; 5. archived material never silently overrides active state. ## Promotion rule A research statement becomes an external project claim only when its source, scope, date, uncertainty and required technical/community/environmental validation are clear. ## Documentation axes The numbered project/domain folders (`00-control`, `10-core`, `30-site-screening`, `40-economics`, `50-research`, `70-long-horizon`) describe project authority and research maturity. Software/data-platform documentation lives in responsibility-based folders such as `architecture/`, `data/`, `product/`, `frontend/`, `api/` and `scenarios/`. See [Information Architecture](../architecture/information-architecture.md). ================================================================================================ FILE: docs/00-control/MASTER_INDEX.md AUTHORITY: canonical ================================================================================================ # Master Index ## Project control - [Project State](PROJECT_STATE.md) - [Strategic Principles](STRATEGIC_PRINCIPLES.md) - [Document Authority](DOCUMENT_AUTHORITY.md) - [Scope Boundaries](SCOPE_BOUNDARIES.md) - [Claims to Validate](CLAIMS_TO_VALIDATE.md) - [Decisions Required](DECISIONS_REQUIRED.md) - [Workstreams](WORKSTREAMS.md) - [Release Status](RELEASE_STATUS.md) - [Corridor Dossier Strategy](CORRIDOR_DOSSIER_STRATEGY.md) - [Responsible International Tenant Governance](INTERNATIONAL_TENANT_GOVERNANCE.md) ## Project reference architecture - [Kristal Farms Project Reference Architecture — EN](../10-core/Kristal_Farms_Project_Reference_Architecture_EN.md) - [Architecture de référence du projet Kristal Farms — FR](../10-core/Architecture_de_reference_du_projet_Kristal_Farms_FR.md) - [Kristal Farms Vision — EN](../10-core/strategy/KRISTAL_FARMS_VISION_EN.md) - [Vision Kristal Farms — FR](../10-core/strategy/VISION_KRISTAL_FARMS_FR.md) - [Plan de mobilisation internationale — FR](../10-core/strategy/PLAN_MOBILISATION_INTERNATIONALE_KRISTAL_FARMS_FR.md) - [Deployment Strategy — EN](../10-core/deployment/DEPLOYMENT_STRATEGY_EN.md) - [Stratégie de déploiement — FR](../10-core/deployment/STRATEGIE_DE_DEPLOIEMENT_FR.md) - [Tenant-Controlled Encrypted Environment — EN](../10-core/tenancy/BLACK_BOX_TENANCY_MODEL_EN.md) - [Environnement chiffré sous contrôle du locataire — FR](../10-core/tenancy/MODELE_LOCATION_BLACK_BOX_FR.md) ## Hydro and site research - [Hydro Resource Atlas Method](../30-site-screening/hydro-atlas/HYDRO_RESOURCE_ATLAS_METHOD.md) - [Hydro Source Hierarchy](../30-site-screening/hydro-atlas/HYDRO_ATLAS_SOURCE_HIERARCHY.md) - [Geometry Pipeline Method](../30-site-screening/hydro-atlas/GEOMETRY_PIPELINE_METHOD.md) - [Manual Reach Review Gate](../30-site-screening/hydro-atlas/MANUAL_REVIEW_GATE.md) - [Service Endpoints](../30-site-screening/hydro-atlas/SERVICE_ENDPOINTS.md) - [Geometry Ingestion Status](../30-site-screening/hydro-atlas/GEOMETRY_INGESTION_STATUS.md) - [Mine Reuse Screening Method](../30-site-screening/mine-reuse/MINE_REUSE_SCREENING_METHOD.md) - [Underground Compute / Mine Infrastructure Reuse](../30-site-screening/mine-reuse/UNDERGROUND_COMPUTE_REUSE.md) - [Mine-Pit Reservoir and Pumped-Storage Research](../30-site-screening/mine-reuse/MINE_RESERVOIR_PUMPED_STORAGE.md) ## Economics - [Economic Architecture Frontier](../40-economics/ECONOMIC_ARCHITECTURE_FRONTIER.md) - [Economic Benchmark Register](../40-economics/ECONOMIC_BENCHMARK_REGISTER.md) - [Scenario Policy](../40-economics/SCENARIO_POLICY.md) ## Software / data-platform contracts - [Application Data Model](../data/application-data-model.md) - [Hydrology Observation Pipeline](../data/hydrology-observation-pipeline.md) - [Hydrology Data Contract](../data/hydrology-data-contract.md) - [Hydrology Derivation Policy](../data/hydrology-derivation-policy.md) - [Hydrology Source Versioning](../data/hydrology-source-versioning-and-time.md) - [Evidence Matrix](../data/evidence-matrix.md) - [Integrated Atlas](../product/integrated-atlas.md) - [Integrated Atlas Data Contract](../data/integrated-atlas-data-contract.md) - [Explorer Data Contract](../product/explorer-data-contract.md) - [Showcase Data Contract](../product/showcase-data-contract.md) - [Economic Data Contract](../data/economic-data-contract.md) - [Economic Method](../scenarios/economic-method.md) ## Software / product implementation - [Documentation Home](../index.md) - [Product Vision](../product/vision.md) - [Software & Data Platform Architecture](../architecture/overview.md) - [Information Architecture](../architecture/information-architecture.md) - [Data Model](../data/data-model.md) - [Evidence Model](../data/evidence-model.md) - [Layer Catalog](../frontend/layer-catalog.md) - [API Overview](../api/overview.md) - [Scenario Model](../scenarios/scenario-model.md) - [Implementation Plan](../roadmap/implementation-plan.md) ## Mine-reuse research - [Northern Mine Reuse Inventory](../50-research/mines/NORTHERN_MINE_REUSE_INVENTORY.md) - Exploratory structured inventory: `../../research/mines/northern_mine_reuse_inventory.csv` ## International commercial research - [International Tenant Landscape](../50-research/commercial/INTERNATIONAL_TENANT_LANDSCAPE.md) - [International Tenant Screening Reference Base](../50-research/governance/INTERNATIONAL_TENANT_SCREENING_REFERENCE_BASE.md) ## Operations and security - [Tenant Due-Diligence Runbook](../operations/TENANT_DUE_DILIGENCE_RUNBOOK.md) - [Tenant Confidentiality Boundary](../security/TENANT_CONFIDENTIALITY_BOUNDARY.md) ## Historical material Superseded packages, old project-state narratives and historical research artifacts are under `archive/`. They are retained for provenance and do not control active project state. ## Long-horizon concepts - [Long-Horizon Concepts](../70-long-horizon/README.md) These concepts are optional future directions and safeguards, not prerequisites or commitments for the first energy/compute deployment. ================================================================================================ FILE: docs/00-control/PROJECT_STATE.md AUTHORITY: canonical ================================================================================================ # Project State **As of:** 2026-08-31 **Status:** Active research and development baseline. This document is not an engineering approval, environmental conclusion, community authorization, market forecast or investment decision. ## Core project thesis Kristal Farms is a northern hydro/renewable resource-access architecture. The primary design question is whether some remote energy resources can be developed more effectively by bringing flexible compute to the energy and exporting digital value by fibre, rather than defaulting to long roads and long high-voltage electrical export corridors. The architecture under study is: > **new remote generation → protected community interface → flexible local compute → fibre export** Community and critical loads have priority over interruptible compute. ## Geography - **Côte-Nord** is the pilot/learning geography because it can provide northern operating conditions while retaining comparatively practical logistics and services for early learning. - **Northern Québec and Labrador** are the longer-term resource geography, where distance from roads and major electrical corridors creates the strongest structural contrast. - No active site is currently ranked or selected. ## Physical architecture Three compute layouts remain valid: 1. generation-side; 2. community/port-side; 3. split/hybrid. Selection depends on electrical distance, fibre, marine/ground logistics, maintenance, environment, security, heat value and host-community preference. ## Compute commercial model Kristal Farms can provide serviced compute sites rather than owning every server. Shared infrastructure may provide power handoff, cooling interface, fibre handoff, security, metering/telemetry and logistics. Tenants can retain control of their hardware, operating systems, models, data, logs and cryptographic keys. ## International tenancy and confidentiality International tenants are an intended market, subject to a selective counterparty-governance policy. Explicit country-level exclusions/holds are governed by `contracts/policy/jurisdiction-eligibility.yaml`; non-listed jurisdictions default to enhanced due diligence. Downstream resellers/subtenants must remain within the same eligibility boundary. The normal service boundary is a **tenant-controlled encrypted environment** (black-box tenancy): Kristal Farms operates agreed shared physical services and minimum necessary service telemetry while the tenant controls private compute, models, datasets and cryptographic keys. Routine content inspection is not part of the operating model. No organization in the research prospect inventory should be presented as interested, committed or contracted without direct commercial evidence. ## International mobilization and resilience A new owner-directed strategy seeks to validate a **12-ensemble international portfolio** built around new renewable generation consumed locally, practical marine access, high-capacity standard telecom and comparatively low ecological sensitivity. Existing dams are not the intended long-term supply base, although existing supply may be used for construction where appropriate and available. The portfolio is intended to diversify tenant, jurisdiction, carrier, port and site dependencies. This diversification is treated as a commercial/operational resilience mechanism and a possible source of broader diplomatic attention during a major disruption. It is **not** a military alliance, collective-defence commitment, extraterritorial status or guarantee that a foreign government will protect a Kristal Farms asset. The next international gate is evidence of demand: direct requirements exchanges and preferably non-binding expressions of interest from multiple eligible organizations before any claim that a coalition exists. See `docs/10-core/strategy/PLAN_MOBILISATION_INTERNATIONALE_KRISTAL_FARMS_FR.md`. ## Mine infrastructure reuse and storage Kristal Farms may evaluate existing mining assets as an **optional infrastructure-reuse pathway**, not as a project prerequisite. Two distinct hypotheses are active at research level: 1. recently closed, suspended or care-and-maintenance underground mines may retain ramps, shafts, electrical distribution, pumping, ventilation, communications, camps, roads or other infrastructure that could reduce new-build scope for a compute node; 2. open-pit mines — including historical/old mines — may be screened as possible upper or lower reservoirs for pumped-storage hydropower where usable volume, head, geotechnics, hydrogeology, environment, rights/governance and system value are credible. Mine age is therefore a **reuse-context field**, not a universal exclusion rule: recency matters more for preservation of underground/industrial assets, while old pits remain eligible for reservoir screening. A mine record does not establish availability, safe occupancy, storage feasibility, current electrical capacity or project rights. ## Heat Heat is a useful co-product, not a universal siting rule. Recovery is justified where useful-heat value exceeds the cost and complexity of recovery and distribution. ## Evidence and screening Current screening is **unranked**: - `screening_mode = unranked`; - `ranking_allowed = false`. The research base includes official hydrometric station references, structured evidence/provenance, community and infrastructure context, external reference projects, telecom/marine evidence and economic benchmarks. Missing geometry and missing values remain explicit. ## What is established - PostGIS-oriented canonical data model for places, assets, projects, corridors, natural features, evidence, observations and scenarios. - 24-river hydrology research set anchored to official WSC station references. - Repeatable geometry/hydrology ingestion workflows with manual acceptance gates. - Integrated application catalog and public-release model. - Structural economic comparison method that can support or reject a generic distance configuration. ## What is not established The repository does not yet establish: - a preferred river or project site; - authoritative connected river geometry for every research river; - engineering intake/powerhouse alignments; - project gross/net head; - design flow or buildable MW; - environmental acceptability or authorization; - Indigenous/community authorization or benefit arrangements; - exact fibre routes/capacity/SLA; - heavy-project-cargo capability at a specific port; - final local electrical design; - vendor quotations; - a committed international anchor tenant or offtake agreement; - a mine approved or available for Kristal Farms reuse; - an underground mine certified as safe/fit for compute occupancy; - a mine-pit pumped-storage site with validated usable volume, head, water balance, geotechnics, environmental acceptability or grid value; - bankable CAPEX/OPEX, NPV or IRR. ## Development mode The next unit of work is the **corridor/site dossier**. Each dossier replaces broad research proxies with project-specific evidence across hydrology, terrain, engineering, environment, rights/governance, logistics, telecom, electrical architecture and economics. ================================================================================================ FILE: docs/00-control/STRATEGIC_PRINCIPLES.md AUTHORITY: canonical ================================================================================================ # Strategic Principles **Status:** Current project-control framing. **Purpose:** Define Kristal Farms clearly without promoting hypotheses into facts. ## 1. Bring the load to the energy Kristal Farms studies whether flexible compute can be located close to remote renewable generation so that digital value moves by fibre instead of requiring every unit of electricity to travel through long new road and high-voltage export corridors. This inversion is the core project thesis. ## 2. Roads and long HV corridors are part of the resource-access problem The structural value proposition is not merely cheap electricity. Some northern hydro resources are difficult to develop because their delivery infrastructure can dominate project complexity. Kristal Farms therefore compares the full enabling infrastructure required by two architectures: - remote generation → long road/HV export → distant load; - remote generation → local flexible compute → fibre export. The second architecture is not assumed to win universally. It must be tested corridor by corridor. ## 3. Community priority is non-negotiable Existing northern community grids are protected infrastructure, not assumed multi-megawatt compute supplies. In modeled systems, community and critical demand are served before flexible compute. ## 4. New generation and compute scale together A multi-megawatt Kristal Farms node requires its own sourced generation and electrical architecture. Planning margin, unused nameplate capacity or a map marker must never be converted into hosting capacity by implication. ## 5. Siting remains open Compute may be generation-side, community/port-side or split. The choice is determined by site evidence: electrical distance, fibre, logistics, maintenance, environment, security, heat value and community preference. ## 6. Fibre is the primary digital-value corridor Fibre route, capacity, redundancy, landing, provider, repair model and SLA are project evidence requirements. A conceptual line on a map is not a confirmed route. ## 7. Heat is optional value Server heat is a co-product. It should be recovered when there is a technically and economically credible use, not treated as a universal requirement that dictates every site layout. ## 8. Marine logistics can replace part of the road burden Where geography supports it, ports and sealift can carry heavy equipment, containers, workers, parts and community freight. Port presence is not proof of heavy-lift capability; facility-specific evidence is required. ## 9. Shared interfaces, separate authority The project should standardize physical and commercial interfaces while avoiding unnecessary concentration of control. Tenant digital sovereignty, community decision rights and infrastructure ownership/governance should remain separable. ## 10. Evidence before ranking The system distinguishes facts, observations, derived values, assumptions and unknowns. Evidence completeness is not site quality. Ranking remains disabled until methodology and governance explicitly authorize it. ## 11. Pilot for learning, then replicate The development loop is: > **design/build → operate → measure → correct → standardize → replicate/scale** The pilot proves architecture and operating methods; it does not need to prove every long-term vision component. ## 12. Long-term network logic If individual nodes prove viable, they may form a chain of hydro/compute/fibre/port nodes across northern Québec and Labrador, with marine logistics and fibre as primary corridors and shorter electrical interties where they improve resilience. ## 13. International tenancy is selective, not indiscriminate Kristal Farms may serve an international compute market while declining counterparties or control structures that do not meet project governance, responsible-business or jurisdictional-risk criteria. Commercial scale does not override eligibility. Explicit country-level exclusions/holds are controlled by the machine-readable jurisdiction schedule and may change only through an explicit C0 decision. Country and organization review must be evidence-backed and categorical, not a numerical moral score. The policy applies to legal counterparties and control structures, not to individuals based on nationality or other protected characteristics. ## 14. Select counterparties; do not inspect private compute Tenant sovereignty includes a content-blind operating boundary. Kristal Farms may operate power, cooling, fibre, physical security and minimum necessary service telemetry without requiring routine access to tenant models, datasets, application payloads or cryptographic keys. Responsible-tenancy controls therefore occur primarily through jurisdictional eligibility, beneficial-ownership/effective-control review, sanctions and trade-control screening, contract and lawful process. Kristal Farms must not claim that it verifies encrypted private workload content when the architecture is deliberately designed not to expose it. ## 15. Reuse existing industrial excavation where it is genuinely advantageous Kristal Farms may reuse mine or brownfield infrastructure when reuse reduces total system cost, schedule, surface disturbance or operating risk **after** accounting for restoration, geotechnical, environmental, rights/governance and integration obligations. This principle does not make mining assets a siting requirement. Recent underground mines may be especially relevant to preserved industrial infrastructure; historical open pits remain eligible for pumped-storage research because reservoir suitability depends primarily on geometry and site condition rather than closure date. ## 16. Generate locally, consume locally, ship equipment by sea, export value by fibre The primary site doctrine is new renewable generation consumed near the generating asset, with practical marine access and high-capacity telecom. Existing dams are not the commercial resource thesis; existing supply may support construction where appropriate. Candidate ensembles should prefer comparatively low ecological sensitivity, but that phrase is a screening objective, not a substitute for biodiversity, rights/governance or environmental assessment. ## 17. International diversification is a resilience layer, not a defence guarantee Kristal Farms should avoid dependence on a single tenant, country, carrier, port, site or technology stack. A geographically and commercially diversified international tenant portfolio can improve continuity incentives and reduce concentration risk. If a major disruption affects several independent foreign commercial stakeholders, it may also attract broader restoration, commercial and diplomatic attention. This must not be represented as collective defence, extraterritoriality or an automatic state obligation. International participation does not make an attack on Kristal Farms legally equivalent to an attack on participating countries. ## 18. Validate international demand before assigning countries to sites A 12-ensemble portfolio may be used as a planning frame, but named organizations remain research prospects until direct evidence exists. The preferred sequence is requirements exchange → non-binding interest → site/workload matching → contracting. Do not fabricate a twelfth partner or force a prospect onto a site merely to complete a matrix. ================================================================================================ FILE: docs/00-control/SCOPE_BOUNDARIES.md AUTHORITY: canonical ================================================================================================ # Scope Boundaries **Status:** Active repository control decision **Effective:** 2026-08-31 ## In scope Kristal Farms develops and evaluates a northern infrastructure architecture built around new or suitable renewable generation, protected community energy interfaces, flexible compute, fibre connectivity and practical marine/land logistics. The repository may study: - hydro and other renewable-resource evidence; - generation-side, community-side and hybrid compute layouts; - serviced compute pads and tenant-operated hardware; - fibre routes, capacity, redundancy and landing requirements; - ports, marine logistics, local access and maintenance; - optional heat recovery where useful heat justifies the added system; - community energy resilience and critical-load priority; - environmental, rights, governance and regulatory constraints; - workforce, housing, training and other enabling infrastructure when relevant to a corridor or project dossier; - reproducible scenario and economic comparison methods; - international tenant/offtaker/operator research and counterparty due diligence; - tenant-controlled encrypted environments (black-box tenancy), including confidentiality, cryptographic and operational service boundaries; - optional reuse of mine/brownfield infrastructure where current condition, rights, restoration obligations and engineering support it; - mine-pit pumped-storage concepts, including historical open pits and coastal/seawater variants, where environmental and system constraints are explicitly evaluated. ## Explicitly out of scope Kristal Farms does **not** depend on or advocate: - changes to provincial, territorial or international boundaries; - separatism or sovereignty claims; - territorial occupation or confrontation as a development strategy; - displacement of existing communities; - company-town dependency or coercive control through housing, employment, infrastructure or data access; - automatic site ranking without an approved, transparent methodology. All project concepts are assumed to operate within applicable law and regulatory requirements and with the rights, authority and participation of affected Indigenous peoples and communities. ## Human and institutional infrastructure Training, research, housing, community facilities and future academic institutions may be studied as enabling or long-term infrastructure. They are not prerequisites for proving the first energy/compute node. Any such program must preserve voluntary participation, individual safety, freedom of movement, non-displacement, portable credentials where applicable and independent remedies. A project must not claim university status, recognized degrees or formal institutional partnerships before those facts exist. ## Evidence boundary Historical, literary, fictional or exploratory material may inform questions and safeguards, but it is not factual evidence, legal authority, engineering evidence or adopted project policy unless separately validated and promoted into the active control layer. ## International tenancy boundary Kristal Farms may adopt project-specific commercial exclusions that are stricter than minimum legal eligibility. Explicit country-level exclusions and holds are governed by the current machine-readable jurisdiction schedule; other jurisdictions and organizations are evaluated using the responsible international tenancy policy rather than inferred from map, market size or nationality alone. The project screens **counterparties before access**. It does not make routine inspection or decryption of tenant application content a condition of tenancy. Technology-origin restrictions are a separate policy question and must not be inferred from counterparty exclusions. See [Responsible International Tenancy and Counterparty Governance](INTERNATIONAL_TENANT_GOVERNANCE.md). ================================================================================================ FILE: docs/10-core/deployment/DEPLOYMENT_STRATEGY_EN.md AUTHORITY: reference ================================================================================================ # Kristal Farms — Deployment Strategy **Status:** Current deployment strategy. This is not a site approval, construction schedule, community agreement or investment commitment. ## Purpose Kristal Farms should prove the architecture incrementally rather than assume that one large project, one river or one physical layout is correct everywhere. The operating loop is: > **design/build → operate → measure → correct → standardize → replicate or scale** ## Pilot geography Côte-Nord is the preferred pilot/learning geography because it can combine northern operating conditions with comparatively practical marine/road access, services and maintenance support. The pilot is intended to prove the architecture and operating model, not to pre-select the long-term northern deployment geography. Longer-term deployment is oriented farther north through Québec and Labrador, where road and high-voltage remoteness may create the strongest structural advantage for local compute and digital export. ## What the pilot must prove A useful pilot should establish evidence for: - generation performance and seasonal operating constraints; - protected community/critical-load interfaces where a community is involved; - modular compute-site power, cooling, metering and security interfaces; - fibre availability, capacity, redundancy and serviceability; - marine and ground logistics, including heavy equipment where required; - maintenance workload, spare-parts strategy and workforce rotation; - environmental monitoring and rights/governance processes; - actual construction and operating costs; - whether heat recovery has a justified local use; - whether the local-compute/digital-export architecture retains an advantage after project-specific costs are included. ## Energy technology Hydro is the primary resource thesis, but deployment is not constrained to one universal hydro scale or configuration. Existing hydro, run-of-river, small/medium developments, larger projects and complementary renewable/storage systems may be evaluated where justified. No technology is automatically the "first step". The first asset should be the one that best reduces uncertainty for the selected pilot while respecting technical, environmental, legal, rights/governance and community constraints. ## Compute siting Three layouts remain valid: 1. generation-side; 2. community/port-side; 3. split/hybrid. The layout is selected from electrical distance, fibre, cooling, heat value, logistics, maintenance, environmental constraints, security and host-community preference. Village-side or dam-side placement is never universal. ## Community rule Where a community is involved, community and critical loads are protected before flexible compute. Existing small community grids are context and protected infrastructure, not assumed sources of multi-megawatt spare compute capacity. Participation, benefit arrangements and local infrastructure must be developed with the relevant rights holders and authorities. Remote territory is never treated as empty or right-free. ## Heat Heat recovery is optional. It should be implemented only where useful-heat value exceeds the cost and complexity of capture and distribution. ## Decision gates After each major deployment stage, record: - actual versus expected cost and schedule; - energy and compute performance; - reliability and maintenance burden; - fibre/network performance; - logistics performance; - environmental observations; - community/rights-holder outcomes; - workforce and training outcomes where applicable; - unresolved risks and evidence gaps. The next decision is explicit: > **repeat, adjust, scale, relocate, pause or stop.** ## Scaling Compute should scale pad by pad and generation only where justified. Successful nodes may eventually form a chain of hydro/compute/fibre/port nodes, with marine logistics as a major physical corridor and shorter electrical interties where they improve resilience. A single long southbound high-voltage corridor is not the assumed default architecture. ================================================================================================ FILE: docs/10-core/tenancy/BLACK_BOX_TENANCY_MODEL_EN.md AUTHORITY: reference ================================================================================================ # Kristal Farms — Tenant-Controlled Encrypted Environment **Status:** Current reference commercial/security model (C1) **Commercial shorthand:** Black-box tenancy ## Model Kristal Farms may lease serviced compute sites or pads while the tenant retains digital sovereignty over the systems placed behind the service boundary. Kristal Farms can provide: - power and metering; - cooling interface; - fibre/network handoff; - physical security and controlled access; - logistics and maintenance access; - facility/service telemetry and SLA measurement. The tenant can retain control of: - hardware and accelerator configuration; - operating systems and orchestration; - models, datasets and applications; - identities, credentials and internal logs; - cryptographic keys and secrets. ## Confidentiality promise The normal operating model is **content-blind by design**. Kristal Farms does not require routine access to private models, datasets, prompts, outputs or decrypted application traffic in order to lease the infrastructure. Counterparty eligibility is established before access through jurisdictional and organizational due diligence. Compliance during tenancy relies on contract, externally verifiable information and lawful process, not hidden inspection of encrypted workloads. ## Boundary Black-box tenancy does not eliminate: - metering; - facility telemetry; - physical safety controls; - shared-network protection; - sanctions/export-control obligations; - valid legal process; - tenant responsibility for its own systems. The governing phrase is: > **Kristal Farms operates the infrastructure. The tenant controls the compute.** See: - `docs/00-control/INTERNATIONAL_TENANT_GOVERNANCE.md` - `docs/security/TENANT_CONFIDENTIALITY_BOUNDARY.md` - ADR-0021 and ADR-0022 ================================================================================================ FILE: docs/architecture/overview.md AUTHORITY: reference ================================================================================================ # Software & data platform architecture ## Target architecture ```mermaid flowchart TB subgraph Clients Public[Public Showcase] Pro[Professional Explorer] QGIS[QGIS] end subgraph Web Next[Next.js / React / TypeScript] ML[MapLibre GL JS] Deck[deck.gl] end subgraph Services API[FastAPI domain API] OGC[pygeoapi / OGC API] Martin[Martin vector tile service] end subgraph Data PG[(PostgreSQL / PostGIS)] Obj[(Object storage / CDN)] end subgraph Pipelines ETL[Python ingest / transform / QA] Pub[Publish pipeline] end Public --> Next Pro --> Next Next --> ML Next --> Deck Next --> API ML --> Martin Next --> OGC API --> PG OGC --> PG Martin --> PG QGIS --> PG ETL --> PG PG --> Pub Pub --> Obj Public --> Obj ``` ## Responsibility boundaries | Component | Primary responsibility | |---|---| | React/Next.js | Product UI, route composition, narrative surfaces | | MapLibre | Base map, vector/raster cartography, terrain/globe | | deck.gl | High-volume or specialized GPU visualization | | FastAPI | Domain logic, scenarios, search/composite operations | | pygeoapi | Standards-based feature access | | Martin | High-performance vector tile delivery | | PostGIS | Canonical operational geospatial data and relations | | QGIS | Professional desktop GIS editing/analysis | | PMTiles/COG | Immutable public release artifacts | ## Architectural style The system is **modular, data-driven, and standards-aware**, but not microservice-heavy by default. Services are separated where responsibilities are materially different. They may initially deploy together. ## Evolution strategy The MVP may begin with PostGIS + Web + static PMTiles. Martin, pygeoapi, and dedicated scenario services can be activated incrementally without changing the data model. ## Monorepo system boundaries The deployment architecture above is complemented by a repository dependency boundary: ```text Knowledge / research research/ ↓ explicit promotion Data platform / contract pipelines/ + database/ + contracts/ + packages/ + data/ ↓ publish views / immutable releases / APIs / tiles Product apps/ + services/ ``` Product runtime code must not import or execute research or pipeline code. See [Workspace boundaries](workspace-boundaries.md). ================================================================================================ FILE: docs/architecture/workspace-boundaries.md AUTHORITY: reference ================================================================================================ # Workspace boundaries Kristal Farms uses **one physical monorepo with three logical systems**. This is an architectural boundary, not merely a folder convention. ## The three systems ```text ┌──────────────────────────────────────────────────────────────┐ │ 1. KNOWLEDGE / RESEARCH │ │ research/ · sources/ · research documentation │ │ exploratory, evidence-seeking, non-runtime │ └──────────────────────────────┬───────────────────────────────┘ │ reviewed promotion ▼ ┌──────────────────────────────────────────────────────────────┐ │ 2. DATA PLATFORM / CONTRACT │ │ pipelines/ · database/ · contracts/ · packages/ · data/ │ │ reproducible ingest, validation, canonicalization, publish │ └──────────────────────────────┬───────────────────────────────┘ │ governed API/release contract ▼ ┌──────────────────────────────────────────────────────────────┐ │ 3. PRODUCT │ │ apps/ · services/ │ │ Showcase, Explorer/Observatory, Scenario Studio │ └──────────────────────────────────────────────────────────────┘ ``` ## Dependency rules ### Product (`apps/`, `services/`) Product code: - **MAY** depend on stable contracts and packages under `packages/` and `contracts/`; - **MAY** consume `data/publish/...` as an immutable development/release artifact; - **MAY** consume governed APIs/tiles backed by PostGIS; - **MUST NOT** import or execute code from `research/`; - **MUST NOT** import or execute ETL/analysis code from `pipelines/`; - **MUST NOT** read `data/raw/` or ad-hoc research outputs at runtime; - **MUST** treat published data as read-only. The production target remains: ```text UI -> typed client -> API / tiles -> PostGIS ``` The current Observatory vertical slice is allowed to read immutable files under `data/publish/current` server-side while services are still being activated. This is a development bridge, not a new canonical source of truth. ### Data platform (`pipelines/`, `database/`, `contracts/`, `packages/`, `data/`) The data platform: - **MAY** consume registered source material and promoted research inputs; - **MUST** make transforms reproducible; - **MUST** preserve provenance and uncertainty; - **MUST** validate before publishing; - **MUST NOT** rely on React/UI code for scientific or business rules; - **MUST** separate raw, processed/canonical and publish states. `data/publish/` is the artifact boundary for file-based consumers. PostGIS `publish` views and governed APIs are the service boundary for runtime consumers. ### Knowledge / research (`research/`) Research: - **MAY** be exploratory and incomplete; - **MAY** generate candidate outputs and hypotheses; - **MUST** label assumptions and source scope; - **MUST NOT** be imported by product runtime code; - **MUST NOT** become public/canonical merely by being committed; - **MUST** be promoted through a reproducible pipeline before becoming a product data dependency. ## Promotion flow ```text question / source ↓ research exploration ↓ reviewed method or result ↓ pipeline / canonical model ↓ validation + evidence QA ↓ publish view or immutable release ↓ API / tiles / public artifact ↓ Observatory ``` A shortcut from `research/` directly to `apps/web/` is an architecture violation. ## Hydrology example The river work illustrates the boundary: - candidate/source exploration may happen under `research/hydrology/`; - official HYDAT/GeoMet retrieval and reproducible geometry workflows remain under `pipelines/ingest/`; - normalization and validation belong to the data platform; - publishable station/community outputs live under `data/publish/current`; - Observatory renders those outputs and their evidence semantics, but does not know how HYDAT was fetched or how candidate rivers were selected. ## Why one repo One monorepo keeps contracts, pipelines, data artifacts, application changes, tests and ADRs reviewable together while the project is still evolving quickly. The logical boundaries preserve the option to split repositories later without paying the coordination cost now. A physical split becomes reasonable when deployment ownership, teams, release cadence or external consumers require independent versioning. Until then, the monorepo is canonical. ================================================================================================ FILE: docs/domain/kristal-farms-principles.md AUTHORITY: reference ================================================================================================ # Kristal Farms domain principles These rules are normative. ## KP-01 — Core system proposition Kristal Farms is primarily researching **new remote renewable generation + protected community interface + flexible local compute + fibre export**. Existing community grids are protected infrastructure and reference systems, not assumed multi-megawatt compute supplies. ## KP-02 — Community priority Community electrical demand has priority. Flexible compute must be curtailed before essential community service in any modeled dispatch logic. ## KP-03 — Planning margin semantics Utility planning margin must never be relabeled, rendered, or mathematically converted into data-centre hosting capacity unless a separately sourced engineering/utility determination establishes hosting capacity. ## KP-04 — Generation and compute scale together A normal multi-MW Kristal Farms node requires its own sourced generation concept and electrical architecture. ## KP-05 — Siting variants remain open Compute may be generation-side, community/port-side, or split. Selection depends on site engineering, logistics, community preference, heat economics, telecom, environmental constraints, and operations. ## KP-06 — Heat reuse is conditional Heat reuse is an economic/technical option. Do not require long-distance heat distribution merely to maximize reuse percentage. ## KP-07 — Fibre is the primary value-export corridor Fibre is architecturally important, but route, capacity, redundancy, carrier, landing, SLA, and ownership require evidence. ## KP-08 — External projects are references External renewable projects remain reference cases unless governed data explicitly reclassifies them. ## KP-09 — No active site ranking Current screening is unranked evidence screening. The system must obey `ranking_allowed = false`. ## KP-10 — Regulatory applicability is open Do not encode assumptions that dedicated local generation is automatically outside utility, tariff, selection, interconnection, environmental, or other regulatory requirements. ## KP-11 — International counterparty eligibility is explicit International tenants, anchor offtakers and tenant-operators must pass the applicable jurisdictional and counterparty-governance process before contracting. Absence from a restricted-jurisdiction schedule is not automatic approval under the current default. ## KP-12 — Counterparty policy is not content surveillance Responsible-tenancy controls are enforced through legal-counterparty identification, beneficial ownership/effective control, sanctions/trade review, contract and externally verifiable information. Do not require routine inspection of encrypted private tenant compute as the enforcement mechanism. ## KP-13 — Tenant private compute remains tenant-controlled Unless a separately contracted managed service explicitly changes the boundary, tenants retain control of private application systems, models, datasets and cryptographic keys. Kristal Farms may operate purpose-limited physical/service telemetry without claiming access to or certification of private workload content. ================================================================================================ FILE: docs/product/vision.md AUTHORITY: reference ================================================================================================ # Application product vision ## Positioning The Kristal Farms application should initially feel like a polished technical product rather than a static consulting map. The public experience must communicate an ambitious infrastructure thesis while allowing professionals to inspect the underlying evidence. The same application and governed data foundation should later support site screening and scenario analysis without a foundational rewrite. ## Product surfaces ### Showcase A guided visual narrative for investors, partners, public stakeholders, communities, and decision-makers. Success means a non-specialist can understand: - why remote renewable generation is central; - why community demand is protected; - why flexible compute can absorb locally generated electricity; - why fibre is the principal value-export corridor; - which elements are demonstrated versus hypothetical. ### Explorer A professional geospatial workspace exposing layers, sources, metadata, uncertainty, timeline, filters, and exports. Success means a GIS or energy professional recognizes the application as a serious technical information system, not a marketing illustration. ### Scenario Studio A later modeling surface for testing generation, community interface, compute flexibility, storage, fibre, heat reuse, and other parameters. Scenario results must be reproducible and explicitly separated from observed data. ## Design principle **The wow should come from making the system understandable.** Terrain, animation, 3D, and visual effects are useful when they clarify infrastructure relationships or scale. Decorative complexity that obscures evidence is a failure. ================================================================================================ FILE: docs/data/data-model.md AUTHORITY: reference ================================================================================================ # Data model ## Design goals - preserve evidence and provenance; - support GIS workflows; - distinguish observed truth from hypotheses; - support time-aware data; - enable data-driven frontend behavior; - allow public and restricted representations; - keep durable identifiers across formats. ## Entity groups ```mermaid flowchart LR Source --> Evidence Evidence --> Observation Evidence --> Relation Relation --> Place Relation --> Asset Relation --> Project Relation --> Corridor Scenario --> Assumption Scenario --> Result Scenario --> Place Scenario --> Project ``` ## Core tables ### `core.place` ```text id stable text/UUID identifier name display name place_type community, port, region, study_area, site, ... geometry nullable geometry jurisdiction optional jurisdiction status lifecycle/status metadata JSONB extension fields created_at updated_at ``` ### `core.asset` ```text id name asset_type technology geometry operator operational_status commissioned_date capacity_value capacity_unit metadata ``` ### `core.project` ```text id name project_type role external_reference | kristal_farms_candidate | kristal_farms_project status geometry developer operator technology capacity_mw metadata ``` ### `core.corridor` ```text id name corridor_type road | marine | transmission | distribution | fibre | conceptual status geometry operator metadata ``` ## Research tables See [Evidence model](evidence-model.md). ## Scenario tables See [Scenario model](../scenarios/scenario-model.md). ## IDs IDs are immutable references. Names may change; IDs should not. Recommended human-readable prefixes are acceptable for imported research records, e.g. `REF-INNAVIK`, but long-term canonical IDs should have a documented namespace strategy and uniqueness checks. ## Extension fields Use typed columns for frequently queried or semantically important fields. Use `metadata JSONB` for sparse source-specific extensions. Do not put core semantics only in JSONB if the application needs to filter, validate, index, or govern them. ### Mine-reuse research extensions Until a governed mine-specific model is justified, represent a mine as an existing `asset` or external-reference `project` and keep sparse research fields in metadata. Preserve separate semantics for lifecycle status, mine method, restoration responsibility, underground condition, pit/reservoir geometry and enabling infrastructure. Historical mine load must never populate current available compute capacity, and total pit excavation must never be treated as usable pumped-storage volume without a derivation. ================================================================================================ FILE: docs/data/evidence-model.md AUTHORITY: reference ================================================================================================ # Evidence model ## Purpose Kristal Farms must be able to show not only *what* a map says, but *why* it says it. ## Objects ### `research.source` Represents an original source. Suggested fields: ```text id title publisher / authority source_type url or document reference publication_date retrieved_at license_or_terms quality_class metadata ``` ### `research.evidence` Represents a claim or scoped research finding. ```text id claim evidence_type verification_status confidence valid_from valid_to last_verified metadata ``` ### `research.evidence_source` Many-to-many relation between evidence and sources. ### `research.evidence_relation` Links evidence to a place, asset, project, corridor, or other subject. ```text evidence_id subject_type subject_id relation_type ``` Example relation types: ```text supports describes constrains contradicts references ``` ### `research.observation` A specific value or categorical observation. ```text id subject_type subject_id metric value_numeric value_text unit valid_from valid_to evidence_id metadata ``` ## Geometry rule Evidence MAY have no geometry. Do not invent a point location to make evidence appear on the map. Connect non-spatial evidence to spatial subjects through relations. ## Verification statuses Recommended baseline: ```text verified supported scoped unverified conflicting unknown ``` Avoid converting these labels into a generic confidence percentage unless a documented methodology exists. ## Evidence panel The UI should expose source title, authority, publication/access dates, claim, verification status, and known limitations whenever practical. ================================================================================================ FILE: contracts/policy/kristal-farms-policy.yaml AUTHORITY: reference ================================================================================================ policy_version: 2026.08.31-r2-proposed screening: mode: unranked_evidence_screening ranking_allowed: false priority_inference_allowed: false energy_hosting: community_load_priority_required: true planning_margin_is_compute_capacity: false multi_mw_compute_requires_generation_concept: true compute_siting_variants: - generation_side - community_side - split heat_reuse_required: false fibre_is_primary_value_export_corridor: true references: external_projects_default_role: external_reference publication: frontend_hiding_counts_as_access_control: false restricted_data_in_public_artifacts_allowed: false international_tenancy: policy_contract: international-tenant-governance.yaml jurisdiction_schedule: jurisdiction-eligibility.yaml counterparty_screening_before_access: true numeric_ethics_score_allowed: false us_counterparties_eligible_for_tenant_roles: false us_counterparty_exclusion_implies_us_technology_embargo: false jurisdiction_schedule_enforced: true downstream_counterparties_inherit_eligibility: true unverified_global_resale_pool_allowed: false technology_origin_policy_is_separate: true tenant_confidentiality: content_blind_by_design: true tenant_controls_private_keys: true routine_private_content_inspection_allowed: false operator_key_escrow_required: false standing_decryption_backdoor_allowed: false ================================================================================================ FILE: AGENTS.md AUTHORITY: canonical ================================================================================================ # AGENTS.md — Instructions for AI coding agents This file is a high-priority implementation contract for any AI agent modifying the Kristal Farms repository. ## Product intent Kristal Farms is a physical northern energy/compute/fibre infrastructure project supported by an evidence-driven geospatial application. The Showcase, Explorer and Scenario Studio share the same governed data model; the software exists to explain, evaluate and develop Kristal Farms rather than becoming a separate product identity. ## Non-negotiable architecture rules 1. **PostGIS is the operational source of truth.** Do not move canonical data into frontend constants or static JSON modules. 2. **Standard layers are catalog-driven.** Do not create one custom React component per dataset unless the layer requires genuinely unique interaction. 3. **Evidence is not geometry.** Claims, observations, and sources remain separate from places/assets/projects and may have no geometry. 4. **Scenarios are not observations.** Never write scenario assumptions into canonical observed-data tables. 5. **Planning margin is not compute capacity.** Never derive `available_compute_mw` from planning-margin data. 6. **Community load is priority.** Scenario logic must curtail flexible compute before essential community demand. 7. **No ranking while prohibited.** If policy says `ranking_allowed: false`, do not create score, rank, traffic-light styling, ordering, or badges that imply preference. 8. **External reference projects remain references** unless a governed data change explicitly changes their role. 9. **Public/private separation happens before publication.** Never place restricted records in public PMTiles/COG artifacts and rely on frontend hiding. 10. **The model layer owns business rules.** React components should present results, not implement scientific or regulatory logic. 11. **Respect the three-system boundary.** `research/` is exploratory, the data platform publishes governed contracts, and `apps/`/`services/` consume them. Product runtime code must not import or execute `research/` or `pipelines/`. 12. **Published artifacts are read-only product inputs.** Development bridges may read `data/publish/...`; product code must not mutate published artifacts or reach into `data/raw/`. ## Preferred implementation pattern ```text UI -> typed client -> API / tiles -> PostGIS | -> scenario engine ``` Use shared schemas and generated types where practical. All material data-model changes require a migration and documentation update. ## Definition of done for a feature A feature is not complete until it has, where applicable: - typed contract; - validation; - tests; - provenance behavior; - permission behavior; - URL/share-state behavior; - documentation update; - accessibility review; - data QA implications reviewed. ## Before changing architecture Read the relevant ADRs under `docs/adr/`. If the proposed change reverses or materially changes an accepted ADR, create a new superseding ADR instead of silently editing history. ## Data imports Imports must pass through `raw -> staging -> core/research -> publish`. Preserve source identifiers and original source values when feasible. Do not silently normalize away ambiguity. ## Cartography Visual design may be expressive, but uncertainty and hypothesis must remain visible. Do not make conceptual corridors look identical to verified infrastructure. Do not imply precision beyond the source geometry. ## AI-generated code AI-generated implementation is acceptable, but generated code must obey the same tests, typing, schema, migration, and review expectations as human-written code. Avoid large opaque generated modules when a declarative configuration or reusable abstraction is clearer. ## Active-state search discipline Treat `archive/` as historical provenance, not active implementation context. Do not search, summarize or copy architecture from `archive/` unless the task explicitly asks for history, migration provenance or superseded behavior. The root `.ignore` excludes `archive/` from common local search/index tools by default. When documentation location is ambiguous, use the two-axis model in `docs/architecture/information-architecture.md`: numbered folders are project/domain authority and research maturity; responsibility folders (`architecture`, `data`, `product`, `frontend`, `api`, `scenarios`, etc.) are software/data-platform documentation. ================================================================================================ FILE: contracts/api/kristal-farms-api.openapi.yaml AUTHORITY: reference ================================================================================================ openapi: 3.1.0 info: title: Kristal Farms Domain API version: 0.1.0 description: Starter contract for Kristal Farms-specific workflows. OGC feature access is documented separately. servers: - url: /api paths: /v1/policy: get: summary: Get active Kristal Farms policy responses: "200": description: Active policy content: application/json: schema: type: object /v1/catalog: get: summary: Get layer catalog visible to current user responses: "200": description: Layer catalog /v1/search: get: summary: Search entities parameters: - in: query name: q required: true schema: {type: string} responses: "200": {description: Search results} /v1/entities/{entity_type}/{entity_id}: get: summary: Get entity detail parameters: - in: path name: entity_type required: true schema: {type: string} - in: path name: entity_id required: true schema: {type: string} responses: "200": {description: Entity detail} "404": {description: Not found} /v1/entities/{entity_type}/{entity_id}/evidence: get: summary: Get evidence linked to an entity parameters: - in: path name: entity_type required: true schema: {type: string} - in: path name: entity_id required: true schema: {type: string} responses: "200": {description: Evidence list} /v1/scenarios: post: summary: Create a scenario requestBody: required: true content: application/json: schema: $ref: ../schemas/scenario.schema.json responses: "201": {description: Scenario created} /v1/scenarios/{scenario_id}/evaluate: post: summary: Evaluate a scenario parameters: - in: path name: scenario_id required: true schema: {type: string} responses: "200": {description: Scenario evaluation} "422": {description: Invalid scenario or assumptions} ================================================================================================ FILE: contracts/ingestion/import-manifest.schema.json AUTHORITY: reference ================================================================================================ { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://kristal.example/contracts/import-manifest.schema.json", "title": "Kristal Farms Import Manifest", "type": "object", "required": [ "import_id", "source_ids", "started_at", "status" ], "properties": { "import_id": { "type": "string" }, "source_ids": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "source_hashes": { "type": "object", "additionalProperties": { "type": "string" } }, "started_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "enum": [ "running", "passed", "failed", "passed_with_warnings" ] }, "record_count": { "type": "integer", "minimum": 0 }, "warning_count": { "type": "integer", "minimum": 0 }, "error_count": { "type": "integer", "minimum": 0 }, "code_version": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] } }, "additionalProperties": false } ================================================================================================ FILE: contracts/layers/layer-catalog.example.yaml AUTHORITY: reference ================================================================================================ schema_version: "1.0" layers: - id: communities title: Communities group: community classification: public source: type: pmtiles collection: communities geometry: types: [Point] display: renderer: maplibre layer_type: symbol style_token: community.default min_zoom: 2 inspector: title_field: name fields: [region, jurisdiction, screening_state] evidence_enabled: true filters: - field: region type: categorical timeline: enabled: false export: enabled: true - id: reference_projects title: Renewable reference projects group: energy classification: public source: type: vector_tiles collection: reference_projects geometry: types: [Point, Polygon] display: renderer: maplibre layer_type: symbol style_token: project.external_reference inspector: title_field: name fields: [technology, capacity_mw, status, role] evidence_enabled: true filters: - field: technology type: categorical - field: status type: categorical timeline: enabled: true start_field: valid_from end_field: valid_to export: enabled: true ================================================================================================ FILE: contracts/layers/layer-catalog.schema.json AUTHORITY: reference ================================================================================================ { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://kristal.example/contracts/layer-catalog.schema.json", "title": "Kristal Farms Layer Catalog", "type": "object", "required": [ "schema_version", "layers" ], "properties": { "schema_version": { "type": "string" }, "layers": { "type": "array", "items": { "$ref": "#/$defs/layer" } } }, "$defs": { "layer": { "type": "object", "additionalProperties": false, "required": [ "id", "title", "group", "classification", "source", "display" ], "properties": { "id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "title": { "type": "string" }, "group": { "type": "string" }, "classification": { "enum": [ "public", "partner", "internal", "restricted" ] }, "source": { "type": "object", "required": [ "type" ], "properties": { "type": { "enum": [ "vector_tiles", "pmtiles", "ogc_features", "geojson_small", "cog", "api_derived", "scenario" ] }, "collection": { "type": "string" }, "url": { "type": "string" } }, "additionalProperties": true }, "geometry": { "type": "object", "properties": { "types": { "type": "array", "items": { "enum": [ "Point", "MultiPoint", "LineString", "MultiLineString", "Polygon", "MultiPolygon" ] } } }, "additionalProperties": true }, "display": { "type": "object", "required": [ "renderer" ], "properties": { "renderer": { "enum": [ "maplibre", "deckgl", "custom" ] }, "layer_type": { "type": "string" }, "style_token": { "type": "string" }, "min_zoom": { "type": "number" }, "max_zoom": { "type": "number" } }, "additionalProperties": true }, "inspector": { "type": "object", "additionalProperties": true }, "filters": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "timeline": { "type": "object", "additionalProperties": true }, "export": { "type": "object", "additionalProperties": true } } } } } ================================================================================================ FILE: contracts/policy/international-tenant-governance.yaml AUTHORITY: reference ================================================================================================ policy_version: 2026.08.31-r2-proposed policy_name: responsible_international_tenancy jurisdiction_schedule: jurisdiction-eligibility.yaml eligibility: states: - ELIGIBLE - ENHANCED_DUE_DILIGENCE - SUSPENDED - INELIGIBLE numeric_ethics_score_allowed: false decision_subject: legal_counterparty_and_control_structure protected_characteristic_inference_allowed: false owner_directed_exclusions: source_of_truth: jurisdiction-eligibility.yaml schedule_is_authoritative: true technology_origin_embargo_implied: false counterparty_due_diligence: beneficial_ownership_required: true effective_control_required: true sanctions_screening_required: true export_control_review_when_applicable: true source_of_funds_review_when_material: true reseller_subtenant_controls_required: true high_level_workload_class_may_be_requested: true private_model_or_dataset_disclosure_required: false downstream_customer_exposure_required_when_capacity_is_resold: true change_of_control_notification_required: true black_box_tenancy: normative_term: tenant_controlled_encrypted_environment commercial_shorthand: black_box_tenancy content_blind_by_design: true routine_plaintext_application_access_allowed: false routine_private_model_inspection_allowed: false routine_private_dataset_inspection_allowed: false operator_key_escrow_required: false covert_monitoring_allowed: false standing_decryption_backdoor_allowed: false operator_observability: power_and_metering: true cooling_and_environmental_telemetry: true physical_access_events: true network_availability_and_aggregate_utilization: true shared_infrastructure_security_signals: true application_payload_decryption_required: false legal_process: validate_authority: true minimize_scope: true disclose_only_data_possessed_or_controlled: true tenant_notice_when_legally_permitted: true create_persistent_decryption_capability: false review_triggers: - sanctions_or_binding_legal_prohibition - beneficial_ownership_or_control_change - material_misrepresentation - substantiated_sanctions_evasion - serious_externally_verifiable_policy_conflict - shared_infrastructure_abuse - legal_inability_to_continue_service presumptive_risk_treatment: ineligible_when_substantiated: - sanctions_evasion_or_prohibited_party_concealment - material_eligibility_fraud - institutional_purpose_of_state_directed_repression_or_unlawful_mass_surveillance - offensive_cyber_activity_directed_at_civilian_or_shared_infrastructure enhanced_due_diligence: - military_or_defence_counterparty - intelligence_or_state_security_counterparty - biometric_or_population_scale_surveillance_provider - high_risk_dual_use_technology_provider - reseller_or_subtenant_aggregator private_workload_content_inspection_is_enforcement_method: false policy_status: PROPOSED_C0_ADOPTION downstream_tenancy: eligibility_boundary_inherited_by_resellers_and_subtenants: true unverified_global_resale_pool_allowed: false dedicated_capacity_pool_required_when_global_pool_can_serve_ineligible_counterparties: true commercial_allocation_records_auditable: true private_workload_content_auditable: false suspension_allowed_when_downstream_eligibility_cannot_be_verified: true ================================================================================================ FILE: contracts/policy/jurisdiction-eligibility.yaml AUTHORITY: reference ================================================================================================ policy_version: 2026.09.01-r3-proposed-sourced policy_name: jurisdiction_eligibility_schedule policy_status: PROPOSED_C0_ADOPTION default_nonlisted_state: ENHANCED_DUE_DILIGENCE jurisdictions: - code: US name: United States state: INELIGIBLE scope: - tenant - anchor_offtaker - tenant_operator basis: owner_policy_commercial_positioning rationale_codes: - owner_directed_exclusion effective_on_adoption: '2026-08-31' legal_prohibition_claimed: false technology_origin_embargo_implied: false review_requires_explicit_c0_decision: true - code: RU name: Russia state: INELIGIBLE scope: - tenant - anchor_offtaker - tenant_operator basis: proposed_owner_values_policy rationale_codes: - armed_conflict - sanctions_exposure - human_rights_risk - state_security_risk effective_on_adoption: '2026-08-31' legal_prohibition_claimed: false technology_origin_embargo_implied: false review_requires_explicit_c0_decision: true - code: BY name: Belarus state: INELIGIBLE scope: - tenant - anchor_offtaker - tenant_operator basis: proposed_owner_values_policy rationale_codes: - armed_conflict_support - sanctions_exposure - political_repression_risk effective_on_adoption: '2026-08-31' legal_prohibition_claimed: false technology_origin_embargo_implied: false review_requires_explicit_c0_decision: true - code: CN name: China state: INELIGIBLE scope: - tenant - anchor_offtaker - tenant_operator basis: proposed_owner_values_policy rationale_codes: - state_surveillance_risk - forced_labour_risk - human_rights_risk - control_transparency_risk effective_on_adoption: '2026-08-31' legal_prohibition_claimed: false technology_origin_embargo_implied: false review_requires_explicit_c0_decision: true - code: IR name: Iran state: INELIGIBLE scope: - tenant - anchor_offtaker - tenant_operator basis: proposed_owner_values_policy rationale_codes: - state_repression_risk - sanctions_exposure - state_security_risk effective_on_adoption: '2026-08-31' legal_prohibition_claimed: false technology_origin_embargo_implied: false review_requires_explicit_c0_decision: true - code: KP name: North Korea state: INELIGIBLE scope: - tenant - anchor_offtaker - tenant_operator basis: proposed_owner_values_policy rationale_codes: - state_repression_risk - sanctions_exposure - proliferation_risk effective_on_adoption: '2026-08-31' legal_prohibition_claimed: false technology_origin_embargo_implied: false review_requires_explicit_c0_decision: true - code: SY name: Syria state: INELIGIBLE scope: - tenant - anchor_offtaker - tenant_operator basis: proposed_owner_values_policy rationale_codes: - armed_conflict - atrocity_risk - sanctions_exposure effective_on_adoption: '2026-08-31' legal_prohibition_claimed: false technology_origin_embargo_implied: false review_requires_explicit_c0_decision: true - code: MM name: Myanmar state: INELIGIBLE scope: - tenant - anchor_offtaker - tenant_operator basis: proposed_owner_values_policy rationale_codes: - military_rule - political_repression_risk - human_rights_risk effective_on_adoption: '2026-08-31' legal_prohibition_claimed: false technology_origin_embargo_implied: false review_requires_explicit_c0_decision: true - code: AF name: Afghanistan state: SUSPENDED scope: - tenant - anchor_offtaker - tenant_operator basis: proposed_owner_precautionary_hold rationale_codes: - governance_uncertainty - human_rights_risk - sanctions_exposure - control_verification_risk effective_on_adoption: '2026-08-31' legal_prohibition_claimed: false technology_origin_embargo_implied: false review_requires_explicit_c0_decision: true - code: LY name: Libya state: SUSPENDED scope: - tenant - anchor_offtaker - tenant_operator basis: proposed_owner_precautionary_hold rationale_codes: - political_instability - sanctions_exposure - control_verification_risk effective_on_adoption: '2026-08-31' legal_prohibition_claimed: false technology_origin_embargo_implied: false review_requires_explicit_c0_decision: true - code: NI name: Nicaragua state: SUSPENDED scope: - tenant - anchor_offtaker - tenant_operator basis: proposed_owner_precautionary_hold rationale_codes: - political_repression_risk - sanctions_exposure - governance_risk effective_on_adoption: '2026-08-31' legal_prohibition_claimed: false technology_origin_embargo_implied: false review_requires_explicit_c0_decision: true - code: SO name: Somalia state: SUSPENDED scope: - tenant - anchor_offtaker - tenant_operator basis: proposed_owner_precautionary_hold rationale_codes: - state_fragility - security_risk - control_verification_risk effective_on_adoption: '2026-08-31' legal_prohibition_claimed: false technology_origin_embargo_implied: false review_requires_explicit_c0_decision: true - code: SD name: Sudan state: SUSPENDED scope: - tenant - anchor_offtaker - tenant_operator basis: proposed_owner_precautionary_hold rationale_codes: - armed_conflict - atrocity_risk - control_verification_risk effective_on_adoption: '2026-08-31' legal_prohibition_claimed: false technology_origin_embargo_implied: false review_requires_explicit_c0_decision: true - code: SS name: South Sudan state: SUSPENDED scope: - tenant - anchor_offtaker - tenant_operator basis: proposed_owner_precautionary_hold rationale_codes: - armed_conflict - state_fragility - control_verification_risk effective_on_adoption: '2026-08-31' legal_prohibition_claimed: false technology_origin_embargo_implied: false review_requires_explicit_c0_decision: true - code: VE name: Venezuela state: SUSPENDED scope: - tenant - anchor_offtaker - tenant_operator basis: proposed_owner_precautionary_hold rationale_codes: - governance_risk - human_rights_risk - sanctions_exposure - control_transparency_risk effective_on_adoption: '2026-08-31' legal_prohibition_claimed: false technology_origin_embargo_implied: false review_requires_explicit_c0_decision: true - code: YE name: Yemen state: SUSPENDED scope: - tenant - anchor_offtaker - tenant_operator basis: proposed_owner_precautionary_hold rationale_codes: - armed_conflict - state_fragility - sanctions_exposure effective_on_adoption: '2026-08-31' legal_prohibition_claimed: false technology_origin_embargo_implied: false review_requires_explicit_c0_decision: true - code: ZW name: Zimbabwe state: SUSPENDED scope: - tenant - anchor_offtaker - tenant_operator basis: proposed_owner_precautionary_hold rationale_codes: - governance_risk - human_rights_risk - sanctions_exposure effective_on_adoption: '2026-08-31' legal_prohibition_claimed: false technology_origin_embargo_implied: false review_requires_explicit_c0_decision: true notes: - This overlay is a proposed C0 update; applying it should be treated as explicit project-control adoption. - Absence from this schedule does not mean automatic eligibility. - Country-level status is a counterparty-risk control and not a judgment about individuals or populations. - The schedule is project policy and may be stricter than minimum legal eligibility; transaction-specific Canadian legal review still applies. - Technology-origin restrictions are separate from counterparty eligibility and are not implied by this schedule. legal_reference_sources: - id: canada-sanctions-index title: Canadian sanctions publisher: Global Affairs Canada url: https://www.international.gc.ca/world-monde/international_relations-relations_internationales/sanctions/index.aspx?lang=eng retrieved_on: '2026-09-01' use: Current sanctions framework and links to governing regulations; not a substitute for transaction-specific legal review. - id: canada-consolidated-autonomous-sanctions title: Consolidated Canadian Autonomous Sanctions List publisher: Global Affairs Canada url: https://www.international.gc.ca/world-monde/international_relations-relations_internationales/sanctions/consolidated-consolide.aspx?lang=eng retrieved_on: '2026-09-01' use: Administrative screening aid only; the Government of Canada states that the consolidated list is not a regulation and has no force of law. - id: canada-eipa title: Export and Import Permits Act publisher: Justice Laws Website, Government of Canada url: https://laws-lois.justice.gc.ca/eng/acts/E-19/index.html retrieved_on: '2026-09-01' use: Statutory framework for Canadian export/import controls. - id: canada-export-control-list title: Export Control List (SOR/89-202) publisher: Justice Laws Website, Government of Canada url: https://laws-lois.justice.gc.ca/eng/Regulations/SOR-89-202/index.html retrieved_on: '2026-09-01' use: Current regulatory list for controlled exports; technology-origin review remains separate from counterparty policy. ================================================================================================ FILE: contracts/reference/data-classification.yaml AUTHORITY: reference ================================================================================================ version: "1.0" levels: public: public_artifact_allowed: true partner: public_artifact_allowed: false internal: public_artifact_allowed: false restricted: public_artifact_allowed: false ================================================================================================ FILE: contracts/reference/status-enums.yaml AUTHORITY: reference ================================================================================================ version: "1.0" project_role: - external_reference - kristal_farms_candidate - kristal_farms_project evidence_verification: - verified - supported - scoped - unverified - conflicting - unknown scenario_status: - draft - working - shared - archived assumption_source_type: - user_input - engineering_assumption - derived - evidence - default siting_variant: - generation_side - community_side - split ================================================================================================ FILE: contracts/releases/release-manifest.example.json AUTHORITY: reference ================================================================================================ { "release_version": "2026.08.30-r1", "generated_at": "2026-08-30T14:00:00Z", "database_migration": "example", "policy_version": "2026.08.30", "collections": [ "communities", "reference_projects" ], "artifacts": [ { "path": "kristal-core.pmtiles", "sha256": "", "classification": "public" } ], "qa": { "passed": true, "report": "qa-report.json" } } ================================================================================================ FILE: contracts/releases/release-manifest.schema.json AUTHORITY: reference ================================================================================================ { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://kristal.example/contracts/release-manifest.schema.json", "title": "Kristal Farms Data Release Manifest", "type": "object", "required": [ "release_version", "generated_at", "policy_version", "artifacts", "qa" ], "properties": { "release_version": { "type": "string" }, "generated_at": { "type": "string", "format": "date-time" }, "database_migration": { "type": [ "string", "null" ] }, "policy_version": { "type": "string" }, "collections": { "type": "array", "items": { "type": "string" }, "uniqueItems": true }, "artifacts": { "type": "array", "items": { "type": "object", "required": [ "path", "sha256", "classification" ], "properties": { "path": { "type": "string" }, "sha256": { "type": "string" }, "classification": { "enum": [ "public", "partner", "internal", "restricted" ] } }, "additionalProperties": false } }, "qa": { "type": "object", "required": [ "passed" ], "properties": { "passed": { "type": "boolean" }, "report": { "type": [ "string", "null" ] } }, "additionalProperties": true } }, "additionalProperties": false } ================================================================================================ FILE: contracts/schemas/electrical-projects.schema.json AUTHORITY: reference ================================================================================================ { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://kristal.farms/schemas/electrical-projects.schema.json", "title": "Kristal external electrical projects research registry", "type": "object", "required": ["schema", "version", "ranking_allowed", "sources", "projects"], "properties": { "schema": {"const": "kristal-electrical-projects-research/v1"}, "version": {"type": "string"}, "ranking_allowed": {"const": false}, "sources": { "type": "array", "items": { "type": "object", "required": ["source_key", "title", "publisher", "source_type", "url", "retrieved_at"], "properties": { "source_key": {"type": "string"}, "title": {"type": "string"}, "publisher": {"type": "string"}, "source_type": {"type": "string"}, "url": {"type": "string", "pattern": "^https://"}, "publication_date": {"type": ["string", "null"]}, "retrieved_at": {"type": "string"}, "document_reference": {"type": ["string", "null"]}, "metadata": {"type": "object"} } } }, "projects": { "type": "array", "items": { "type": "object", "required": ["canonical_key", "name", "project_type", "project_status", "technology", "communities", "source_keys", "evidence"], "properties": { "canonical_key": {"type": "string", "pattern": "^project:external:"}, "name": {"type": "string"}, "project_type": {"type": "string"}, "project_status": {"type": "string"}, "technology": {"type": "string"}, "capacity_mw": {"type": ["number", "null"]}, "developer": {"type": ["string", "null"]}, "operator": {"type": ["string", "null"]}, "geometry": {"type": "null"}, "communities": {"type": "array", "items": {"type": "object", "required": ["name"], "properties": {"name": {"type": "string"}, "entity_key": {"type": ["string", "null"]}, "relation_type": {"type": ["string", "null"]}}}}, "metadata": {"type": "object"}, "source_keys": {"type": "array", "minItems": 1, "items": {"type": "string"}}, "evidence": {"type": "object", "required": ["evidence_type", "claim", "confidence"], "properties": {"evidence_type": {"type": "string"}, "claim": {"type": "string"}, "confidence": {"type": "string"}, "published_at": {"type": ["string", "null"]}, "metadata": {"type": "object"}}} } } } } } ================================================================================================ FILE: contracts/schemas/evidence.schema.json AUTHORITY: reference ================================================================================================ { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://kristal.example/contracts/evidence.schema.json", "title": "Kristal Farms Evidence", "type": "object", "required": [ "id", "claim", "verification_status", "source_ids" ], "properties": { "id": { "type": "string" }, "claim": { "type": "string" }, "evidence_type": { "type": [ "string", "null" ] }, "verification_status": { "enum": [ "verified", "supported", "scoped", "unverified", "conflicting", "unknown" ] }, "confidence": { "type": [ "string", "null" ] }, "source_ids": { "type": "array", "items": { "type": "string" }, "minItems": 1, "uniqueItems": true }, "last_verified": { "type": [ "string", "null" ], "format": "date" }, "valid_from": { "type": [ "string", "null" ], "format": "date" }, "valid_to": { "type": [ "string", "null" ], "format": "date" }, "metadata": { "type": "object" } }, "additionalProperties": false } ================================================================================================ FILE: contracts/schemas/observation.schema.json AUTHORITY: reference ================================================================================================ { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://kristal.example/contracts/observation.schema.json", "title": "Kristal Farms Observation", "type": "object", "required": [ "id", "subject_type", "subject_id", "metric", "unit", "evidence_id" ], "properties": { "id": { "type": "string" }, "subject_type": { "type": "string" }, "subject_id": { "type": "string" }, "metric": { "type": "string" }, "value_numeric": { "type": [ "number", "null" ] }, "value_text": { "type": [ "string", "null" ] }, "unit": { "type": "string" }, "valid_from": { "type": [ "string", "null" ] }, "valid_to": { "type": [ "string", "null" ] }, "evidence_id": { "type": "string" }, "metadata": { "type": "object" } }, "additionalProperties": false } ================================================================================================ FILE: contracts/schemas/scenario.schema.json AUTHORITY: reference ================================================================================================ { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://kristal.example/contracts/scenario.schema.json", "title": "Kristal Farms Scenario Input", "type": "object", "required": [ "name", "base_data_version", "assumptions" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "base_data_version": { "type": "string" }, "model_version": { "type": [ "string", "null" ] }, "siting_variant": { "enum": [ "generation_side", "community_side", "split" ] }, "assumptions": { "type": "object", "properties": { "generation_mw": { "type": "number", "minimum": 0 }, "community_priority_mw": { "type": "number", "minimum": 0 }, "reserve_mw": { "type": "number", "minimum": 0 }, "compute_min_mw": { "type": "number", "minimum": 0 }, "compute_max_mw": { "type": "number", "minimum": 0 } }, "additionalProperties": true }, "metadata": { "type": "object" } }, "additionalProperties": false } ================================================================================================ FILE: contracts/schemas/source.schema.json AUTHORITY: reference ================================================================================================ { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://kristal.example/contracts/source.schema.json", "title": "Kristal Farms Source", "type": "object", "required": [ "id", "title", "source_type" ], "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "authority": { "type": [ "string", "null" ] }, "source_type": { "type": "string" }, "url": { "type": [ "string", "null" ], "format": "uri" }, "source_date": { "type": [ "string", "null" ], "format": "date" }, "accessed": { "type": [ "string", "null" ], "format": "date" }, "quality": { "type": [ "string", "null" ] }, "scope": { "type": [ "string", "null" ] }, "metadata": { "type": "object" } }, "additionalProperties": false } ================================================================================================ FILE: contracts/schemas/target-village-dossier.schema.json AUTHORITY: reference ================================================================================================ { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://kristal-farms.local/contracts/target-village-dossier.schema.json", "title": "Kristal Farms target village research dossier", "type": "object", "required": [ "schema", "slug", "community_name", "kf_status", "screening_role", "reviewed_at", "development_thesis", "air", "marine", "logistics_envelope", "open_gates", "sources" ], "properties": { "schema": { "const": "kristal-target-village-research/v1" }, "slug": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "community_name": { "type": "string", "minLength": 1 }, "kf_status": { "enum": ["TARGET_SCREENING", "REFERENCE_ONLY", "PAUSED"] }, "screening_role": { "type": "string", "minLength": 1 }, "reviewed_at": { "type": "string", "format": "date" }, "development_thesis": { "type": "string", "minLength": 1 }, "air": { "type": "object", "required": ["access_pattern", "load_status", "pavement_strength", "max_aircraft_mass_kg", "operational_constraints"], "properties": { "access_pattern": { "type": "string" }, "load_status": { "enum": ["published_reference", "not_verified", "unknown"] }, "pavement_strength": { "type": ["string", "null"] }, "max_aircraft_mass_kg": { "type": ["number", "null"], "minimum": 0 }, "operational_constraints": { "type": "array", "items": { "type": "string" }, "uniqueItems": true } }, "additionalProperties": false }, "marine": { "type": "object", "required": [ "access_mode", "commercial_access", "facilities", "approach_depth_m", "anchorage_depth_m", "berth_depth_range_m", "depth_status", "ro_ro", "laydown_available", "load_limits", "seasonality", "constraints", "source_ids" ], "properties": { "access_mode": { "type": "string" }, "commercial_access": { "enum": ["seasonal", "year_round", "not_verified"] }, "facilities": { "type": "array", "items": { "type": "object", "required": ["type", "label"], "properties": { "type": { "type": "string" }, "label": { "type": "string" }, "length_m": { "type": ["number", "null"], "minimum": 0 } }, "additionalProperties": false } }, "approach_depth_m": { "type": ["number", "null"], "minimum": 0 }, "anchorage_depth_m": { "type": ["number", "null"], "minimum": 0 }, "berth_depth_range_m": { "oneOf": [ { "type": "null" }, { "type": "array", "prefixItems": [ { "type": "number", "minimum": 0 }, { "type": "number", "minimum": 0 } ], "minItems": 2, "maxItems": 2 } ] }, "depth_status": { "enum": ["published_reference", "partial_reference", "not_verified"] }, "ro_ro": { "type": ["boolean", "null"] }, "laydown_available": { "type": ["boolean", "null"] }, "load_limits": { "type": "object", "required": ["status", "deck_load_t_m2", "axle_load_t", "max_unit_mass_t", "crane_swl_t"], "properties": { "status": { "enum": ["published_reference", "not_verified", "unknown"] }, "deck_load_t_m2": { "type": ["number", "null"], "minimum": 0 }, "axle_load_t": { "type": ["number", "null"], "minimum": 0 }, "max_unit_mass_t": { "type": ["number", "null"], "minimum": 0 }, "crane_swl_t": { "type": ["number", "null"], "minimum": 0 } }, "additionalProperties": false }, "seasonality": { "type": "object", "required": ["service_type", "start_month", "end_month", "status"], "properties": { "service_type": { "type": "string" }, "start_month": { "type": ["integer", "null"], "minimum": 1, "maximum": 12 }, "end_month": { "type": ["integer", "null"], "minimum": 1, "maximum": 12 }, "status": { "enum": ["published_schedule_context", "general_operating_context", "not_verified"] } }, "additionalProperties": false }, "constraints": { "type": "array", "items": { "type": "string" }, "uniqueItems": true }, "source_ids": { "type": "array", "items": { "type": "string" }, "uniqueItems": true } }, "additionalProperties": false }, "logistics_envelope": { "type": "object", "required": ["marine_delivery", "air_delivery", "heavy_module_status", "assessment_status"], "properties": { "marine_delivery": { "type": "string" }, "air_delivery": { "type": "string" }, "heavy_module_status": { "enum": ["favourable", "constrained", "diligence_required", "unknown"] }, "assessment_status": { "enum": ["partial", "research_ready", "diligence_required"] } }, "additionalProperties": false }, "open_gates": { "type": "array", "items": { "type": "string" }, "uniqueItems": true }, "sources": { "type": "array", "items": { "type": "object", "required": ["id", "title", "publisher", "url", "role"], "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "publisher": { "type": "string" }, "url": { "type": "string" }, "role": { "type": "string" } }, "additionalProperties": false } } }, "additionalProperties": false } ================================================================================================ FILE: contracts/schemas/tenant-eligibility-record.schema.json AUTHORITY: reference ================================================================================================ { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://kristal-farms.example/contracts/schemas/tenant-eligibility-record.schema.json", "title": "Tenant Eligibility Record", "type": "object", "additionalProperties": false, "required": [ "record_id", "classification", "legal_counterparty_name", "incorporation_jurisdiction", "commercial_role", "eligibility_state", "decision_date", "policy_version" ], "properties": { "record_id": {"type": "string", "minLength": 1}, "classification": {"const": "RESTRICTED"}, "legal_counterparty_name": {"type": "string", "minLength": 1}, "incorporation_jurisdiction": {"type": "string", "minLength": 2}, "commercial_role": { "enum": ["tenant", "anchor_offtaker", "tenant_operator", "reseller", "other_material_counterparty"] }, "eligibility_state": { "enum": ["ELIGIBLE", "ENHANCED_DUE_DILIGENCE", "SUSPENDED", "INELIGIBLE"] }, "policy_version": {"type": "string", "minLength": 1}, "decision_date": {"type": "string", "format": "date"}, "next_review_date": {"type": ["string", "null"], "format": "date"}, "ownership_control_verified": {"type": "boolean"}, "sanctions_screening_completed": {"type": "boolean"}, "export_control_review_required": {"type": "boolean"}, "reseller_or_subtenant_model": {"type": "boolean"}, "high_level_workload_class": {"type": ["string", "null"]}, "evidence_refs": { "type": "array", "items": {"type": "string", "minLength": 1}, "uniqueItems": true }, "decision_basis": { "type": "array", "items": {"enum": ["project_policy", "legal_requirement", "commercial_risk", "responsible_business_conduct", "unresolved"]}, "uniqueItems": true }, "notes": {"type": ["string", "null"]} } } ================================================================================================ FILE: contracts/story/showcase-story.example.yaml AUTHORITY: reference ================================================================================================ schema_version: "1.0" scenes: - id: north-context title: Northern energy context panel: story.north-context camera: center: [-73.0, 59.0] zoom: 3.2 pitch: 20 bearing: 0 duration_ms: 2200 layers: visible: [communities] - id: kristal-farms-architecture title: New generation to fibre value export panel: story.kristal-farms-architecture focus_entity: REF-INNAVIK camera: center: [-77.9, 58.45] zoom: 7.0 pitch: 48 bearing: 15 duration_ms: 1800 layers: visible: [communities, reference_projects, conceptual_energy_flow] animation: energy_flow: true reveal_sequence: - generation - community_interface - compute - fibre ================================================================================================ FILE: contracts/story/showcase-story.schema.json AUTHORITY: reference ================================================================================================ { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://kristal.example/contracts/showcase-story.schema.json", "title": "Kristal Farms Showcase Story", "type": "object", "required": [ "schema_version", "scenes" ], "properties": { "schema_version": { "type": "string" }, "scenes": { "type": "array", "items": { "type": "object", "required": [ "id", "camera" ], "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "panel": { "type": [ "string", "null" ] }, "focus_entity": { "type": [ "string", "null" ] }, "camera": { "type": "object", "required": [ "center", "zoom" ], "properties": { "center": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 }, "zoom": { "type": "number" }, "pitch": { "type": "number" }, "bearing": { "type": "number" }, "duration_ms": { "type": "integer", "minimum": 0 } }, "additionalProperties": false }, "layers": { "type": "object", "properties": { "visible": { "type": "array", "items": { "type": "string" } }, "hidden": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "animation": { "type": "object", "additionalProperties": true } }, "additionalProperties": false } } }, "additionalProperties": false } ================================================================================================ FILE: docs/00-control/CLAIMS_TO_VALIDATE.md AUTHORITY: canonical ================================================================================================ # Claims to Validate This register identifies questions that remain open. It is not a finding that a concept is wrong. ## Hydro resources | Claim / assumption | Required evidence | |---|---| | A research river contains a developable hydro project | Authoritative geometry, flow series, terrain, intake/powerhouse concept, hydraulic losses, environmental and rights/governance review. | | A drainage area or mean flow implies buildable MW | Design flow, project head, losses, civil/electrical concept and project constraints. | | A gauge location can stand in for a dam site | Separate engineering siting evidence. | ## Infrastructure substitution | Claim / assumption | Required evidence | |---|---| | Local compute is cheaper than long electrical export | Equal-scope route, voltage, road, substation, fibre, port/local access, compute-site, O&M and financing estimates. | | Long HV/road infrastructure can be materially avoided | Site-specific conventional-export alternative and local architecture. | | The local-compute architecture has lower lifecycle footprint | Comparable land, habitat, materials, water, carbon, logistics and restoration analysis. | ## Fibre and logistics | Claim / assumption | Required evidence | |---|---| | A community has adequate fibre for target workloads | Provider, capacity, redundancy, route, latency, SLA and repair evidence. | | A coastal location supports a practical fibre landing | Landing-zone, marine route, rights, permits, environment and carrier engineering. | | A port can receive project cargo | Facility-specific draft, berth/ramp, lifting/handling, seasonal access and operator confirmation. | ## Compute and energy | Claim / assumption | Required evidence | |---|---| | Existing local grid can host compute | Utility/engineering hosting-capacity determination; planning margin alone is insufficient. | | Cold climate creates a specific PUE/cooling advantage | Site climate and actual cooling design. | | Heat recovery creates project/community value | Real heat sinks, temperatures, load profiles, distribution design and economics. | ## Mine infrastructure reuse and storage | Claim / assumption | Required evidence | |---|---| | A recently closed underground mine can reduce compute-site CAPEX | Current ownership/rights, underground condition, dewatering, ground support, ventilation, egress, power, communications, heat-rejection concept, code/occupancy review and equal-scope reuse-vs-new-build estimate. | | Historical mine electrical infrastructure implies capacity is available today | Current utility/interconnection evidence. Historical voltage or mine load is not hosting capacity. | | Underground placement is inherently a secure “bunker” | Security and engineering design for the specific hazards/standards claimed. Underground location alone does not establish blast, EMP, fire, flood or continuity performance. | | An open pit can serve as a pumped-storage reservoir | Source-backed pit geometry, bathymetry/usable volume, operating water levels, gross/net head, hydraulic route, water balance, geotechnics, seepage, water chemistry and environmental/rights review. | | An old mine is too old to consider as a storage reservoir | Not assumed. Mine age is metadata; reservoir screening is controlled by geometry, geotechnical/environmental condition, water system and grid value. | | The ocean can be used as the lower reservoir without material penalty | Seawater-compatible turbine/pump/material design, liner/seepage strategy, groundwater protection, marine intake/outfall study, corrosion/biofouling plan and permitting. | | Pumped storage creates additional net generation | Not supportable. Storage shifts energy in time and must include pumping energy and round-trip losses. | ## Commercial and regulatory | Claim / assumption | Required evidence | |---|---| | A benchmark $/km is a valid project estimate | Site-specific concept/FEED estimate on equivalent scope. | | A positive economic frontier equals savings | Complete pricing of both architectures on equal scope. | | A tariff/regulatory treatment applies or does not apply | Current utility/regulatory/legal determination for the specific configuration. | ## Governance and community Any project dossier must validate rights-holder/community process, decision rights, land/water/marine implications, benefit arrangements, workforce effects, grievance/remedy mechanisms and anti-capture safeguards before presenting community participation as established. ## International tenancy and commercial demand | Claim / assumption | Required evidence | |---|---| | A named international organization is interested in leasing Kristal Farms capacity | Direct communication, RFI/RFP response, requirements exchange, LOI or other attributable commercial evidence. A research inventory is not evidence of interest. | | A non-U.S. organization is automatically eligible because of its home country | Legal-counterparty, beneficial-ownership/effective-control, sanctions, trade-control and responsible-business due diligence. | | A tenant can use a northern site without material product impact | Workload-specific latency, network, reliability, curtailment, cooling, density, maintenance and data-residency requirements. | | Black-box tenancy means Kristal Farms can guarantee the tenant's private workload content is ethically compliant | Not supportable. The model intentionally avoids routine access to private encrypted content; governance occurs through counterparty selection, contract and lawful process. | | Excluding U.S. counterparties also excludes U.S.-origin technology | Not assumed. Technology-origin/export-control policy is a separate decision. | ## International mobilization and resilience | Claim / assumption | Required evidence | |---|---| | Global compute growth necessarily increases fossil generation in a target country | Country- and time-specific grid mix, marginal-generation/emissions analysis and workload growth evidence. Do not generalize from annual average electricity mix alone. | | A named country or organization can deploy tenant-controlled server containers/modules at a Kristal Farms site | Direct counterparty requirements, Canadian legal/trade review, equipment import/export constraints, data-residency review, telecom requirements and an attributable commercial signal. | | Twelve international participants form a coalition | Multiple attributable expressions of interest/agreements from distinct eligible counterparties plus defined roles. A prospect list is not a coalition. | | International participation makes Kristal Farms protected from attack or equivalent to sovereign territory | Not supportable as a general claim. Any actual security/diplomatic commitment would require explicit legal/government evidence. Commercial stakeholder diversity may improve resilience but is not collective defence. | | International tenant diversity materially improves continuity and recovery | Concentration analysis, contractual continuity obligations, multi-carrier/multi-port/site topology, insurer/lender treatment and incident/recovery planning. | | A coastal site has “low biodiversity” or low ecological impact | Site-specific habitat/species data, protected-area review, seasonal surveys where required, cumulative-effects analysis and rights/governance/environmental assessment. Use “comparatively low ecological sensitivity” only as a screening hypothesis until validated. | | Local generation plus compute has a lower footprint than electrical export | Equal-scope lifecycle comparison including reservoirs, civil works, marine works, fibre, roads, lines, materials, habitat, water and restoration. | ================================================================================================ FILE: docs/00-control/CORRIDOR_DOSSIER_STRATEGY.md AUTHORITY: canonical ================================================================================================ # Corridor Dossier Strategy General regional research is now sufficient to support deeper project work. The next unit of development is a named **corridor dossier**, followed by site concepts only where the evidence supports them. ## Dossier objective For a representative corridor, connect: > **resource → authoritative hydrography → terrain → hydrology → community → port/logistics → fibre → electrical architecture → environment/rights/governance → economics** without converting missing evidence into assumptions by default. ## Minimum dossier sections 1. scope and geography; 2. authoritative source inventory; 3. hydrography and watershed evidence; 4. terrain and potential engineering layouts; 5. hydrology and seasonality; 6. community/rights/governance context; 7. port, sealift and local-access logistics; 8. fibre route/provider/capacity/redundancy; 9. generation and protected community interface; 10. compute siting variants and serviced-pad requirements; 11. environment and permitting constraints; 12. equal-scope economic alternatives; 13. unresolved questions and go/no-go gates. ## Screening rule A dossier may conclude that a corridor is unattractive or insufficiently evidenced. That is a valid result. Evidence completeness, visual prominence and proximity to a community do not constitute a ranking. ================================================================================================ FILE: docs/00-control/DECISIONS_REQUIRED.md AUTHORITY: canonical ================================================================================================ # Decisions Required This register contains unresolved decisions that should be made explicitly rather than inferred from documents or map styling. | ID | Decision | Current handling | |---|---|---| | **D-001** | Which Côte-Nord corridor should be the first pilot dossier? | No active site ranking. Select a corridor for deeper evidence collection, not a winner by score. | | **D-002** | Which compute layout should a dossier test: generation-side, community/port-side, or split? | Keep all three available until electrical/logistics/community evidence narrows the choice. | | **D-003** | What minimum fibre service profile is required for each tenant class? | Record capacity, redundancy, landing/provider and repair assumptions explicitly per scenario. | | **D-004** | What electrical service boundary separates community priority load from flexible compute? | Require a documented protected interface and dispatch/curtailment logic. | | **D-005** | Which serviced-pad interfaces become project standards? | Define power, cooling, fibre, security, telemetry, logistics and maintenance handoffs before procurement. | | **D-006** | Which public datasets and derived layers may be released? | Publish only controlled, non-sensitive, versioned artifacts; exact site/security data requires explicit clearance. | | **D-007** | When may site ranking be enabled? | Only after a transparent methodology, sufficient cross-domain evidence and an explicit governance decision. | | **D-008** | What economic decision metric governs a project dossier? | Use equal-scope scenario economics; do not promote benchmark ratios into site estimates. | | **D-009** | What anti-capture mechanisms should be embedded before land/infrastructure appreciation? | Develop land, housing, infrastructure and governance separation mechanisms before a specific community buildout. | | **D-010** | Which long-term education/community concepts belong in a specific project scope? | Treat as adjacent future programs; do not make them prerequisites for the first energy/compute node. | | **D-011** | When should the proposed r2 jurisdiction schedule be adopted, amended or superseded? | The r2 overlay proposes explicit `INELIGIBLE` and `SUSPENDED` jurisdictions. Adoption or later changes require a documented C0 decision with dated evidence; non-listed jurisdictions remain `ENHANCED_DUE_DILIGENCE`. | | **D-012** | What exact legal test defines "United States-controlled" for the owner-directed counterparty exclusion? | Treat beneficial ownership, effective control and contracting entity as due-diligence inputs; obtain transaction/legal definition before binding contracts. | | **D-013** | Which tenant service telemetry is required for safe operations while preserving content-blind tenancy? | Limit collection to power/cooling/facility/network/SLA needs; no routine plaintext application access or default key escrow. | | **D-014** | Does Kristal Farms adopt any future technology-origin restrictions separate from tenant eligibility? | The proposed expanded counterparty schedule still does **not** imply an embargo on hardware/software/components by origin. Decide separately if required. | | **D-015** | Which military, intelligence, surveillance, cyber-security and other dual-use counterparty classes should become explicit `INELIGIBLE` categories rather than `ENHANCED_DUE_DILIGENCE`? | Current policy applies EDD to these classes and ineligibility only where the adopted risk conditions are substantiated; decide before targeted outreach. | | **D-016** | What evidence threshold promotes a mine from a research/reference object into a Kristal Farms corridor/site reuse dossier? | Require current owner/restoration status, source-backed geometry and infrastructure condition, environmental/rights context, current power/telecom evidence and a defined engineering verification plan. Promotion means deeper study, not ranking or selection. | ## Decision record format When a decision is made, record: - decision ID and date; - decision and rationale; - approver/authority; - evidence reviewed; - affected code/data/docs; - follow-up actions; - superseded decision, if any. ================================================================================================ FILE: docs/00-control/INTERNATIONAL_TENANT_GOVERNANCE.md AUTHORITY: canonical ================================================================================================ # Responsible International Tenancy and Counterparty Governance **Status:** Current project-control policy (C0) **Effective:** 2026-08-31 **Scope:** Tenant, operator, offtaker, reseller and material commercial-counterparty eligibility for Kristal Farms compute infrastructure. **Legal note:** This is a project policy, not legal advice, a sanctions determination, or a human-rights rating of any population. Contracting decisions remain subject to applicable Canadian law, trade controls, sanctions, competition rules and legal review. ## 1. Policy objective Kristal Farms is designed to serve an international compute market without treating maximum tenant volume as the governing objective. The project may decline otherwise lawful business when a counterparty, control structure, jurisdictional exposure or institutional purpose is materially inconsistent with project values, risk tolerance or long-term legitimacy. The governing sequence is: > **jurisdictional eligibility → counterparty due diligence → contractual eligibility → black-box tenancy** Kristal Farms therefore governs **who receives access to project infrastructure**. It does not make routine access to a tenant's private compute content a condition of tenancy. ## 2. International market posture International tenancy is an intended commercial pathway. Prospecting should prioritize organizations that can use remote or northern compute effectively, including large-scale model training, scientific/HPC workloads, batch processing, sovereign or jurisdiction-controlled cloud capacity, and other high-density workloads whose value is not dependent on metropolitan-edge latency. Commercial scale does not override the eligibility policy. A large prospective tenant is not automatically preferred over a smaller eligible tenant. ### 2.1 Current owner-directed jurisdiction schedule The machine-readable jurisdiction schedule is the source of truth for country-level project posture. Under the proposed r2 C0 update, the following jurisdictions are **INELIGIBLE** for tenant, anchor-offtaker and tenant-operator roles: **United States, Russia, Belarus, China, Iran, North Korea, Syria and Myanmar**. The following are placed in **SUSPENDED** status pending a later explicit C0 review: **Afghanistan, Libya, Nicaragua, Somalia, Sudan, South Sudan, Venezuela, Yemen and Zimbabwe**. These are project-level values, risk and commercial-positioning controls. They are not factual claims that every person or organization associated with a listed jurisdiction presents the same conduct or risk. A country-level posture never replaces legal-counterparty, ownership/control, sanctions or transaction-specific legal review. The schedule applies to the **counterparty relationship** and to downstream legal counterparties where capacity is resold or subleased. It does not, by itself, prohibit equipment, software, standards, components, financing instruments or supply-chain dependencies originating in an ineligible jurisdiction. Technology-origin policy is a separate decision and must not be inferred from tenant eligibility. See `contracts/policy/jurisdiction-eligibility.yaml`. Applying the proposed r2 overlay constitutes an explicit C0 adoption decision. ## 3. Eligibility states Kristal Farms uses categorical decisions rather than a numerical "ethics score." | State | Meaning | Contracting posture | |---|---|---| | **ELIGIBLE** | No identified policy-level barrier after proportionate review. | Normal commercial diligence may proceed. | | **ENHANCED_DUE_DILIGENCE** | Material uncertainty, complex ownership, elevated jurisdictional risk or sensitive institutional role requires deeper review. | No binding tenancy until review is closed. | | **SUSPENDED** | Eligibility cannot presently be determined or external events require a temporary hold. | New contracting and expansion paused. | | **INELIGIBLE** | Counterparty or controlling relationship conflicts with an explicit project exclusion or unacceptable risk threshold. | No tenancy/offtake/operator agreement. | The state applies to a **specific legal counterparty and control structure at a point in time**. It must not be generalized to individuals based on nationality, ethnicity, religion or other protected characteristics. ## 4. Jurisdictional screening factors Country and jurisdiction review is a risk-control input, not a moral ranking of populations. The review should consider, with dated sources and legal review where required: - rule of law and independence of institutions; - internationally recognized human-rights conditions; - sanctions, export-control and trade-restriction exposure; - armed-conflict, aggression, atrocity, occupation or severe political-instability risk where relevant to the counterparty; - state-directed censorship, political surveillance or coercive digital-control risk; - corruption, bribery and beneficial-ownership transparency; - labour-rights and forced-labour exposure; - cyber-abuse, state-linked intrusion or technology-transfer risk; - privacy, data-governance and lawful-access environment; - the practical ability to identify the counterparty, its controllers and source of funds; - compatibility with Canadian legal and regulatory obligations. A jurisdiction may be placed in **ENHANCED_DUE_DILIGENCE**, **SUSPENDED** or **INELIGIBLE** status without asserting that every organization in that jurisdiction has engaged in misconduct. The machine-readable jurisdiction schedule uses **ENHANCED_DUE_DILIGENCE as the default for non-listed jurisdictions** until a review establishes an explicit posture. Absence from the schedule is therefore not automatic approval. See `contracts/policy/jurisdiction-eligibility.yaml`. ## 5. Counterparty due diligence Before signing a tenancy, anchor-offtake or tenant-operator agreement, Kristal Farms should establish, proportionate to risk: 1. legal name, registration and principal place of business; 2. ultimate beneficial ownership and persons/entities exercising effective control; 3. relevant parent, subsidiary and affiliated entities; 4. sanctions and restricted-party screening under applicable Canadian law; 5. material export-control or controlled-technology implications known at contracting time; 6. source of funds and financing structure where commercially material; 7. significant public enforcement, corruption, fraud, human-rights or cyber-abuse findings relevant to the relationship; 8. whether the counterparty acts for an undisclosed government, military, intelligence service or sanctioned party; 9. whether the tenant will resell/sublease capacity and, if so, how downstream counterparties remain within the same policy boundary; 10. a high-level declared workload class sufficient for safety, power, cooling, networking and legal classification **without requiring disclosure of private models, datasets, prompts or application content**. Due diligence should be evidence-backed and periodically refreshed. Rumour, social-media controversy or nationality alone is insufficient for an adverse decision. ## 5.1 Institutional-purpose risk treatment Some organization types require a higher bar even when the private workload is not visible. The decision concerns the **counterparty and its externally verifiable institutional role**, not a hidden inspection of tenant content. Presumptive **INELIGIBLE** treatment may apply, when substantiated, to a counterparty whose relevant institutional purpose or conduct includes sanctions evasion/prohibited-party concealment, material eligibility fraud, state-directed repression or unlawful mass surveillance, or offensive cyber activity directed at civilian/shared infrastructure. At minimum **ENHANCED_DUE_DILIGENCE** should apply to military/defence entities, intelligence or state-security bodies, population-scale biometric-surveillance providers, high-risk dual-use technology providers, and reseller/subtenant aggregators. A later C0 decision may tighten or relax these classes. This treatment does not require Kristal Farms to determine the content of an encrypted workload. It is based on the identity, control, declared relationship and externally verifiable conduct of the counterparty. ## 6. Black-box tenancy principle After an eligible counterparty is admitted, the default service is a **tenant-controlled encrypted environment**. "Black-box tenancy" is an acceptable commercial shorthand; the normative meaning is: - tenant-controlled hardware and/or logically dedicated systems as contracted; - tenant-controlled operating systems, models, datasets and applications; - tenant-controlled cryptographic keys; - no operator key escrow as a default service requirement; - no routine Kristal Farms access to decrypted application payloads; - no routine inspection of tenant models, training data, prompts, outputs or internal telemetry; - no covert monitoring mechanism or standing backdoor created for commercial-policy enforcement. Kristal Farms cannot truthfully promise to verify the private content of an encrypted tenant environment that it is contractually and technically designed not to inspect. The project rule is therefore: > **Select counterparties; do not inspect private compute.** See `docs/security/TENANT_CONFIDENTIALITY_BOUNDARY.md` and ADR-0021. ## 7. What Kristal Farms may observe Content blindness does not mean operational blindness. Kristal Farms may collect the minimum information reasonably necessary to provide and protect shared infrastructure, including as contractually defined: - power consumption, power quality and curtailment state; - cooling demand, thermal and environmental telemetry; - physical-access and facility-security events; - network availability, aggregate utilization, routing and fault telemetry; - security signals needed to protect shared facility/network infrastructure without decrypting tenant application content; - billing, metering, SLA and maintenance records; - information voluntarily shared by the tenant for support or incident response. Telemetry must be purpose-limited, access-controlled and retained according to an explicit policy. ## 8. Contractual compliance without content inspection The tenant agreement should rely on **representations, warranties, covenants and termination rights**, not hidden workload surveillance. At minimum, an eligible tenant should contractually undertake to: - comply with applicable Canadian law and valid regulatory requirements; - comply with applicable sanctions, export controls and trade restrictions; - not use the tenancy as a vehicle for sanctions evasion or concealed prohibited-party access; - provide accurate ownership/control information and report material changes; - apply the same eligibility boundary to authorized subtenants/resellers where subletting is permitted; - maintain appropriate security for its own systems, credentials and keys; - cooperate with proportionate legal/compliance inquiries that do not require routine disclosure of private compute content; - notify Kristal Farms when a material change makes a prior eligibility representation inaccurate. A contractual statement is not the same as technical verification of content. Documentation must preserve that distinction. ## 9. Review, suspension and termination triggers A counterparty may be re-reviewed, suspended or terminated when supported by evidence and contract, including: - sanctions designation or a legally binding prohibition; - material undisclosed beneficial-ownership/control change; - substantiated sanctions-evasion or concealed prohibited-party access; - material fraud in eligibility representations; - serious, externally verifiable conduct inconsistent with the adopted counterparty policy; - repeated facility/network abuse that threatens shared infrastructure or other tenants; - legal inability to continue providing the service. The response should be proportionate and documented. The policy does not authorize Kristal Farms to defeat tenant encryption to search for possible violations. ## 10. Legal process and government requests Kristal Farms should maintain a legal-request procedure based on: - validation of jurisdiction and legal authority; - scope minimization; - disclosure only of information Kristal Farms actually possesses or controls; - tenant notice where legally permitted; - no voluntary creation of a standing decryption capability; - no weakening of tenant encryption merely to make future access easier; - documented handling and independent legal review for exceptional requests. If Kristal Farms does not possess tenant keys or decrypted content, documentation must not imply otherwise. ## 11. Resellers, operators and layered tenancy A tenant must not be permitted to defeat the eligibility policy through undisclosed subleasing, nominee structures or reseller chains. Where downstream tenancy is allowed, contracts should define: - whether Kristal Farms approves each downstream legal counterparty or approves a documented eligibility process operated by the primary tenant; - audit rights over the **eligibility process and records**, not private workload content; - notification of material control changes; - suspension rights where the downstream structure cannot be verified. ### 11.1 Capacity-pool separation for resellers and GPU clouds A non-ineligible primary counterparty must not be used as a conduit for ineligible downstream customers. If the tenant/operator normally sells from a global pooled capacity service that may serve ineligible counterparties, the Kristal Farms capacity must be contractually and operationally assigned to a **dedicated eligibility-bounded pool** or another verifiable allocation mechanism. Kristal Farms may audit the downstream **eligibility process and commercial allocation records** needed to verify compliance. It must not use this audit right as a pretext to inspect private models, datasets, prompts, outputs or decrypted workload content. If downstream eligibility cannot be verified, new allocation, expansion or service may be suspended under the policy. ## 12. Governance and evidence discipline International eligibility decisions should record: - decision state and date; - legal counterparty and ownership/control snapshot; - sources reviewed; - reviewer/approver; - unresolved issues; - next review date or trigger; - whether the decision is project-policy, legal requirement, or both. Do not convert third-party democracy, corruption, sanctions or human-rights indices into an automatic Kristal Farms score. External indices are research inputs; project eligibility remains an explicit decision with documented reasoning. ## 13. Reference baseline The policy may draw from, without treating any single source as dispositive: - internationally recognized human-rights instruments already listed in `docs/50-research/governance/HUMAN_RIGHTS_REFERENCE_BASE.md`; - UN Guiding Principles on Business and Human Rights; - OECD Guidelines for Multinational Enterprises on Responsible Business Conduct; - OECD AI Principles where AI actors/workloads are relevant; - current Canadian sanctions regulations and official consolidated reference lists; - current Canadian export-control rules; - jurisdiction-specific legal advice where a real transaction is contemplated. See `docs/50-research/governance/INTERNATIONAL_TENANT_SCREENING_REFERENCE_BASE.md`. ## 14. Policy boundary This document governs **commercial eligibility and confidentiality boundaries**. It does not: - claim that Kristal Farms can determine the contents of an encrypted tenant environment; - authorize discrimination against individuals on protected grounds; - replace sanctions/export-control legal advice; - establish that a specific prospective organization has expressed interest in Kristal Farms; - establish a technology-origin embargo; - create a blanket military/intelligence prohibition beyond the current enhanced-due-diligence treatment unless a later explicit C0 decision does so. ## 15. International diversification and resilience boundary Kristal Farms may intentionally diversify eligible tenants across multiple jurisdictions to reduce commercial concentration risk and improve continuity incentives. A disruption affecting several independent foreign tenants may create broader commercial, insurance, supply-chain or diplomatic attention than a single-tenant asset would receive. That strategic benefit must remain bounded by evidence and contract. International tenancy does **not** by itself: - create a military or collective-defence alliance; - make Kristal Farms sovereign or extraterritorial territory of a tenant's home state; - guarantee intervention by a foreign government; - override Canadian law, sanctions, trade controls or lawful process; - permit a tenant to conceal its legal identity or effective control behind the black-box content boundary. The project should therefore describe this objective as **international stakeholder diversification** or **distributed international resilience** until actual agreements justify stronger language. See `docs/10-core/strategy/PLAN_MOBILISATION_INTERNATIONALE_KRISTAL_FARMS_FR.md`. ================================================================================================ FILE: docs/00-control/QA_REPORT.md AUTHORITY: canonical ================================================================================================ # Repository QA **Current validation date:** 2026-08-31 ## Automated status - Python tests: **55 passed** on the clean source tree. - Domain model validator: **PASS** — 92 entities, 24 hydrometric stations, 24 river references, 100 observations, 240 screening-dimension states. - Hydrology validator: **PASS** — 72 HYDAT ingestion jobs; no fabricated observation series. - Integrated atlas validator: **PASS** — 92 entities, 126 relations, 15 catalog layers, 7 Showcase scenes. - Economics validator: **PASS** — 10 benchmarks, 3 scenarios, 64 sensitivity cases. - Active repository Markdown relative links: **160 checked, 0 broken**. - Repository-hygiene tests: **PASS** — no internal research numbering, retired product naming, unrelated project terminology or superseded siting rules in active surfaces. - International tenancy policy contracts: **PASS** — categorical eligibility, jurisdiction schedule, non-listed jurisdiction EDD default, downstream eligibility/ring-fencing and content-blind tenancy invariants parse and test successfully. - Mine-reuse policy tests: **PASS** — recent-closure preference is limited to infrastructure reuse; historical open pits remain eligible for reservoir research; bunker/power/ranking inference guards are enforced. - Screening: **unranked**. ## Required invariants - Planning margin is not converted into hosting capacity. - Project head, design flow and buildable MW are not inferred by generic hydrology pipelines. - Conceptual corridors do not gain synthetic route geometry. - External reference projects are not silently promoted to Kristal Farms candidates. - Economic benchmarks remain reference-only and cannot produce bankable NPV/IRR automatically. - Unknown and unpriced inputs remain explicit. - Public releases contain no legacy ranking fields or private data hidden only by UI state. - Active project documentation uses current Kristal Farms terminology. - Superseded working-source extractions and old deployment narratives remain outside active documentation. - Tenant-governance policy does not imply private-workload inspection or a technology-origin embargo. - Mine age does not create a universal eligibility rule: recent closure is a reuse-condition signal, while old open pits may remain valid reservoir research objects. - Historical mine power, mine depth and total pit volume are not silently converted into current compute capacity, hydraulic head or usable storage volume. Historical QA and older research snapshots are preserved under `archive/` for provenance only. ================================================================================================ FILE: docs/00-control/RELEASE_STATUS.md AUTHORITY: canonical ================================================================================================ # Release Status **As of:** 2026-08-31 ## Active state | Area | Status | Interpretation | |---|---|---| | Project reference architecture | **Current** | Governs current project intent and architecture language. | | Application architecture | **Current design contract** | Governs data model, UX surfaces, APIs and publishing architecture. | | Hydrology research registry | **Current research baseline** | Official station anchors and evidence; not dam sites or capacity estimates. | | Integrated atlas | **Current research/application baseline** | Joins evidence and entities without fabricating geometry. | | Economic architecture frontier | **Current non-bankable research method** | Structural comparison only; benchmarks are not site costs. | | Site ranking | **Disabled** | `ranking_allowed = false`. | | Corridor/site feasibility | **Not established** | Requires project-specific engineering, environment, rights/governance, telecom, logistics and economics. | | Public application release | **Design/data foundation** | Current data contracts and static outputs exist; production Web/API implementation is not complete. | | Long-horizon human/learning concepts | **Optional / not prerequisite** | Kept separate from the first-line energy/compute project case and not presented as committed institutions or programs. | | International tenancy governance | **Current control policy** | Counterparty eligibility is selective; U.S.-based/U.S.-controlled tenant roles are excluded by current owner policy and non-listed jurisdictions default to enhanced due diligence. | | Tenant confidentiality boundary | **Current reference/security model** | Tenant-controlled encrypted environments are content-blind to routine operator access; counterparty governance does not imply private workload inspection. | | International prospect inventory | **Research only** | Named organizations are candidates for research and do not imply interest, commitment or eligibility. | | Mine infrastructure reuse & storage | **Exploratory research** | Recent underground mines may be studied for infrastructure reuse; open pits of any age may be studied for pumped-storage geometry. No mine is selected or represented as available/feasible. | ## External-use rule Use active documents and current releases only. Superseded partner packages, historical reports and old screening logic are retained under `archive/` for provenance and must not be presented as current project direction. ## Observatory interface sync — 2026-08-31 The repository frontend is synchronized through Observatory v0.2.4: - MapLibre 6 / Next 16 worker-safe integration - Geographic Observatory river/context interactions - human-readable evidence inspector - corrected feature-state radius expressions - hydration tolerance for browser-extension body attributes - clean basemap without park/landuse surface pop-in - Natural Earth fade fix to avoid pitch-black zoom transitions - automatic fit to governed published extent + Reset view - static local satellite imagery contract and manual GDAL publication pipeline - no runtime satellite API key/provider ================================================================================================ FILE: docs/00-control/SOURCE_TRACEABILITY.md AUTHORITY: canonical ================================================================================================ # Source Traceability Kristal Farms separates project intent from external evidence. ## Source classes - **Government / regulator / utility:** primary evidence for official status, infrastructure, hydrology, tariffs and regulatory records within source scope. - **Community / Indigenous organization:** primary evidence for positions, governance, local infrastructure and community-defined priorities within source scope. - **Operator / company:** evidence for its own projects, services and published specifications; commercial claims require context. - **Academic / consultant:** research evidence; methodology and date must be retained. - **Project direction:** authoritative for Kristal Farms intent only, not independent evidence of technical/economic feasibility. - **Legacy source:** retained for provenance; may be superseded or conflict with current direction. - **User-provided concept note:** preserves a supplied hypothesis or framing for provenance; it can seed research questions but is not independent technical evidence until its claims are separately sourced/validated. ## Current project-direction records - `sources/owner-direction/2026-08-30-canonical-project-direction.md` - `sources/owner-direction/2026-08-30-hydro-resource-atlas-direction.md` - `sources/owner-direction/2026-08-30-application-data-direction.md` - `sources/owner-direction/2026-08-30-economic-comparison-direction.md` ## Current user-provided research sources - `sources/user-provided/step_mine_ocean.md` — coastal mine-pit/ocean pumped-storage concept note; preserved verbatim and treated as a research hypothesis source. ## Traceability rule Important claims should be able to answer: - who published the source; - what the source actually states; - publication/validity date; - retrieval date; - the supporting passage/table/record; - whether the project is recording a fact, interpretation, derived value or assumption; - whether later evidence conflicts with it. A source may support evidence without providing geometry. Missing geometry must not be repaired by inventing coordinates. ================================================================================================ FILE: docs/00-control/WORKSTREAMS.md AUTHORITY: canonical ================================================================================================ # Workstreams Kristal Farms work is organized by project dependencies, evidence gates and deliverables. | Workstream | Objective | Next controlled output | |---|---|---| | **WS-01 Project architecture** | Maintain the physical and commercial reference architecture. | Interface specifications and archetype deltas. | | **WS-02 Corridor dossiers** | Convert broad regional evidence into a small number of deep project dossiers. | Corridor evidence packs and go/no-go gates. | | **WS-03 Hydrology & hydro geometry** | Materialize authoritative basin/flowline data, source series and terrain evidence. | Accepted research reaches, hydrology profiles and engineering inputs. | | **WS-04 Generation & electrical** | Define new generation concepts and protected community interfaces. | Concept single-lines, dispatch logic and interconnection scope. | | **WS-05 Compute sites** | Standardize serviced-pad interfaces and tenant boundaries. | Pad/service specification and operating model. | | **WS-06 Fibre & telecom** | Establish actual routes, capacity, redundancy, provider and repair options. | Carrier/route evidence and connectivity design. | | **WS-07 Ports & logistics** | Validate marine facilities, heavy-project-cargo capability and local access. | Logistics plan and vendor/facility evidence. | | **WS-08 Environment & rights/governance** | Screen ecological, cultural, legal and community constraints before site claims. | Evidence matrix, engagement plan and decision gates. | | **WS-09 Economics** | Replace broad benchmarks with equal-scope project estimates. | Versioned scenario economics and sensitivity analysis. | | **WS-10 Application & data** | Maintain PostGIS, provenance, catalog, APIs, Explorer/Showcase and releases. | Reproducible application/data releases. | | **WS-11 Security & tenancy** | Formalize physical-service boundary and tenant sovereignty. | Threat model, controls and SLA boundary. | | **WS-12 Workforce & operations** | Build repeatable northern construction, maintenance and training capability. | Operations playbook and capability plan. | | **WS-13 Community value & heat** | Evaluate heat and other local co-benefits where site-specific demand exists. | Heat/load study and benefit options. | | **WS-14 Long-term network** | Test multi-node fibre/marine/electrical resilience once individual nodes are credible. | Regional topology scenarios. | | **WS-15 International tenancy & counterparty governance** | Build a responsible, jurisdiction-aware international tenant pipeline while preserving content-blind tenancy. | Eligibility register, due-diligence workflow, tenant requirement matrix and contractual control set. | | **WS-16 Mine infrastructure reuse & storage** | Test whether northern mining assets can reduce new-build scope through underground/industrial reuse, surface brownfields or mine-pit pumped storage. | Unranked mine inventory, source-backed geometry/infrastructure evidence and reuse-specific engineering/environmental gates. | | **WS-17 International mobilization & distributed resilience** | Validate multi-country demand for tenant-controlled compute and coordinate the Canadian, telecom, marine and site-enabling conditions without implying a defence alliance. | Tenant requirement exchanges/LOIs, government coordination map, carrier feasibility responses, concentration-risk register and international portfolio gates. | Every workstream should have an owner, current status, next decision, evidence links, risks and a single next deliverable. ================================================================================================ FILE: docs/10-core/Architecture_de_reference_du_projet_Kristal_Farms_FR.md AUTHORITY: reference ================================================================================================ # Architecture de référence du projet Kristal Farms ## Thèse centrale Kristal Farms est une architecture d’accès aux ressources énergétiques nordiques. L’inversion centrale est : > **amener une charge de calcul flexible à l’énergie éloignée et exporter la valeur numérique par fibre, plutôt que dépendre par défaut de longues routes et de longs corridors électriques haute tension.** La réduction ou l’évitement des longues routes et lignes HV est une proposition de valeur structurelle primaire. Elle n’est pas présumée universellement avantageuse : l’économie doit être démontrée corridor par corridor et site par site. ## Géographie - Côte-Nord : géographie de pilote/apprentissage. - Québec nordique et Labrador : territoire de déploiement à long terme où l’éloignement des routes/HV peut créer le contraste structurel le plus fort. ## Architecture physique Trois dispositions restent valides : calcul près de la centrale, calcul près du village/port, ou architecture hybride. Le choix dépend de la distance électrique, de la valeur de la chaleur, de la fibre, de la logistique, de l’environnement, de la maintenance, de la sécurité et du choix communautaire. ## Modèle commercial du calcul Kristal Farms peut offrir des sites/pads de calcul viabilisés plutôt que posséder tous les serveurs. L’infrastructure commune peut fournir alimentation électrique, interface de refroidissement, fibre, sécurité, comptage/télémétrie et accès logistique. Les locataires gardent la souveraineté sur leur matériel, OS, modèles, données, clés et télémétrie interne. ## Priorité énergétique communautaire Les réseaux villageois existants sont une infrastructure communautaire protégée; ils ne sont pas présumés fournir plusieurs MW disponibles au calcul. L’architecture étudiée est principalement : > **nouvelle production → interface communautaire protégée → calcul flexible → export par fibre** Les charges communautaires/critiques ont priorité sur le calcul interruptible. ## Chaleur La chaleur est un coproduit utile, pas une règle universelle de localisation. Elle est récupérée lorsque sa valeur utile dépasse le coût et la complexité de récupération/distribution. ## Réseau et modularité Le programme peut utiliser des projets hydro/renouvelables petits, moyens ou plus grands lorsque justifiés, avec une croissance du calcul pad par pad. Des nœuds réussis peuvent former un chapelet côtier/de bassins relié principalement par fibre et logistique maritime, avec des interconnexions électriques plus courtes lorsqu’elles apportent de la résilience. ## Gouvernance internationale des locataires Kristal Farms vise un marché international tout en restant sélectif sur ses contreparties. L'admissibilité est établie avant l'accès à partir de la juridiction, de la propriété effective et du contrôle, des sanctions/contrôles commerciaux et d'une diligence raisonnable de conduite responsable. La politique actuelle du propriétaire exclut les contreparties établies ou contrôlées aux États-Unis des rôles de locataire, acheteur ferme principal (*anchor offtaker*) et opérateur-locataire. Cette exclusion commerciale ne constitue pas, à elle seule, un embargo sur l'origine technologique. ## Location aveugle au contenu L'environnement normal est un **environnement chiffré sous contrôle du locataire** (raccourci commercial : location « black box »). Kristal Farms exploite le plan des services physiques partagés; le locataire contrôle le calcul privé. L'exploitation normale n'exige pas l'accès de Kristal Farms aux modèles privés, jeux de données, contenus applicatifs ou clés cryptographiques du locataire. La conformité repose donc sur la contrepartie et le contrat plutôt que sur l'inspection du contenu. Voir `docs/00-control/INTERNATIONAL_TENANT_GOVERNANCE.md` et `docs/security/TENANT_CONFIDENTIALITY_BOUNDARY.md`. ## Gouvernance et anti-capture Le capital peut financer l’infrastructure sans acquérir automatiquement le contrôle de la terre, du logement, de l’énergie, du port, de la fibre, de l’emploi et de la gouvernance communautaire. ## État du screening Il n’existe **aucun classement actif de sites**. Toute priorisation future exige des preuves transparentes en hydrologie, terrain/head, environnement, gouvernance communautaire/autochtone, logistique, télécom, architecture électrique et économie actuelle. ================================================================================================ FILE: docs/10-core/deployment/STRATEGIE_DE_DEPLOIEMENT_FR.md AUTHORITY: reference ================================================================================================ # Kristal Farms — Stratégie de déploiement **Statut :** stratégie de déploiement actuelle. Ce document n'est ni une approbation de site, ni un échéancier de construction, ni une entente communautaire, ni un engagement d'investissement. ## Objectif Kristal Farms doit démontrer son architecture progressivement plutôt que présumer qu'un grand projet, une seule rivière ou une seule disposition physique convient partout. La boucle d'exploitation est : > **concevoir/construire → exploiter → mesurer → corriger → standardiser → répliquer ou agrandir** ## Géographie pilote La Côte-Nord est la géographie pilote/d'apprentissage privilégiée parce qu'elle peut combiner des conditions nordiques avec un accès maritime/routier, des services et un soutien d'entretien comparativement plus pratiques. Le pilote sert à démontrer l'architecture et le modèle d'exploitation; il ne prédétermine pas la géographie de déploiement à long terme. Le déploiement à plus long terme vise le Québec plus nordique et le Labrador, là où l'éloignement des routes et des corridors haute tension peut créer l'avantage structurel le plus fort pour le calcul local et l'export numérique. ## Ce que le pilote doit démontrer Un pilote utile doit produire des preuves sur : - la performance de la production et ses contraintes saisonnières; - l'interface communautaire/charges critiques protégées lorsqu'une communauté est concernée; - les interfaces modulaires de puissance, refroidissement, comptage et sécurité des sites de calcul; - la disponibilité, capacité, redondance et maintenabilité de la fibre; - la logistique maritime et terrestre, y compris les équipements lourds lorsque requis; - la charge d'entretien, les pièces de rechange et les rotations de personnel; - le suivi environnemental et les processus de droits/gouvernance; - les coûts réels de construction et d'exploitation; - la valeur réelle d'une éventuelle récupération de chaleur; - le maintien ou non de l'avantage de l'architecture calcul-local/export-numérique après intégration des coûts propres au projet. ## Technologie énergétique L'hydro est la thèse de ressource principale, mais le déploiement n'impose pas une seule échelle ni une seule configuration hydro. Hydro existante, fil de l'eau, petits/moyens développements, projets plus grands et systèmes renouvelables/stockage complémentaires peuvent être étudiés lorsqu'ils sont justifiés. Aucune technologie n'est automatiquement la « première étape ». Le premier actif doit être celui qui réduit le mieux l'incertitude du pilote retenu tout en respectant les contraintes techniques, environnementales, juridiques, de droits/gouvernance et communautaires. ## Localisation du calcul Trois dispositions restent valides : 1. côté production; 2. côté communauté/port; 3. hybride/répartie. Le choix dépend de la distance électrique, de la fibre, du refroidissement, de la valeur de la chaleur, de la logistique, de l'entretien, de l'environnement, de la sécurité et de la préférence de la communauté hôte. Ni « village-side » ni « dam-side » n'est universel. ## Règle communautaire Lorsqu'une communauté est impliquée, les charges communautaires et critiques sont protégées avant le calcul flexible. Les petits réseaux communautaires existants sont une infrastructure protégée et un contexte de référence; ils ne sont pas présumés disposer de plusieurs MW libres pour le calcul. La participation, les bénéfices et les infrastructures locales doivent être développés avec les titulaires de droits et autorités concernés. Un territoire éloigné n'est jamais traité comme vide ou sans droits. ## Chaleur La récupération de chaleur est optionnelle. Elle est mise en œuvre seulement lorsque la valeur de chaleur utile dépasse le coût et la complexité de captation et de distribution. ## Portes de décision Après chaque étape importante, documenter : - coûts et échéancier réels versus prévus; - performance énergétique et de calcul; - fiabilité et charge d'entretien; - performance fibre/réseau; - performance logistique; - observations environnementales; - résultats communautaires/titulaires de droits; - résultats de main-d'œuvre et de formation lorsque pertinents; - risques et lacunes de preuve restant ouverts. La décision suivante doit être explicite : > **répéter, ajuster, agrandir, déplacer, mettre en pause ou arrêter.** ## Croissance Le calcul doit croître pad par pad et la production seulement lorsqu'elle est justifiée. Des nœuds réussis peuvent éventuellement former un chapelet hydro/calcul/fibre/port, avec la mer comme corridor logistique majeur et des interconnexions électriques plus courtes lorsqu'elles améliorent la résilience. Un seul grand corridor haute tension vers le sud n'est pas l'architecture présumée par défaut. ================================================================================================ FILE: docs/10-core/Kristal_Farms_Project_Reference_Architecture_EN.md AUTHORITY: reference ================================================================================================ # Kristal Farms Project Reference Architecture ## Core thesis Kristal Farms is a northern hydro/renewable resource-access architecture. Its central inversion is: > **bring flexible compute to remote energy and export digital value by fibre, rather than defaulting to long roads and long high-voltage electrical export corridors.** Avoiding or materially reducing long roads and HV corridors is a primary structural value proposition because it may open remote hydro resources that are unattractive under the conventional delivery model. The economic advantage is **not assumed universal**; it must be demonstrated per corridor/site. ## Geography - Côte-Nord is the preferred pilot/learning geography because it can combine northern conditions with more practical access and logistics. - The long-term resource thesis extends farther north through Québec and Labrador, where road/HV remoteness creates the strongest structural contrast. ## Physical architecture Three compute layouts remain valid: 1. generation/dam-adjacent compute; 2. village/port-adjacent compute; 3. hybrid split architecture. Selection depends on electrical distance, heat value, fibre, marine/ground logistics, maintenance, environment, security and community choice. ## Compute commercial model Kristal Farms can provide leaseable serviced compute sites/pads rather than owning every server. The shared infrastructure can provide power handoff, cooling interface, fibre handoff, security, metering/telemetry, logistics and maintenance access. Tenants retain sovereignty over their hardware, operating systems, models, data, keys and internal telemetry. ## Community energy rule Existing village grids are protected community infrastructure, not assumed multi-megawatt compute supplies. The architecture under research is primarily: > **new generation → protected community interface → flexible compute → fibre export** Community/critical loads have priority over interruptible compute. ## Heat Heat is a valuable co-product, not a universal siting rule. Recover/use it where useful heat value exceeds recovery/distribution cost and complexity. ## Modularity and network The program can use small, medium and larger hydro/renewable projects where justified, scaling compute pad by pad. Successful nodes may form a coastal/watershed chain linked primarily by fibre and marine logistics, with shorter electrical interties where useful for resilience. ## Commercial/data sovereignty boundary Shared physical-service interfaces and tenant-controlled digital systems are a core commercial boundary: Kristal Farms can meter and operate physical services without requiring access to tenant application data. ## International tenant governance Kristal Farms is intended to be internationally marketable while remaining selective about counterparties. Tenant eligibility is determined before access through the jurisdiction schedule, ownership/control, sanctions/trade-control, downstream-customer exposure and responsible-business due diligence. This commercial exclusion does not itself create a technology-origin embargo. ## Content-blind tenancy The normal tenant environment is a **tenant-controlled encrypted environment** (commercial shorthand: black-box tenancy). Kristal Farms operates the shared physical-service plane; the tenant controls private compute. Routine operations do not require operator access to private models, datasets, application payloads or tenant cryptographic keys. Compliance is therefore counterparty- and contract-based rather than content-inspection-based. See `docs/00-control/INTERNATIONAL_TENANT_GOVERNANCE.md` and `docs/security/TENANT_CONFIDENTIALITY_BOUNDARY.md`. ## Governance / anti-capture Capital may finance infrastructure, but capital should not automatically acquire control over community land, housing, energy, port, fibre, employment and governance. The project should preserve shared interfaces with separated authority and design anti-capture mechanisms before land/infrastructure appreciation creates incentives for concentration. ## Current screening rule There is **no active site rank**. Future prioritization requires transparent evidence across hydrology, terrain/head, environment, Indigenous/community governance, logistics, telecom, electrical architecture and current economics. ================================================================================================ FILE: docs/10-core/strategy/KRISTAL_FARMS_VISION_EN.md AUTHORITY: reference ================================================================================================ # Kristal Farms — Northern Energy-to-Compute Vision **Status:** Current strategic narrative. Not a site feasibility report or investment claim. Kristal Farms proposes a different way to access remote northern renewable resources: > **bring flexible compute to the energy, consume the electricity locally, and export digital value by fibre.** ## Why this matters A remote hydro resource is not only an energy question. Its practical value can depend on roads, transmission, substations, logistics, fibre, environmental constraints and community/rights context. Kristal Farms tests whether moving a transportable digital load can reduce the infrastructure required to monetize some remote resources. ## Physical model A node combines: - new renewable generation; - a protected community interface where relevant; - serviced compute sites; - fibre connectivity; - marine/ground logistics; - optional heat recovery and storage where justified. Compute can sit near generation, near a community/port, or be split between both. ## Commercial model Kristal Farms can provide infrastructure services while tenants retain sovereignty over their servers, operating systems, models, data, logs and keys. The host operates physical services; the tenant controls the digital workload. ## International tenancy Kristal Farms is intended to serve an international tenant market while remaining selective about counterparties. The machine-readable jurisdiction schedule, beneficial ownership/effective control, downstream-customer exposure, sanctions/trade exposure and responsible-business conduct are reviewed before contracting. The normal tenancy model is a **tenant-controlled encrypted environment**: the host runs agreed physical services and minimum necessary service telemetry while private compute remains content-blind to routine host operations. ## Geography and scaling Côte-Nord is a practical pilot/learning geography. The longer-term thesis extends farther north through Québec and Labrador, where lack of roads and long electrical-export distance can create the strongest structural contrast. Nodes can scale pad by pad. Successful nodes may eventually form a chain linked primarily by fibre and marine logistics, with shorter electrical interties where they improve resilience. ## Community and environmental discipline Community/critical loads have priority over flexible compute. No site is assumed acceptable because it is remote. Hydrology, ecology, rights/governance, logistics, fibre, engineering and economics must be evaluated explicitly. ## Long-term capability If the architecture works repeatedly, northern construction, operations, fibre, cold-climate compute and remote-energy expertise become a reusable capability. Education, research and new community infrastructure may grow around successful nodes, but they are not prerequisites for proving the first energy/compute architecture. ================================================================================================ FILE: docs/10-core/strategy/PLAN_MOBILISATION_INTERNATIONALE_KRISTAL_FARMS_FR.md AUTHORITY: reference ================================================================================================ # Plan de mobilisation internationale — Kristal Farms **Statut :** direction stratégique active, à valider par preuves commerciales, techniques, environnementales, juridiques et gouvernementales. **Date :** 2026-08-31 **Origine :** direction fournie par le fondateur et unique membre de l’Initiative kOA pour le projet Kristal Farms. **Limite :** ce document ne constitue ni engagement d’un gouvernement, ni coalition contractuelle, ni garantie de sécurité, ni sélection définitive de sites ou de locataires. ## 1. Thèse internationale La demande mondiale de calcul augmente rapidement. Selon le pays, le moment et le mix électrique marginal, une nouvelle charge de calcul peut accroître directement ou indirectement l’utilisation de production fossile. Kristal Farms ne doit pas généraliser cette affirmation à tous les pays : l’effet doit être évalué marché par marché. La proposition Kristal Farms est de créer **une nouvelle capacité renouvelable au Québec nordique**, de la consommer presque entièrement sur place par du calcul flexible et de transporter la valeur numérique par fibre plutôt que de construire par défaut de longues lignes de transport d’électricité. Le message aux partenaires internationaux est donc : > **Vous gardez le contrôle de votre calcul. Nous créons l’environnement physique renouvelable, portuaire et télécom qui permet de l’exécuter au Canada.** ## 2. Doctrine physique des ensembles Les ensembles internationaux doivent être recherchés selon cinq critères dominants : 1. **nouvelle production renouvelable** développable à proximité du campus, principalement hydro lorsqu’elle est techniquement, environnementalement et socialement justifiée; 2. **consommation locale** de la puissance par le centre de calcul, afin de réduire la dépendance aux longues infrastructures électriques d’export; 3. **accès portuaire ou maritime pratique** pour le matériel lourd, les transformateurs, turbines, modules de calcul, pièces et logistique de construction; 4. **connexion de données haute capacité** par des standards télécom existants, avec capacité, redondance, route, SLA et réparation à valider; 5. **sensibilité écologique relativement faible**, ce qui signifie éviter autant que possible les aires protégées, habitats critiques, zones humides sensibles et secteurs à forte valeur écologique ou culturelle, sans jamais remplacer les études de terrain par une impression de « faible biodiversité ». Un barrage existant n’est pas la base du modèle commercial. Une alimentation existante peut servir temporairement au chantier si elle est disponible et autorisée. La capacité finale doit provenir d’une **nouvelle ressource développée pour le site**. ### Séquence énergétique possible Une séquence de référence peut être : > **éolien + secours thermique temporaire → petit hydro neuf → hydro principal ou cascade de petits ouvrages → expansion graduelle du calcul** Le petit ouvrage peut fournir une énergie stable au chantier du projet suivant. Cette séquence demeure une hypothèse d’architecture : elle ne doit pas être imposée à un site lorsque les données montrent une meilleure solution. ## 3. Modèle de location internationale Kristal Farms fournit, selon le contrat : - site et emprise servis; - énergie et qualité de puissance; - refroidissement ou interface de rejet thermique; - sécurité physique; - manutention et logistique locale; - comptage et télémétrie de service; - **handoff télécom standard** vers les opérateurs retenus. Le locataire contrôle, selon son architecture : - serveurs, GPU, stockage et matériel réseau privé; - containers, modules, racks ou salles dédiées; - systèmes d’exploitation, orchestration et logiciels; - modèles, données, journaux privés et clés cryptographiques; - réplication, caches, routage applicatif et transferts de données. Kristal Farms ne crée pas de protocole propriétaire, de format de transmission propriétaire ni de « réseau de données Kristal » entre locataires. Les transporteurs et locataires utilisent les standards existants et leurs propres architectures. ## 4. Pourquoi une mobilisation internationale Le portefeuille recherché n’est pas un seul mégacampus dépendant d’un seul client. Il vise plusieurs ensembles et plusieurs contreparties admissibles, idéalement répartis entre plusieurs juridictions stables. Cette diversité crée plusieurs couches de résilience : ### 4.1 Résilience énergétique et physique - production distribuée entre plusieurs ensembles; - consommation près de la production; - campus modulaires capables de croître par phases; - accès maritime permettant des chaînes logistiques différentes; - réduction de la dépendance à une seule longue ligne électrique. ### 4.2 Résilience télécom - standards de transport existants plutôt qu’un protocole propriétaire; - recours possible à plusieurs transporteurs et plusieurs routes physiques; - interconnexion aux grands centres selon des architectures à valider; - absence d’un plan de données partagé obligatoire entre locataires. ### 4.3 Résilience commerciale - plusieurs locataires et pays plutôt qu’un seul anchor tenant; - modules contrôlés indépendamment par les locataires; - possibilité de remplacer ou agrandir un bloc sans reconfigurer tout le portefeuille; - demande internationale diversifiée pouvant réduire le risque de dépendance à un seul marché. ### 4.4 Résilience politique et diplomatique Si plusieurs entreprises ou institutions étrangères exploitent du matériel important dans différents ensembles Kristal Farms, une perturbation majeure pourrait toucher simultanément plusieurs intérêts économiques étrangers. Cela **peut** augmenter les incitations à la continuité de service, à la restauration rapide, à la coopération commerciale et à l’attention diplomatique. La formulation correcte est : > **Kristal Farms cherche une résilience par diversification d’intérêts internationaux.** Il ne faut pas affirmer : - qu’un locataire étranger apporte une protection militaire; - qu’une attaque contre Kristal Farms équivaut juridiquement à une attaque contre son pays d’origine; - qu’une coalition de défense existe avant des accords réels; - qu’un campus bénéficie d’extraterritorialité; - que la location black box soustrait le locataire ou Kristal Farms au droit canadien. ## 5. La coalition recherchée Le mot **coalition** décrit ici un objectif commercial et institutionnel : une pluralité de parties ayant chacune un intérêt indépendant dans la continuité du système. Les catégories recherchées sont : - locataires/opérateurs internationaux de calcul; - gouvernements du Québec et du Canada dans leurs rôles applicables; - communautés et titulaires de droits concernés; - producteurs/développeurs d’énergie autorisés; - opérateurs télécom et transporteurs de fibre; - autorités et opérateurs portuaires/maritimes; - fournisseurs d’équipements et de maintenance; - financeurs et assureurs admissibles. Aucune de ces catégories n’est présumée engagée avant preuve directe. ## 6. Portefeuille international : 12 places, pas 12 engagements inventés Le paysage commercial actuel identifie plusieurs organisations à étudier, notamment OVHcloud, Nebius, Nscale, SK Telecom, NAVER/NAVER Cloud, Sakura Internet, KDDI, Deutsche Telekom/T-Systems, Scaleway/iliad, Infomaniak et Exoscale. Leur présence dans le registre de recherche ne signifie pas qu’elles ont manifesté un intérêt. Le plan international peut conserver **12 places de portefeuille**, mais la douzième ne doit pas être remplie artificiellement. Une organisation ne devient cible officielle que lorsque : 1. son contrôle et sa juridiction passent le screening applicable; 2. son type de workload peut réellement fonctionner au Canada/nord du Québec; 3. ses exigences de puissance, fibre, refroidissement, maintenance et résidence des données sont compatibles; 4. un contact direct produit au minimum un signal commercial attribuable. L’objectif n’est donc pas « un pays par barrage » dès maintenant. L’objectif est **un ensemble de besoins internationaux validés**, puis un appariement entre exigences de locataires et ensembles énergétiques réellement développables. ## 7. Question posée aux organisations internationales Le premier contact doit valider la demande plutôt que vendre un site non prouvé : > **Votre organisation envisagerait-elle de déployer et contrôler son propre matériel de calcul au Canada sur un site alimenté par une nouvelle production renouvelable locale, sous réserve du prix, de la fibre, de la redondance, de la réglementation, de la logistique et de vos exigences de souveraineté des données?** Les informations recherchées sont : - MW initiaux et trajectoire d’expansion; - densité par rack/module et technologie de refroidissement; - format d’installation : container, module préfabriqué, salle, cage ou bâtiment; - latence maximale et marchés de peering requis; - capacité fibre, diversité de chemins et SLA; - politique de curtailment/interruption acceptable; - exigences de résidence/souveraineté des données; - préférence matériel locataire vs matériel fourni; - durée minimale de contrat et structure d’offtake; - exigences physiques de maintenance et sécurité; - restrictions d’exportation/importation de matériel ou technologie. ## 8. Question posée au Québec et au Canada La mobilisation politique ne demande pas d’approuver immédiatement douze barrages ou un réseau télécom complet. Elle demande de valider si le pays souhaite **étudier et coordonner** une nouvelle classe d’infrastructure : production renouvelable nordique + consommation de calcul locale + accès maritime + transport numérique vers les grands centres. La demande initiale est : 1. reconnaître le concept comme une hypothèse d’infrastructure à évaluer; 2. nommer les interlocuteurs pertinents pour énergie, environnement, télécom, ports, investissement et développement nordique; 3. permettre une table de faisabilité avec transporteurs, communautés/titulaires de droits et partenaires industriels; 4. définir les conditions sous lesquelles des locataires étrangers peuvent installer et contrôler leur matériel au Canada; 5. identifier les corridors numériques existants qui peuvent être renforcés avant d’envisager de nouvelles constructions. ## 9. Dorsale de données : besoin, pas technologie propriétaire Kristal Farms peut exprimer un besoin pour une **dorsale de transport numérique multi-opérateurs** reliant les ensembles retenus aux grands centres, mais ne doit pas présumer la topologie finale. Le besoin peut inclure : - liens vers Montréal, Québec et/ou Toronto selon l’ingénierie; - fibre noire, longueurs d’onde, Ethernet/IP ou autres services standards selon les opérateurs; - 100/400G ou capacités supérieures lorsque justifiées par la demande; - chemins physiquement diversifiés lorsque faisables; - ententes de réparation nordique et pièces de rechange; - points d’interconnexion neutres ou multiples lorsqu’ils réduisent un point unique de défaillance. **Kristal définit le besoin de service; les transporteurs définissent et exploitent les technologies de transport.** ## 10. Mobilisation par étapes ### Phase A — Signal de demande Obtenir des échanges de besoins et, idéalement, 2 à 3 manifestations d’intérêt non contraignantes d’organisations admissibles. ### Phase B — Mobilisation canadienne Présenter la demande potentielle à Québec et Ottawa : volumes, contraintes, retombées physiques au Canada et besoins de coordination. ### Phase C — Télécom et ports Faire établir par les opérateurs les routes possibles, capacités, redondances, coûts indicatifs, modèles de réparation et possibilités de renforcement des infrastructures existantes. ### Phase D — Dossiers de sites Évaluer les sites selon la nouvelle doctrine : **génération neuve + consommation locale + port + fibre + faible sensibilité écologique relative**. ### Phase E — Pilote Construire un premier ensemble suffisamment petit pour apprendre, mais conçu dès le départ pour démontrer l’interface black box, la logistique maritime, la production locale et le transport de données. ### Phase F — Réplication Associer progressivement de nouveaux ensembles à des besoins locataires validés, sans créer une dépendance unique à un pays, un client, un port, un transporteur ou une technologie. ## 11. Conditions minimales avant d’utiliser le mot « coalition » publiquement Avant de présenter Kristal Farms comme coalition internationale établie, il devrait exister au minimum : - plusieurs contreparties admissibles provenant de juridictions distinctes; - des manifestations d’intérêt ou accords attribuables; - au moins un cadre de coopération canadien vérifiable; - une architecture de continuité montrant qu’aucun locataire ou lien télécom unique n’est indispensable; - une formulation juridique vérifiée des obligations et limites de chaque partie. Avant ces preuves, le terme approprié est **stratégie de coalition internationale** ou **portefeuille international recherché**. ## 12. Anti-promesses Le plan international n’établit pas encore : - douze locataires; - douze pays participants; - un MW engagé; - un barrage autorisé; - un port certifié pour les charges du projet; - une fibre compute-grade redondante vers chaque site; - une garantie gouvernementale; - une protection diplomatique ou militaire; - une réduction d’émissions dans un pays donné sans analyse de son système électrique; - une immunité juridique liée au caractère black box. La force du plan vient précisément du fait qu’il peut être **validé par étapes** avant de devenir une promesse. ================================================================================================ FILE: docs/10-core/strategy/VISION_KRISTAL_FARMS_FR.md AUTHORITY: reference ================================================================================================ # Kristal Farms — Vision énergie-calcul nordique **Statut :** narratif stratégique actuel. Ce document n'est ni une étude de faisabilité de site ni une promesse d'investissement. Kristal Farms propose une autre manière d'accéder aux ressources renouvelables nordiques éloignées : > **amener une charge de calcul flexible à l'énergie, consommer l'électricité localement et exporter la valeur numérique par fibre.** ## Pourquoi cette inversion compte Une ressource hydroélectrique éloignée n'est pas seulement une question d'énergie. Sa valeur pratique dépend aussi des routes, du transport électrique, des postes, de la logistique, de la fibre, de l'environnement et du contexte communautaire/de droits. Kristal Farms teste si le déplacement d'une charge numérique transportable peut réduire l'infrastructure nécessaire pour valoriser certaines ressources. ## Modèle physique Un nœud combine : - nouvelle production renouvelable; - interface communautaire protégée lorsque pertinente; - sites de calcul viabilisés; - connectivité fibre; - logistique maritime/terrestre; - récupération de chaleur et stockage lorsque justifiés. Le calcul peut être près de la production, près d'une communauté/port, ou réparti entre les deux. ## Modèle commercial Kristal Farms peut fournir les services d'infrastructure pendant que les locataires gardent la souveraineté sur leurs serveurs, systèmes d'exploitation, modèles, données, journaux et clés. L'hôte exploite les services physiques; le locataire contrôle la charge numérique. ## Location internationale Kristal Farms vise un marché international de locataires tout en restant sélectif sur ses contreparties. La juridiction, la propriété effective et le contrôle, l'exposition aux sanctions/contrôles commerciaux et la conduite responsable sont examinés avant la contractualisation. La politique actuelle du propriétaire exclut les contreparties établies ou contrôlées aux États-Unis des rôles de locataire, acheteur ferme principal (*anchor offtaker*) et opérateur-locataire. Le modèle normal est un **environnement chiffré sous contrôle du locataire** : l'hôte exploite les services physiques convenus et la télémétrie minimale nécessaire, tandis que le calcul privé reste aveugle au contenu pour les opérations courantes de l'hôte. ## Géographie et croissance La Côte-Nord est une géographie pratique de pilote/apprentissage. La thèse à plus long terme s'étend plus au nord au Québec et au Labrador, là où l'absence de routes et la distance d'export électrique peuvent créer le contraste structurel le plus fort. Les nœuds peuvent croître pad par pad. Des nœuds réussis peuvent éventuellement former un chapelet relié principalement par fibre et logistique maritime, avec des interconnexions électriques plus courtes lorsque cela améliore la résilience. ## Discipline communautaire et environnementale Les charges communautaires/critiques ont priorité sur le calcul flexible. Aucun site n'est présumé acceptable parce qu'il est éloigné. Hydrologie, écologie, droits/gouvernance, logistique, fibre, ingénierie et économie doivent être évalués explicitement. ## Capacité à long terme Si l'architecture fonctionne de manière répétée, l'expertise nordique en construction, exploitation, fibre, calcul en climat froid et énergie éloignée devient une capacité réutilisable. L'éducation, la recherche et de nouvelles infrastructures communautaires peuvent se développer autour de nœuds réussis, sans être des prérequis pour démontrer la première architecture énergie/calcul. ================================================================================================ FILE: docs/10-core/tenancy/MODELE_LOCATION_BLACK_BOX_FR.md AUTHORITY: reference ================================================================================================ # Kristal Farms — Environnement chiffré sous contrôle du locataire **Statut :** Modèle commercial/sécurité de référence actuel (C1) **Raccourci commercial :** location « black box » ## Modèle Kristal Farms peut louer des sites ou pads de calcul viabilisés tout en laissant au locataire la souveraineté numérique sur les systèmes placés derrière l'interface de service. Kristal Farms peut fournir : - alimentation électrique et comptage; - interface de refroidissement; - raccordement fibre/réseau; - sécurité physique et accès contrôlé; - accès logistique et maintenance; - télémétrie des services/infrastructures et mesure des SLA. Le locataire peut garder le contrôle de : - la configuration matérielle et des accélérateurs; - systèmes d'exploitation et orchestration; - modèles, jeux de données et applications; - identités, justificatifs d'accès et journaux internes; - clés cryptographiques et secrets. ## Engagement de confidentialité Le fonctionnement normal est **aveugle au contenu par conception** (*content-blind by design*). Kristal Farms n'exige pas d'accès de routine aux modèles privés, jeux de données, prompts, sorties ou trafic applicatif déchiffré pour louer l'infrastructure. L'admissibilité de la contrepartie est établie avant l'accès par une diligence raisonnable portant sur la juridiction, l'organisation, la propriété effective et le contrôle. Pendant la location, la conformité repose sur le contrat, les faits externes vérifiables et les procédures légales applicables, et non sur l'inspection cachée des charges de calcul chiffrées. ## Limites La location black box n'élimine pas : - le comptage; - la télémétrie des installations; - les contrôles de sécurité physique; - la protection du réseau partagé; - les obligations liées aux sanctions et contrôles à l'exportation; - les procédures légales valides; - la responsabilité du locataire pour ses propres systèmes. La formulation de référence est : > **Kristal Farms exploite l'infrastructure. Le locataire contrôle le calcul.** Voir : - `docs/00-control/INTERNATIONAL_TENANT_GOVERNANCE.md` - `docs/security/TENANT_CONFIDENTIALITY_BOUNDARY.md` - ADR-0021 et ADR-0022 ================================================================================================ FILE: docs/adr/0000-template.md AUTHORITY: reference ================================================================================================ # ADR-XXXX — Title **Status:** proposed **Date:** YYYY-MM-DD ## Context What problem or constraint requires a durable decision? ## Decision What is being decided? ## Alternatives considered ### Alternative A Pros / cons. ### Alternative B Pros / cons. ## Consequences ### Positive - ... ### Negative / trade-offs - ... ## Migration / rollout How is this introduced safely? ## Supersedes None. ================================================================================================ FILE: docs/adr/0001-maplibre-primary-renderer.md AUTHORITY: reference ================================================================================================ # ADR-0001 — MapLibre as primary Web renderer **Status:** accepted **Date:** 2026-08-30 ## Context Kristal Farms requires a visually strong public experience, professional interactive mapping, data-driven styling, vector tiles, terrain/globe capability, and freedom from a proprietary geospatial application backend. ## Decision Use **MapLibre GL JS** as the primary Web map renderer, with **deck.gl** for specialized GPU visualizations. ## Alternatives considered - Leaflet: simpler but less suitable for the desired modern WebGL experience and large tiled datasets. - OpenLayers: excellent Web GIS capabilities but less aligned with the desired visual/product experience. - ArcGIS: strong enterprise ecosystem but higher platform lock-in. - CesiumJS: excellent 3D globe/engineering capabilities but unnecessary as the primary renderer for the MVP. ## Consequences The Web team owns more custom product UX, which is desirable. Professional GIS capability is provided through PostGIS/QGIS/OGC interfaces rather than forcing the frontend to replicate desktop GIS. ================================================================================================ FILE: docs/adr/0002-postgis-source-of-truth.md AUTHORITY: reference ================================================================================================ # ADR-0002 — PostGIS as operational source of truth **Status:** accepted **Date:** 2026-08-30 ## Context The application and data system must scale beyond static GeoJSON, support GIS professionals, preserve relationships/provenance, and serve multiple interfaces. ## Decision Use PostgreSQL/PostGIS as the canonical operational database. ## Consequences GeoJSON, GeoParquet, MVT, PMTiles, COG, and GeoPackage are derived/interchange representations. The frontend must not become the canonical store. ================================================================================================ FILE: docs/adr/0003-evidence-separated-from-geometry.md AUTHORITY: reference ================================================================================================ # ADR-0003 — Evidence separated from geometry **Status:** accepted **Date:** 2026-08-30 ## Context Historical research contains valid records whose geometry is intentionally null. Forcing every claim into a map geometry would invent spatial precision and blur the difference between evidence and physical objects. ## Decision Model sources, evidence, observations, and evidence relations separately from places/assets/projects/corridors. ## Consequences The UI fetches evidence related to selected spatial subjects. Non-spatial evidence remains first-class data. Import pipelines must not fabricate coordinates merely for visualization. ================================================================================================ FILE: docs/adr/0004-open-geospatial-interoperability.md AUTHORITY: reference ================================================================================================ # ADR-0004 — Open geospatial interoperability **Status:** accepted **Date:** 2026-08-30 ## Context Kristal Farms data should be usable by professional GIS users and external systems rather than only by the Kristal Farms frontend. ## Decision Support PostGIS/QGIS workflows and standards-oriented geospatial APIs, initially OGC API features via pygeoapi where appropriate. ## Consequences The application retains an open data architecture. Domain-specific workflows may still use a separate FastAPI service rather than forcing them into OGC feature semantics. ================================================================================================ FILE: docs/adr/0005-immutable-public-data-releases.md AUTHORITY: reference ================================================================================================ # ADR-0005 — Immutable public data releases **Status:** accepted **Date:** 2026-08-30 ## Context The public Showcase must be fast, scalable, stable, auditable, and separable from private/live research data. ## Decision Publish stable public map datasets as versioned immutable artifacts, primarily PMTiles for vector data and COG for raster, distributed through object storage/CDN. ## Consequences Live PostGIS remains the research source of truth. Public releases require a formal publish/QA pipeline and can be rolled back by changing the active release reference. ================================================================================================ FILE: docs/adr/0006-ranking-disabled-by-policy.md AUTHORITY: reference ================================================================================================ # ADR-0006 — Ranking disabled by policy **Status:** accepted **Date:** 2026-08-30 ## Context Legacy site tiers exist in historical research, but current direction supersedes those rankings and requires unranked evidence screening. ## Decision Represent ranking permission as versioned policy. Current value is `ranking_allowed: false`. UI, API, analysis, and publication QA must enforce it. ## Consequences Legacy priorities remain available only as provenance. Future ranking requires an explicit methodology, governance decision, policy update, and superseding/related ADR. ================================================================================================ FILE: docs/adr/0007-cesium-deferred.md AUTHORITY: reference ================================================================================================ # ADR-0007 — Cesium deferred until engineering 3D data justifies it **Status:** accepted **Date:** 2026-08-30 ## Context A 3D globe can create visual impact, but the MVP's core information is 2D/2.5D geospatial research and evidence. MapLibre already supports terrain/globe-style presentation. ## Decision Do not use CesiumJS as the primary MVP renderer. Reconsider it for a dedicated engineering mode when LiDAR, photogrammetry, CAD/BIM, detailed terrain, or 3D infrastructure becomes material. ## Consequences The MVP remains simpler while preserving a future path to 3D Tiles/Cesium. Stable entity IDs and backend separation should make a later second renderer feasible. ================================================================================================ FILE: docs/adr/0008-canonical-entity-supertype.md AUTHORITY: reference ================================================================================================ # ADR-008 — Canonical entity supertype **Status:** Accepted ## Context The architecture already has a conceptual `ENTITY`, while evidence and observations need to reference places, assets, projects, corridors and future natural features with referential integrity. A polymorphic `(entity_type, entity_id)` pair cannot be protected by a normal foreign key. ## Decision Introduce `core.entity` as the canonical identity table. `core.place`, `core.asset`, `core.project`, `core.corridor` and `core.natural_feature` are subtype tables keyed by the same UUID. Evidence/observations/relations reference `core.entity(id)`. ## Consequence Canonical IDs remain stable across Web, QGIS, APIs, tiles and future 3D. Evidence does not need to know which subtype table holds geometry. ================================================================================================ FILE: docs/adr/0009-natural-features-for-hydrology.md AUTHORITY: reference ================================================================================================ # ADR-009 — Natural features for hydrology **Status:** Accepted ## Context The Hydro Resource Atlas contains rivers, watersheds and river reaches. They are not infrastructure `asset`, development `project`, or necessarily `corridor`. Forcing them into those types would blur factual geography and scenarios. ## Decision Add `core.natural_feature` with types `river`, `watershed`, `river_reach`, `lake`, `coastline`, `other`. Geometry may be `NULL`. A WSC hydrometric station is a `core.asset`; the river it monitors is a `core.natural_feature`; `core.entity_relation(relation_type='monitors')` links them. ## Consequence Historical hydro research can be migrated without turning station points into river geometry or projects. Future accepted WSC/GRHQ/Canada1Water geometry can attach to the natural feature without changing its canonical ID. ================================================================================================ FILE: docs/adr/0010-research-layers-are-ingest-artifacts-not-domain-model.md AUTHORITY: reference ================================================================================================ # ADR-010 — Research exchange layers are ingest artifacts, not the domain model **Status:** Accepted Research GeoJSON snapshots remain useful for reproducibility and exchange. They are no longer treated as the application source of truth. Examples: - Hydro-geometry analysis windows -> `system.ingestion_job.request_geometry`; - extraction jobs -> `system.ingestion_job`; - terrain/evidence gates -> `research.screening_dimension_state`; - WSC station points -> `core.asset`; - drainage area -> `research.observation`; - basin availability -> `research.evidence`; - river/watershed/reach -> `core.natural_feature` once canonicalized. Public GeoJSON/PMTiles are generated from `publish` views. ================================================================================================ FILE: docs/adr/0011-hydrology-series-are-versioned-source-objects.md AUTHORITY: reference ================================================================================================ # ADR-011 — Hydrology series are versioned source objects **Status:** Accepted ## Decision Daily/monthly hydrology is represented by `research.observation_series` plus observations, with source release, retrieval time and raw checksum. Series are not embedded in river metadata. ## Consequence The same station can safely retain observations from multiple releases or agencies without silent overwrite. ================================================================================================ FILE: docs/adr/0012-measurement-time-and-knowledge-time-are-distinct.md AUTHORITY: reference ================================================================================================ # ADR-012 — Measurement time and knowledge time are distinct **Status:** Accepted Hydrologic validity dates describe the measured phenomenon. Publication/retrieval/release metadata describe when Kristal Farms recorded it. Both must be preserved for reproducible releases and source corrections. ================================================================================================ FILE: docs/adr/0013-design-flow-is-never-an-automatic-hydat-derivation.md AUTHORITY: reference ================================================================================================ # ADR-013 — Design flow is never an automatic HYDAT derivation **Status:** Accepted HYDAT observations and research climatologies may inform later engineering, but `design_flow_m3s` requires an explicit engineering process and cannot be emitted by the automated observation pipeline. ================================================================================================ FILE: docs/adr/0014-integrated-atlas-uses-relations-not-synthetic-geometry.md AUTHORITY: reference ================================================================================================ # ADR-014 — Integrated atlas uses relations, not synthetic geometry ## Status Accepted ## Context The integrated atlas must connect rivers, communities, ports, telecom, energy and logistics even when exact facility/route geometry is absent. ## Decision Use canonical entity relations and evidence/observations to create context. Do **not** create a map line or point solely to satisfy the frontend. Community points imported from legacy My Maps remain explicitly approximate centroids. Regional marine systems, ferry/fibre corridors and external projects may have `geometry = NULL`. ## Consequences The Explorer can show badges and Evidence Panel context without inventing spatial precision. Map rendering becomes a projection of what has real geometry, not a requirement imposed on all knowledge. ================================================================================================ FILE: docs/adr/0015-legacy-screening-is-provenance-not-governance.md AUTHORITY: reference ================================================================================================ # ADR-015 — Legacy screening is provenance, not current governance ## Status Accepted Legacy Tier 1/2/3/4 and old no-go language are preserved so their origin can be inspected, but current `system.governance_state` remains `screening_mode=unranked` and `ranking_allowed=false`. Public publish views omit legacy tiers by default. Legacy environmental concerns are `unverified` historical context until replaced or supported by current authoritative evidence. ================================================================================================ FILE: docs/adr/0016-public-release-is-immutable-snapshot.md AUTHORITY: reference ================================================================================================ # ADR-016 — Public atlas releases are immutable snapshots ## Status Accepted The Showcase consumes an immutable release snapshot. Live research can continue to change independently. Release metadata records the dataset version, screening mode and `ranking_allowed=false`. This prevents a public story from silently changing as research fixtures evolve. ================================================================================================ FILE: docs/adr/0017-economic-benchmarks-are-not-site-costs.md AUTHORITY: reference ================================================================================================ # ADR-017 — Economic benchmarks are not site costs The economic benchmark method registers completed-project ratios and public funding-intensity ratios as **research benchmarks**. `usable_as_site_estimate=false` is mandatory. A benchmark becomes a scenario input only through an explicit `scenario.assumption` with evidence lineage. No benchmark may silently populate a candidate-site CAPEX. ================================================================================================ FILE: docs/adr/0018-break-even-frontier-before-bankable-economics.md AUTHORITY: reference ================================================================================================ # ADR-018 — Use a break-even frontier before bankable economics When Kristal Farms-specific local electrical works, serviced pads, port upgrades, fibre landing/terminal, local access and storage are not priced, the economic comparison does not set them to zero and call the difference savings. Instead it computes the **remaining unpriced Kristal Farms budget** before parity with evidence-backed reference envelopes for conventional export infrastructure. Project NPV, IRR and bankability remain blocked until a site dossier supplies complete engineering, hydrology, cost, revenue, financing, tax and regulatory inputs. ================================================================================================ FILE: docs/adr/0019-common-generation-and-tenant-hardware-not-avoided-costs.md AUTHORITY: reference ================================================================================================ # ADR-019 — Common generation and tenant hardware are not avoided costs The architecture comparison holds the new remote generation resource conceptually common between the two monetization architectures. Generation CAPEX is therefore excluded from the differential frontier unless a later site study demonstrates that the generation design itself changes. Likewise, tenant compute hardware is not treated as an avoided Kristal Farms cost: the commercial model can use tenant-owned hardware, and equivalent compute hardware would not be a transmission-project cost in the alternative architecture. ================================================================================================ FILE: docs/adr/0020-one-monorepo-three-logical-systems.md AUTHORITY: reference ================================================================================================ # ADR-020 — One monorepo with three logical systems ## Status Accepted ## Context Kristal Farms contains exploratory research, reproducible geospatial/data pipelines and a Web product. As the Observatory implementation began, hydrology research concerns and frontend display concerns became easy to treat as one implementation surface even though they have different lifecycle, quality and dependency rules. The project needs a boundary that keeps research fast, data publication governed and product code stable without introducing the operational overhead of multiple repositories prematurely. ## Decision Keep one canonical Git repository and divide it into three logical systems: 1. **Knowledge / research** — `research/` plus controlled source/research documentation. Exploratory and non-runtime. 2. **Data platform / contract** — `pipelines/`, `database/`, `contracts/`, `packages/` and `data/`. Reproducible ingest, validation, canonicalization and publication. 3. **Product** — `apps/` and `services/`. Showcase, Explorer/Observatory and Scenario Studio runtime surfaces. Dependencies flow toward governed publication: ```text research -> data platform -> product ``` Product runtime code must not import or execute `research/` or `pipelines/`. File-based development consumers may read immutable `data/publish/...` artifacts and stable package/contracts. Production continues to target governed APIs/tiles backed by PostGIS. ## Consequences ### Positive - research can remain exploratory without weakening application semantics; - Observatory can evolve independently from hydrology methodology; - data publication becomes the explicit contract boundary; - cross-cutting changes can still be reviewed atomically in one pull request; - repository splitting remains possible later because dependencies are already directional. ### Costs - some concepts appear in both research documentation and product documentation and must be linked rather than conflated; - promotion from research to product requires deliberate pipeline/contract work; - automated boundary tests are needed to prevent convenient direct imports. ## Alternatives considered ### Three repositories Rejected for now. It would require independent versioning, coordinated releases and cross-repository CI before those costs are justified. ### Two repositories (research/data and product) Deferred. This can become appropriate when the Web application has an independent deployment/release team or when public data contracts are versioned as an external dependency. ### One repository without enforced boundaries Rejected. Folder proximity must not allow exploratory research to become an implicit application dependency. ================================================================================================ FILE: docs/adr/0021-content-blind-tenant-environments.md AUTHORITY: reference ================================================================================================ # ADR-0021 — Tenant environments are content-blind by design **Status:** accepted **Date:** 2026-08-31 ## Context Kristal Farms may lease serviced compute sites/pads while tenants retain control of hardware/software, models, data and keys. The project also intends to select commercial counterparties according to jurisdictional and responsible-business criteria. A design that attempted to enforce commercial values through routine inspection of encrypted tenant content would conflict with the tenant-sovereignty proposition, create additional security/privacy risk and make the stated black-box model misleading. ## Decision Normal Kristal Farms operations will be **content-blind by design**. Kristal Farms will operate shared physical services and minimum necessary service telemetry without requiring routine access to tenant application content, private models/datasets or decryption keys. No default operator key escrow, covert content monitoring or standing decryption backdoor will be required as a condition of tenancy. Counterparty policy is enforced through admission/due diligence, contract, externally verifiable information and lawful process rather than hidden workload inspection. ## Consequences - Tenant confidentiality becomes a core commercial/security boundary. - Kristal Farms cannot claim to verify private encrypted workload content. - Infrastructure telemetry remains available for power, cooling, physical security, networking, billing and SLA operation. - Managed services that require logical access must be separately contracted and explicitly scoped. - Legal requests are handled according to what Kristal Farms actually possesses or controls; the architecture should not create unnecessary standing access. ================================================================================================ FILE: docs/adr/0022-counterparty-screening-before-tenancy.md AUTHORITY: reference ================================================================================================ # ADR-0022 — Responsible-tenancy controls are counterparty-based, not content-inspection-based **Status:** accepted **Date:** 2026-08-31 ## Context Kristal Farms intends to operate internationally while preserving the right to decline commercial relationships that do not meet project values, governance or risk criteria. Tenant environments are also intended to remain encrypted and content-blind to routine operator access. ## Decision Responsible international tenancy will be governed primarily through: 1. jurisdictional eligibility; 2. legal-counterparty identification; 3. beneficial-ownership/effective-control review; 4. sanctions/export-control screening; 5. proportionate responsible-business due diligence; 6. contractual representations, covenants and termination rights; 7. periodic re-review based on external evidence and control changes. The project will use categorical states (`ELIGIBLE`, `ENHANCED_DUE_DILIGENCE`, `SUSPENDED`, `INELIGIBLE`) rather than a numerical ethics score. Explicit country-level exclusions and holds are governed by `contracts/policy/jurisdiction-eligibility.yaml`. Downstream resellers/subtenants inherit the same eligibility boundary. These counterparty rules do not themselves create a technology-origin embargo. ## Consequences - Screening records must identify the specific legal entity, control structure, evidence and date. - Country-level indicators are inputs, not automatic determinations about organizations or people. - Reseller/subtenant structures require pass-through eligibility controls. - Policy enforcement must not depend on defeating tenant encryption. - A future change to the United States exclusion requires an explicit project-control decision. ================================================================================================ FILE: docs/adr/0023-offline-satellite-snapshots.md AUTHORITY: reference ================================================================================================ # ADR 0023 — Satellite imagery is a static local snapshot - Status: Accepted - Date: 2026-08-31 ## Context The Observatory benefits from photographic context at high zoom, but a third-party satellite tile API introduces changing imagery, runtime network dependencies, provider keys, cost exposure and reproducibility problems. ## Decision Satellite imagery used by the product is manually acquired and published as an immutable local snapshot. Runtime flow: ```text reviewed source GeoTIFF ↓ manual promotion pipelines/imagery/build_local_satellite.py ↓ data/publish/imagery/current/imagery_manifest.json ↓ deployment copy apps/web/public/imagery//{z}/{x}/{y}.png ↓ MapLibre raster layer ``` The product must not contain a MapTiler/Esri/Sentinel-Hub satellite API key and must not automatically refresh satellite imagery. Photographic context is not evidence. Evidence and geometry provenance remain separate. ## Consequences - A release is visually reproducible. - Imagery updates require an explicit reviewed promotion. - Repository/deployment size can be large. - Source licensing and attribution must be reviewed before publishing tiles. - The contextual vector basemap remains a separate concern and may still be externally hosted unless separately snapshotted. ================================================================================================ FILE: docs/adr/README.md AUTHORITY: reference ================================================================================================ # Architecture Decision Records ADRs preserve the reasoning behind durable decisions. ## Statuses ```text proposed accepted superseded deprecated rejected ``` ## Process 1. Copy `0000-template.md`. 2. Assign next number. 3. Describe context and alternatives. 4. Record consequences, including operational/data consequences. 5. Link superseded ADRs rather than rewriting their history. ## Initial ADRs - [0001 — MapLibre as primary Web renderer](0001-maplibre-primary-renderer.md) - [0002 — PostGIS as source of truth](0002-postgis-source-of-truth.md) - [0003 — Evidence separated from geometry](0003-evidence-separated-from-geometry.md) - [0004 — Open geospatial interoperability](0004-open-geospatial-interoperability.md) - [0005 — Immutable public data releases](0005-immutable-public-data-releases.md) - [0006 — Ranking disabled by policy](0006-ranking-disabled-by-policy.md) - [0007 — Cesium deferred](0007-cesium-deferred.md) - [0020 — One monorepo with three logical systems](0020-one-monorepo-three-logical-systems.md) - [0021 — Tenant environments are content-blind by design](0021-content-blind-tenant-environments.md) - [0022 — Responsible-tenancy controls are counterparty-based](0022-counterparty-screening-before-tenancy.md) ================================================================================================ FILE: docs/api/authentication.md AUTHORITY: reference ================================================================================================ # Authentication and authorization ## Public mode Showcase and explicitly public Explorer collections require no sign-in. ## Authenticated mode Use OIDC-compatible authentication for partner/internal access. ## Authorization Authorization decisions are server-side and may be based on: - role; - organization/tenant where later required; - collection classification; - action; - scenario ownership/sharing state. ## Tokens Do not place long-lived tokens in URLs or client storage when avoidable. API and tile services must validate access independently for non-public resources. ================================================================================================ FILE: docs/api/errors.md AUTHORITY: reference ================================================================================================ # API errors ## Shape Use a consistent structured error response, for example: ```json { "error": { "code": "SCENARIO_INVALID_ASSUMPTION", "message": "compute_max_mw must be non-negative", "details": {"field": "compute_max_mw"}, "request_id": "..." } } ``` ## Principles - stable machine-readable error codes; - human-readable messages; - field-level details for validation; - no stack traces or secrets in public responses; - request/trace IDs for support; - 404 must not leak existence of restricted resources when policy requires concealment. ================================================================================================ FILE: docs/api/kristal-farms-api.md AUTHORITY: reference ================================================================================================ # Kristal Farms API ## Responsibilities - entity + evidence aggregation; - search across entity classes; - scenario create/read/update/archive; - scenario evaluation; - scenario comparison; - authenticated annotations/workflows; - catalog/policy retrieval when not fully static. ## Candidate endpoints ```text GET /v1/catalog GET /v1/policy GET /v1/search?q= GET /v1/entities/{entity_type}/{id} GET /v1/entities/{entity_type}/{id}/evidence POST /v1/scenarios GET /v1/scenarios/{id} PATCH /v1/scenarios/{id} POST /v1/scenarios/{id}/evaluate POST /v1/scenarios/compare ``` ## Versioning Use a path or media-type version strategy deliberately. The starter contract uses `/v1`. ## Evidence aggregation Entity detail responses may aggregate linked evidence for convenience but should retain evidence/source IDs so clients can trace the underlying records. ## Scenario writes Scenario writes must never mutate canonical research observations. ================================================================================================ FILE: docs/api/ogc-api.md AUTHORITY: reference ================================================================================================ # OGC API ## Purpose Expose publishable geospatial collections in a standards-oriented form so external GIS/software can use Kristal Farms data without depending on the Web application's internal contracts. ## Initial collections Potential collections include: ```text communities energy_assets reference_projects corridors candidate_sites ``` Only collections with appropriate geometry and publication classification should be exposed. ## Evidence Evidence itself may be available through domain APIs or tabular endpoints; it should not be forced into a spatial collection when it has no geometry. ## Filters Where supported, expose attribute, bbox, and temporal filtering. Keep authorization rules consistent with publication policy. ================================================================================================ FILE: docs/api/overview.md AUTHORITY: reference ================================================================================================ # API overview Kristal Farms uses different interfaces for different jobs. | Interface | Purpose | |---|---| | FastAPI domain API | Kristal Farms-specific workflows and scenarios | | OGC API | Standards-based geospatial feature access | | Martin MVT | High-performance map rendering | | PMTiles/COG | Immutable public release delivery | | PostGIS | Controlled professional/QGIS and service access | ## Rule Do not force all geospatial access through proprietary endpoints when a standard collection interface is appropriate. Conversely, do not distort domain workflows to fit a generic OGC feature API. ## Contracts A starter OpenAPI contract is provided at `contracts/api/kristal-farms-api.openapi.yaml`. ================================================================================================ FILE: docs/api/tiles.md AUTHORITY: reference ================================================================================================ # Tile API ## Live tiles Martin serves MVT from curated PostGIS publish views. ## Static public tiles Stable public layers should normally be bundled into PMTiles for CDN delivery. ## Tile properties Tile payloads should include only fields required for rendering, filtering, selection, and lightweight tooltips. Do not embed full source documents or large evidence payloads in vector tiles. ## Feature identity Every selectable feature in a tile must carry a stable entity identifier that can be used to fetch full detail/evidence from an API. ## Generalization Use zoom-dependent geometry simplification and attribute reduction where appropriate. Preserve canonical geometry in PostGIS. ================================================================================================ FILE: docs/architecture/backend.md AUTHORITY: reference ================================================================================================ # Backend architecture ## Service responsibilities ### Kristal Farms API — FastAPI Owns domain-specific operations that do not map naturally to generic geospatial standards: - scenario CRUD/evaluation; - entity evidence aggregation; - cross-domain search; - comparison operations; - authenticated annotations/workflows; - model execution. ### OGC API — pygeoapi Provides standards-based access to publishable geospatial collections. ### Tile service — Martin Provides MVT tiles from PostGIS and/or prepared tile sources. ## Deployment principle These are logical services. During early development they may share infrastructure or deployment units. Separate them operationally only when scaling, security, or ownership requires it. ## API boundary No browser should receive direct database credentials. QGIS access is a separate professional workflow with controlled database roles. ## Business rules Domain rules belong in a testable model/service layer. Route handlers should validate input, authorize operations, call domain functions, and serialize results. ================================================================================================ FILE: docs/architecture/data-architecture.md AUTHORITY: reference ================================================================================================ # Data architecture ## PostgreSQL schemas ```text raw Source-faithful imports staging Normalization / ETL workspace core Canonical geographic and infrastructure entities research Evidence, sources, observations, research state scenario User/model hypotheses and results publish Stable views for APIs, tiles, and exports system Catalog, policies, versions, operational metadata ``` ## Why PostGIS PostGIS provides a durable professional geospatial source of truth that can serve the Web application, Python workflows, QGIS, standards-based APIs, and tile generation without converting every workflow into frontend-specific JSON. ## Derived formats | Need | Representation | |---|---| | Small interchange | GeoJSON | | Large analytical files | GeoParquet | | Web vector rendering | MVT | | Immutable public tiles | PMTiles | | Raster | Cloud Optimized GeoTIFF | | Portable GIS exchange | GeoPackage | | Future large 3D | 3D Tiles | Derived artifacts must record their source dataset version and publication timestamp. ================================================================================================ FILE: docs/architecture/deployment.md AUTHORITY: reference ================================================================================================ # Deployment architecture ## Environments - `development` - `staging` - `production` ## Public read path For stable public layers, prefer immutable release artifacts on object storage/CDN: ```mermaid flowchart LR PG[(PostGIS)] --> Publish[Publish pipeline] Publish --> PM[PMTiles / COG] PM --> CDN[Object storage + CDN] CDN --> Browser[Public browser] ``` This reduces public dependency on live database availability and supports high traffic. ## Live professional path ```mermaid flowchart LR Browser --> API[FastAPI / OGC API / Martin] API --> PG[(PostGIS)] ``` ## Deployment units Recommended initial container/service set: ```text web kristal-farms-api pygeoapi martin postgres-postgis ``` Add queue/workers only when long-running jobs justify them. ## Infrastructure portability Use standard containers, object storage, PostgreSQL, OIDC, and CDN primitives. Cloud-specific managed services are allowed, but the application should not require a proprietary geospatial backend. ================================================================================================ FILE: docs/architecture/frontend.md AUTHORITY: reference ================================================================================================ # Frontend architecture ## Stack - React - TypeScript - Next.js - MapLibre GL JS - deck.gl ## Major modules ```text AppShell ├── Showcase │ ├── StoryDirector │ ├── CameraDirector │ ├── NarrativePanel │ └── ShowcaseMap ├── Explorer │ ├── MapWorkspace │ ├── LayerCatalog │ ├── Legend │ ├── FilterPanel │ ├── Timeline │ ├── EvidencePanel │ └── DataDrawer └── ScenarioStudio ├── ScenarioEditor ├── SystemDiagram ├── Assumptions ├── Results └── Compare ``` ## State categories ### URL state Must be serializable for shareable views: - map camera; - selected entity; - mode; - visible layers; - selected timeline period; - filters; - comparison IDs where safe. ### Server state Fetched from APIs or tile metadata. Use a dedicated query/cache layer rather than duplicating remote records into global UI stores. ### Local UI state Panel width, temporary hover state, local display preferences. ## Layer rendering Generic map layers must be instantiated from the layer catalog. Custom React code is justified for special interactions such as scenario editing, animated system flows, or bespoke 3D engineering visualization. ## Type safety Frontend types should be generated or shared from machine-readable contracts wherever practical. Avoid hand-maintained duplicate enums between frontend and backend. ## Map observatory interaction Explorer and Showcase share the interaction model defined in [Map observatory interaction](../frontend/map-observatory-interaction.md). Ordinary geographic features remain MapLibre-rendered and catalog-driven. React owns hover cards, the persistent Entity Inspector, relation UI, comparison surfaces, and other non-geographic investigation controls. Transient hover state remains local UI state; selected entity and safe comparison IDs participate in shareable URL state. ================================================================================================ FILE: docs/architecture/information-architecture.md AUTHORITY: reference ================================================================================================ # Information architecture Kristal Farms uses two complementary information axes. They are intentionally separated so a reader can distinguish **project/domain authority** from **software/data-platform implementation** without guessing from filenames. ## Project and domain axis | Area | Purpose | Authority tendency | |---|---|---| | `docs/00-control/` | Current project state, principles, decisions and release interpretation | C0 | | `docs/10-core/` | Physical/commercial **project reference architecture**, deployment and tenancy | C1 | | `docs/30-site-screening/` | Site/corridor screening methods and technical research | C4 | | `docs/40-economics/` | Economic research and benchmark methods | C4 | | `docs/50-research/` | Active domain/commercial/governance research | C4 | | `docs/70-long-horizon/` | Optional long-horizon concepts | C4L | ## Software and data-platform axis | Area | Purpose | |---|---| | `docs/architecture/` | Software/data-platform architecture and system boundaries | | `docs/data/` | Application data model, evidence, provenance, hydrology/economic data contracts and publishing semantics | | `docs/product/` | Product surfaces and product-facing data contracts | | `docs/frontend/` | Interaction, cartography, accessibility and UI implementation rules | | `docs/api/` | Service/API contracts and behavior | | `docs/scenarios/` | Scenario-engine contracts and economic scenario method | | `docs/operations/`, `docs/security/`, `docs/testing/` | Operational controls | | `docs/adr/` | Durable technical decision history | The former `docs/60-application-data/` bucket was removed because it mixed this second axis back into the numbered project/domain axis. Its documents now live under `data/`, `product/` or `scenarios/` according to responsibility. ## Repository information flow ```text sources / research ↓ promotion + validation pipelines / database / contracts / packages ↓ governed publish/API/tiles apps / services ``` `archive/` is historical provenance, not active authority. It remains versioned but is excluded from default local search/index behavior through the root `.ignore`; historical work should opt into `archive/` explicitly. ## Observatory workspace model The top-level Observatory remains a flat six-workspace cockpit for speed, but the workspaces have a stable conceptual grouping: - **Explore** — Northern Atlas, Villages, Corridors. - **Evaluate** — Economics. - **Govern** — Evidence, International Portfolio. The grouping describes user intent; URLs remain stable (`section=atlas|villages|corridors|economics|evidence|international`). The International Portfolio may currently contain twelve planning slots, but the count is state, not navigation taxonomy. ================================================================================================ FILE: docs/architecture/observability.md AUTHORITY: reference ================================================================================================ # Observability Track enough information to distinguish application, data, and infrastructure failures. ## Application telemetry - API request latency/error rate; - tile request latency/error rate; - frontend exceptions; - failed scenario evaluations; - authentication/authorization failures. ## Data pipeline telemetry - import start/end; - source version/hash; - row/feature counts; - validation failures; - publish artifact hashes; - release version; - public/private leakage checks. ## Database telemetry - connection saturation; - slow queries; - storage growth; - replication/backup health where applicable. ## Privacy Public product analytics must not collect sensitive research contents or private scenario parameters unless expressly required and disclosed. ================================================================================================ FILE: docs/architecture/performance.md AUTHORITY: reference ================================================================================================ # Performance ## Principles - Avoid sending large raw GeoJSON collections to browsers. - Use MVT/PMTiles for large vector layers. - Use COG for raster. - Generalize geometry by zoom. - Load specialized analysis layers only when enabled. - Cache immutable release artifacts aggressively. - Keep selection/detail requests separate from map rendering payloads. ## Suggested budgets These are engineering targets, not hard guarantees: - initial public shell should become interactive quickly on normal broadband; - map interaction should remain visually smooth during pan/zoom; - layer toggles should not require full application reload; - detail/evidence panels should use indexed queries and paginated evidence where needed; - public releases should be CDN-cacheable and independent of live DB latency for core visuals. ## Database Use spatial indexes for geometry filters and conventional indexes for commonly filtered metadata. Validate query plans for large publish views before exposing them as live endpoints. ================================================================================================ FILE: docs/architecture/repository-structure.md AUTHORITY: reference ================================================================================================ # Repository structure Kristal Farms uses **one canonical monorepo with three logical systems**. The GitHub Wiki is the only intentionally separate repository. ```text kristal-farms/ ├── research/ # Knowledge: exploratory/non-runtime work │ ├── hydrology/ │ ├── energy/ │ ├── communities/ │ └── experiments/ ├── pipelines/ # Data platform: reproducible ingest/transform/QA/publish │ ├── ingest/ │ ├── transform/ │ ├── validate/ │ ├── economics/ │ └── publish/ ├── database/ # Data platform: PostGIS operational source of truth ├── contracts/ # Data platform: machine-readable boundaries ├── packages/ # Stable schemas/catalog/map-style/shared packages ├── data/ │ ├── raw/ │ ├── processed/ │ ├── fixtures/ │ ├── publish/ │ ├── catalog/ │ └── examples/ ├── apps/ │ └── web/ # Product: Showcase / Observatory / Scenario Studio ├── services/ │ ├── kristal-farms-api/ │ ├── ogc-api/ │ └── tiles/ ├── docs/ ├── tools/ # Specialist local/developer utilities ├── sources/ ├── tests/ ├── infra/ ├── archive/ └── .github/ ``` ## Logical system 1 — Knowledge / research - `research/`: active exploratory code, notebooks, candidate analysis and methodological experiments. - `sources/`: controlled source material and owner-direction records. - `docs/00-control`, `docs/10-core`, `docs/30-site-screening`, `docs/40-economics`, `docs/50-research` and `docs/70-long-horizon`: project/domain documentation organized by authority and maturity. - `archive/`: superseded/historical research that must not control active state. Research can be incomplete. It is not a runtime dependency and it is not publishable merely because it is committed. ## Logical system 2 — Data platform / contract - `database/`: canonical operational PostGIS schemas and views. - `pipelines/`: reproducible ingest, transform, validation, economics and publish logic. - `contracts/`: machine-readable API, schema, release, story, layer and policy contracts. - `packages/`: stable schemas, catalog, cartographic semantics and shared implementation packages. - `data/raw/`: source-faithful/controlled input artifacts. - `data/processed/current/`: current derived research outputs with provenance. - `data/fixtures/current/`: loadable canonical development/application fixtures. - `data/publish/current/`: current immutable public-release artifacts. This system turns research into reproducible, governed data. ## Logical system 3 — Product - `apps/web/`: Showcase, Explorer/Observatory and Scenario Studio implementation. - `services/`: domain API, OGC API and tile delivery. - `docs/architecture`, `docs/data`, `docs/product`, `docs/frontend`, `docs/api`, `docs/scenarios`, etc.: software/data-platform implementation documentation organized by responsibility. Product code consumes governed APIs/tiles, stable packages/contracts or immutable publish artifacts. It must not import or execute `research/` or `pipelines/`. Specialist local utilities live under `tools/`; only the canonical rebuild and quick-start launchers remain at repository root. ## Direction of dependency ```text research ↓ promote/review data platform + contracts ↓ publish/API/tiles product ``` See [Information architecture](information-architecture.md), [Workspace boundaries](workspace-boundaries.md) and [ADR-020](../adr/0020-one-monorepo-three-logical-systems.md). ## Separate wiki `Kristal_Farms.wiki` is a separate Git repository for the public/explanatory GitHub Wiki. It is not the technical source of truth. ================================================================================================ FILE: docs/architecture/security.md AUTHORITY: reference ================================================================================================ # Security architecture ## Data classifications ```text PUBLIC PARTNER INTERNAL RESTRICTED ``` Every dataset/layer must have a classification. ## Publication boundary The public artifact generator must filter restricted content before writing PMTiles, GeoJSON, GeoParquet, COG, or metadata bundles. Frontend hiding is not access control. ## Authentication Use standards-based OIDC for authenticated modes. Avoid building a custom identity system. ## Authorization Permissions may apply to: - collections; - attributes; - downloads; - scenarios; - annotations; - write operations; - administrative configuration. ## Database roles At minimum separate: - migration/admin role; - service read/write role; - tile read role; - OGC read role; - analyst/QGIS roles; - publication pipeline role. ## Secrets No secrets in Git. Environment-specific credentials belong in a secret manager or protected CI environment. ## Sensitive spatial data Where community, cultural, environmental, infrastructure, or partner data requires reduced spatial precision, create an explicitly generalized/redacted publish representation rather than simply removing fields in the UI. ## Tenant-controlled encrypted environments Tenant operation is content-blind by design unless a separately contracted managed service explicitly changes the logical-access boundary. Kristal Farms should not require routine application-content access, private model/dataset inspection, operator key escrow or a standing decryption backdoor. The provider may retain purpose-limited telemetry needed for power, cooling, physical security, shared network availability/security, metering and SLA operation. See `../security/TENANT_CONFIDENTIALITY_BOUNDARY.md`. ## Counterparty security boundary Responsible-tenancy controls are performed through legal-counterparty identification, beneficial ownership/effective control, sanctions/trade screening, contract and periodic re-review. They are not implemented by defeating tenant encryption. ================================================================================================ FILE: docs/architecture/technology-stack.md AUTHORITY: reference ================================================================================================ # Technology stack ## Selected foundation | Layer | Technology | Role | |---|---|---| | Web application | React + TypeScript + Next.js | Product UI and routing | | Primary map | MapLibre GL JS | Cartographic renderer | | Advanced visualization | deck.gl | GPU analytical/flow layers | | Canonical database | PostgreSQL + PostGIS | Geospatial source of truth | | Domain API | FastAPI | Kristal Farms-specific operations and models | | Standards API | pygeoapi | OGC-oriented geospatial access | | Tile serving | Martin | MVT delivery from PostGIS/tile archives | | Public vector release | PMTiles | Immutable CDN-friendly vector archive | | Raster release | COG | Cloud-friendly raster distribution | | Professional desktop GIS | QGIS | Analysis/editing for authorized users | | Analytical file interchange | GeoParquet | Large columnar geospatial datasets | | Future engineering 3D | CesiumJS + 3D Tiles | Deferred engineering/terrain mode | ## Version policy Application dependencies should be pinned by package/lock files and updated deliberately. Architecture documentation should generally describe capabilities and compatibility constraints rather than becoming a second dependency lock file. ## Re-evaluation triggers A technology decision should be revisited when a measurable requirement changes: dataset size, rendering type, data governance, offline use, 3D engineering data, cloud constraints, or external partner integration. ================================================================================================ FILE: docs/data/application-data-model.md AUTHORITY: reference ================================================================================================ # Kristal Farms application data model The application uses a canonical relational/geospatial model rather than treating each research file as a permanent map layer. ## Core refinements 1. `core.entity` provides a shared canonical identity. 2. `core.natural_feature` represents rivers, watersheds and research reaches. 3. Source, evidence and observation records are normalized and linked explicitly. 4. Screening dimensions are evidence/status/open-question records, not numeric scores. 5. Extraction windows and processing jobs live under `system.ingestion_job` rather than masquerading as domain geography. 6. Public Web layers are derived from `publish` views and immutable releases. The current fixture contains 24 river natural features and 24 WSC hydrometric-station assets. Only the official station positions have physical geometry in the current canonical fixture; river and watershed geometry remains null until authoritative geometry is ingested and accepted. ## Mine-reuse research boundary Mine-reuse records remain exploratory until a source-backed inventory and stable semantics justify promotion. During research, mines should normally use existing `asset`/`project` entity patterns plus explicit metadata for lifecycle, mine method, underground condition, pit/reservoir geometry, restoration status and enabling infrastructure. Do not add `available_compute_mw`, pumped-storage capacity or security claims by inference. If mine-reuse fields become routinely queried or published, promote them through migrations/contracts/tests rather than leaving core semantics only in JSONB. ================================================================================================ FILE: docs/data/data-quality.md AUTHORITY: reference ================================================================================================ # Data quality ## QA levels ### Structural - schema validity; - required fields; - valid IDs; - valid geometry/SRID; - unit conformity; - date parsing; - relation integrity. ### Provenance - referenced source IDs exist; - evidence is linked to a subject where appropriate; - source dates/retrieval dates are captured where available; - no orphan evidence unless intentionally standalone. ### Domain - planning margin cannot populate compute-hosting fields; - external references cannot silently become Kristal Farms candidates; - ranking fields are blocked while ranking is disabled; - scenario outputs cannot populate observed-data tables. ### Publication - restricted data absent from public artifacts; - release metadata/version present; - artifact hashes recorded; - expected row/feature counts checked. ## CI behavior Critical QA failures must block publication. Warnings may be allowed only when documented and visible in the release report. ## Current fixture baseline The active fixture under `data/fixtures/current/` is cumulative and validated by the repository test suite. Historical migration counts are preserved in `archive/research-snapshots/` and are not product acceptance criteria. ================================================================================================ FILE: docs/data/DATA_VALIDATION_PASS_2026-09-01.md AUTHORITY: reference ================================================================================================ # Data validation pass — 2026-09-01 ## Scope This pass focuses on governed/current data and factual public surfaces in the Kristal Farms snapshot, with special attention to AI-generated claims that could be hallucinated, over-precise, stale, or insufficiently sourced. Included: - canonical research provenance fixtures (`research_source`, `research_evidence`, evidence/source links, observations, economic benchmarks); - current public evidence, community infrastructure, grid-reach and economic benchmark artifacts; - the International Portfolio research portfolio and its public interface; - current legal/reference context attached to the jurisdiction policy. Not certified by this pass: - legacy/raw/internal research archives that are not promoted as canonical evidence; - commercial willingness, future delivery, or actual available capacity of third parties; - legal eligibility of any transaction or counterparty; - engineering-grade geometry or site-specific cost estimates. ## Executive findings ### 1. Canonical provenance graph: structurally sound The canonical fixture layer had no broken evidence/source references in the reviewed current snapshot: - 46 research sources after this pass; - 127 evidence records; - 274 evidence↔source links after this pass; - 100 observations, all with a valid `source_evidence_id`; - 10 economic benchmarks, all with a valid `source_evidence_id`. The existing evidence/observation/scenario separation is a strong anti-hallucination control because scenarios are not silently promoted to observations. ### 2. Public economic provenance: broken chain fixed Before this pass, all 10 public economic benchmarks exposed a `source_evidence_id`, but the corresponding economic evidence records were omitted from `evidence_records_public.json`. The IDs therefore did not resolve in the public evidence ledger. Fix: - `build_observatory_public.py` now includes evidence referenced by `economic_benchmarks_public.json`; - the public evidence ledger increased from 115 to 125 records; - all 10 public benchmark evidence IDs now resolve to public evidence and source records. ### 3. Northern Labrador road benchmark: numeric correction The source study states a ROM construction estimate of approximately **CAD 2,089,790,000** for 809 km of gravel road and **CAD 602,393,000** for 809 km of paving, with ROM accuracy of ±50% and costs based on 2023 pricing. The previous fixture metadata rounded these to CAD 2.1B and CAD 600M, and the published per-km benchmarks were calculated from those rounded amounts. Source: [Newfoundland and Labrador House of Assembly / Allnorth — Final Draft Project Summary Report, Pre-Feasibility Study for a Road into Northern Labrador](https://www.assembly.nl.ca/business/electronicdocuments/Allnorth-ProjectSummaryReport-RoadToTheNorth.pdf) Corrected values: | Benchmark | Previous | Corrected | | --- | ---: | ---: | | Gravel-road ROM / km | 2,595,797.280593 CAD/km | **2,583,176.761434 CAD/km** | | Construction + paving / km | 3,337,453.646477 CAD/km | **3,327,791.100124 CAD/km** | | Annual maintenance / km-year | 16,069.221261 CAD/km-year | unchanged | A source-arithmetic validator now recomputes all 10 governed economic benchmarks from their source metadata. ### 4. International Portfolio (12 planning slots): missing attribution fixed The International Portfolio public artifact previously published factual rationales without any visible source references. This was the largest hallucination risk on an otherwise governed public research surface. Fixes: - all 12 candidates now have attributable primary sources; - 18 candidate source references were added; - the public JSON carries those sources; - the web inspector displays clickable references and what each source supports; - every candidate is marked `PRIMARY_SOURCE_CONFIRMED_NOT_INDEPENDENTLY_AUDITED`; - the interface explicitly warns that first-party attribution is not independent verification of capacity, commercial appetite, legal eligibility, or future delivery. Two time-sensitive descriptions were tightened: - **NAVER Cloud:** a June 2026 announcement says initial 55 MW operations are planned for 2027, with a gigawatt-scale objective; a July 2026 update expanded the planned GAK Sejong deployment from 55 MW to 200 MW. These are plans/future milestones, not 2026 operating capacity. Sources: [NAVER, 2026-06-08](https://navercorp.com/en/media/pressReleasesDetail?seq=10034386) and [NAVER, 2026-07-25](https://www.navercorp.com/en/media/pressReleasesDetail?seq=10034518). - **SK Telecom / SK Hyper:** SKT announced an up-to-15-GW Korean AIDC program in July 2026, with the first 5 GW staged from 2029, and separately approved SK Hyper as its dedicated AIDC development company. Sources: [SK Telecom, 2026-07-05](https://news.sktelecom.com/en/3155) and [SK Telecom, 2026-07-23](https://news.sktelecom.com/en/3192). Other primary-source checks added to the portfolio include: - [OVHcloud AI Training capabilities](https://docs.ovhcloud.com/en/guides/public-cloud/ai-machine-learning/ai-training-capabilities) — BHS/Beauharnois is an active AI Training region; current hardware availability differs from GRA; - [KDDI, 2026-04-30](https://news.kddi.com/kddi/corporate/csr-topic/2026/04/30/7739.html) — company-reported renewable-electricity procurement, liquid cooling and Telehouse footprint; - [Verda, 2026-06-02](https://verda.com/blog/nvidia-vr200-r200-early-deployments) — announced Rubin deployments and expected 2027 capacity; - [Civo sovereign AI](https://www.civo.com/ai/sovereign) — public/private sovereign-AI architecture and residency controls; - [Sakura Internet, 2026-02-25](https://vip1b.www.sakura.ad.jp/corporate/information/newsreleases/2026/02/25/1968223641/) — company-announced operation of ~1,100 Blackwell GPUs in a containerized Ishikari facility; - [IONOS service catalog](https://docs.ionos.com/cloud/support/general-information/service-catalog) and [IONOS AI Model Hub governance](https://docs.ionos.com/cloud/ai/ai-model-hub/governance-and-compliance/eu-ai-act) — H200 GPU VMs and German/EU data-residency positioning; - [Firmus Southgate](https://firmus.co/infrastructure/southgate) and [Firmus 600 MW energy agreement](https://firmus.co/newsroom/firmus-secures-600-mw-energy-supply-agreement-in-south-australia-linked-to-1-2-gw-of-new-renewable-generation-and-battery-storage) — company-described energy-aligned/liquid-cooled infrastructure and energy agreement; - [Deutsche Telekom / T-Systems Industrial AI Cloud](https://www.telekom.com/en/media/media-information/archive/t-systems-brings-ai-into-the-supply-chain-1105624) — company-reported operation since February 2026 with 10,000 Blackwell GPUs; - [Nebius infrastructure partners](https://nebius.com/infrastructure-partners), [Meta agreement](https://nebius.com/newsroom/nebius-signs-new-ai-infrastructure-agreement-with-meta), and [Microsoft agreement](https://assets.nebius.com/assets/86625727-9e66-46c1-af79-c27d57434e3c/25-25580-1_Nebius%2520Group%2520N.V._6-K.pdf%3Fcache-buster%3D2025-09-08T21%3A23%3A09.625Z) — partner model and large U.S. counterparties; - [Scaleway H100](https://www.scaleway.com/en/h100/) — H100 availability in Paris/Warsaw and explicit European-jurisdiction positioning. ### 5. Hydro-Québec data-centre tariff: proposal status qualified with current regulator source The 0.13 CAD/kWh figure is a **proposed** average price, not a final approved tariff. The canonical evidence already treated it as context-only and non-final. This pass adds the live Régie proceeding as a qualifying source so the current status is traceable. - [Hydro-Québec proposal](https://nouvelles.hydroquebec.com/nouvelles/communiques/tout-quebec/tarifs-centres-donnees-chaines-blocs-refleteront-valeur-electricite-renouvelable.html) - [Régie de l’énergie — R-4333-2026](https://www.regie-energie.qc.ca/fr/participants/dossiers/r-4333-2026) — status `En cours` at retrieval on 2026-09-01. ### 6. Jurisdiction policy: legal references added without converting policy into law The country schedule remains a proposed owner/project policy and explicitly does **not** claim that every listed country is legally prohibited. Four Canadian legal/reference sources were added so reviewers can distinguish internal eligibility policy from Canadian sanctions/export-control law: - [Global Affairs Canada — Canadian sanctions](https://www.international.gc.ca/world-monde/international_relations-relations_internationales/sanctions/index.aspx?lang=eng) - [Global Affairs Canada — Consolidated Canadian Autonomous Sanctions List](https://www.international.gc.ca/world-monde/international_relations-relations_internationales/sanctions/consolidated-consolide.aspx?lang=eng) - [Justice Laws — Export and Import Permits Act](https://laws-lois.justice.gc.ca/eng/acts/E-19/index.html) - [Justice Laws — Export Control List (SOR/89-202)](https://laws-lois.justice.gc.ca/eng/Regulations/SOR-89-202/index.html) Important: the Government of Canada itself states that the consolidated autonomous sanctions list is an administrative aid, is not a regulation, and has no force of law. Governing regulations and transaction-specific legal review remain controlling. ## Additional current-source spot checks These high-value active claims were checked against authoritative/current sources and did not require correction in this pass: - **Nunavik EAUFON-3:** current Kativik Regional Government material targets cable landings/activation in 2027; the canonical evidence correctly treats the phase as planned/under development rather than complete. [KRG EAUFON project update](https://www.krg.ca/en-CA/eaufon-mapping-tools-in-Ungava-Bay) - **Nunavik fibre funding benchmark:** CRTC Decision 2024-163 authorizes up to CAD 79,419,117 for a 933 km KRG transport-fibre project; the benchmark is correctly labeled a funding-intensity proxy, not a total construction unit cost. [CRTC 2024-163](https://crtc.gc.ca/eng/archive/2024/2024-163.pdf) - **Nunavut fibre funding benchmark:** CRTC Decision 2024-149 authorizes up to CAD 271,937,242 for approximately 1,300 km; again, the model correctly treats the ratio as a contribution proxy. [CRTC 2024-149](https://web.crtc.gc.ca/eng/archive/2024/2024-149.htm) - **PUE context:** the Uptime Institute 2025 survey reports average PUE values of 1.48 for facilities commissioned within five years and 1.44 for 20 MW+ facilities; the model correctly labels these as context only, not Kristal Farms site assumptions. [Uptime Institute Global Data Center Survey 2025](https://datacenter.uptimeinstitute.com/rs/711-RIA-145/images/2025.Annual.Survey.Report.pdf?version=0) - **Lac-Robertson:** Hydro-Québec documentation supports 21 MW hydro plus 4.8 MW diesel and states the system is not connected to the main transmission grid. [Hydro-Québec](https://nouvelles.hydroquebec.com/nouvelles/communiques/montreal/une-entente-visant-a-soutenir-les-initiatives-futures-de-pakua-shipi.html) ## Automated controls added/strengthened - `pipelines/validate/validate_public_references.py` - validates canonical evidence↔source relationships; - requires valid evidence references for observations and benchmarks; - requires International Portfolio candidate sources and HTTPS URLs; - validates community infrastructure source URLs; - validates grid `source_ids` against the source registry; - validates public evidence source records; - requires every public economic benchmark to resolve to public evidence. - `pipelines/validate/validate_economics.py` - now recomputes all 10 benchmark values from source metadata and fails on arithmetic drift. - publication tests now require candidate references, policy/legal lookup references, UI source exposure, and public benchmark evidence resolution. ## Test result `pytest -q`: **94 passed**. The TypeScript typecheck was not run because this snapshot does not contain `apps/web/node_modules`; no dependency installation was performed during the validation pass. ## Remaining risk / next-pass priorities 1. **Primary-source bias:** the International Portfolio sources are mostly company/first-party sources. They prove attribution, not independent truth. A second pass should add independent corroboration for capacity, operating status, ownership/control and customer concentration where it affects decisions. 2. **Legacy internal evidence:** public evidence still contains explicitly typed `internal_legacy_research` records without public URLs. These remain historical context only and should never be treated as current authority. 3. **Source freshness:** fast-changing project schedules, tariffs, sanctions and infrastructure status need a `valid_through`/freshness policy or scheduled revalidation. 4. **Legal status:** sanctions/export-control references are lookup aids; legal screening must resolve the governing regulations and facts for the specific counterparty and transaction. 5. **Publication release discipline:** this work updates the current working publication artifacts but does not create a newly signed/immutable formal release bundle. ## Validation rule of thumb adopted in this pass A factual statement is not considered decision-ready merely because it has a URL. The minimum acceptable chain is: **claim → evidence record → attributable source → explicit scope/status/date → publication reference** For company-announced future capacity, the status must remain **planned/announced** until independently supported as operational. ================================================================================================ FILE: docs/data/economic-data-contract.md AUTHORITY: reference ================================================================================================ # Economic data contract ## Evidence `research.economic_benchmark` stores externally sourced ratios and context. Every benchmark is marked `usable_as_site_estimate=false`. ## Assumptions `scenario.assumption` is the explicit bridge from benchmark/context to a scenario. Unknown site costs are stored as `UNPRICED`, never silently treated as zero. ## Results `scenario.result` stores derived outputs with algorithm key/version and completeness state. ## Sensitivity `scenario.sensitivity_case` stores non-site distance stress cases. ## Forbidden automatic outputs The generic economic workflow does not produce project IRR, bankable NPV, net project savings, site rank, project MW/head/design flow or a winning-site conclusion. Those require a project-specific dossier with engineering and commercial evidence. ================================================================================================ FILE: docs/data/evidence-matrix.md AUTHORITY: reference ================================================================================================ # Hydrology evidence matrix All 24 Hydro Resource Atlas river references currently remain `hydrology = partial`. This means: - an official WSC station entity exists; - official HYDAT collection/source metadata is registered; - station-filtered ingestion jobs exist; - full raw flow series are not materialized in the current fixture; - real-data climatology has therefore not been published from those series; - design flow and MW remain prohibited automatic outputs. Additional source depth for individual rivers improves evidence coverage but does not create a rank or preferred-site conclusion. ================================================================================================ FILE: docs/data/hydrology-data-contract.md AUTHORITY: reference ================================================================================================ # Hydrology data contract ## Operational model Hydrology is stored as provenance-rich observations rather than pasted onto river geometry. ```text research.source ↓ research.evidence ↓ research.observation_series ↓ research.observation ↓ research.observation_derivation # derived values only ``` A series is materialized only after raw source rows are actually retrieved. In the current research runtime, full HYDAT series have not been materialized; empty placeholders are not published as data. ## Source observations Examples include: - `daily_mean_discharge_m3s`; - `monthly_mean_discharge_m3s`; - annual maximum/minimum daily-mean discharge. Source values preserve record identity, measurement time, source release, retrieval time, quality/provisional flags when available and raw-artifact lineage. ## Derived observations Derived hydrology must preserve: - derivation type; - algorithm key and semantic version; - source series IDs; - coverage start/end; - raw value count; - completeness fraction; - parameters. The current research statistic `hydrology.climatological_monthly_mean@1.0.0` is completeness-gated and is not an engineering design-flow selector. ## Forbidden automatic outputs The hydrology pipeline must not automatically produce: - `design_flow_m3s`; - `project_gross_head_m`; - `project_net_head_m`; - `capacity_mw`; - `validated_hosting_capacity_kw`; - site score/rank. Those values require later engineering, utility/service validation or governance decisions. ================================================================================================ FILE: docs/data/hydrology-derivation-policy.md AUTHORITY: reference ================================================================================================ # Hydrology derivation policy ## Research statistics are not engineering selections A climatological monthly mean may be derived automatically when source coverage satisfies a documented QA gate. A **design flow cannot**. The initial algorithm `hydrology.climatological_monthly_mean@1.0.0` uses configurable defaults: - minimum 10 sufficiently complete calendar years; - minimum annual completeness fraction 0.90; - minimum month completeness fraction 0.80. These are Kristal Farms research-QA defaults, not universal hydrology standards and not evidence of engineering sufficiency. Parameter changes require a versioned algorithm/configuration record. Low-flow frequency metrics, firm-energy selection, environmental flow, design flood and turbine design flow are deferred to project-specific hydrology and engineering work. ================================================================================================ FILE: docs/data/hydrology-observation-pipeline.md AUTHORITY: reference ================================================================================================ # Hydrology observation pipeline ## Source model Official hydrometric data is ingested into a source-preserving workflow: `raw response → staging normalized rows → research source/evidence → research observation` Raw API rows are never written directly into `core` entities. ## Metrics - `daily_mean_discharge_m3s` — source observation; - `monthly_mean_discharge_m3s` — source observation; - seasonal/climatological statistics — derived observations with algorithm version; - `design_flow_m3s` — engineering value and therefore never auto-created from daily/monthly observations. ## Current runtime state Hydrology ingestion jobs are registered for the canonical WSC stations, but the full source series were not materialized in the research runtime because the external hosts were not reachable from that execution environment. No flow values were fabricated to fill the gap. ================================================================================================ FILE: docs/data/hydrology-source-versioning-and-time.md AUTHORITY: reference ================================================================================================ # Hydrology source versioning and time Hydrology uses two separate clocks. ## Measurement time `valid_from`, `valid_to` and source date identify when a hydrologic value applies. ## Knowledge time `retrieved_at`, `source_release`, evidence publication date and raw-artifact hash identify what the project knew and from which release. This distinction matters because official metadata can change. Natashquan station 02WB003 currently retains both the WSC `gross_drainage_area_km2 = 15400` observation and the CEHQ `station_basin_area_km2 = 15693` observation under separate metrics/evidence; neither silently overwrites the other. The current HYDAT source manifest records release `HYDAT_20260717`. ================================================================================================ FILE: docs/data/ingestion.md AUTHORITY: reference ================================================================================================ # Data ingestion ## Flow ```mermaid flowchart LR Source --> Raw Raw --> Staging Staging --> Validate Validate --> Core[Core / Research] Core --> QA QA --> Publish ``` ## `raw` Preserve source-faithful values and source metadata. Avoid irreversible cleaning. ## `staging` Perform parsing, CRS conversion, unit normalization, entity matching, and schema mapping. ## `core` / `research` Write only records that satisfy canonical constraints. ## Idempotency Imports should be rerunnable. Use stable source IDs, checksums, or import batch IDs to avoid uncontrolled duplication. ## Import manifest Each import should record at least: ```text import_id source_id source_hash started_at completed_at record_count warning_count error_count code_version ``` ## Manual review Ambiguous entity matches, regulatory interpretation, or source conflicts should enter a review queue/state rather than being guessed by automation. ================================================================================================ FILE: docs/data/integrated-atlas-data-contract.md AUTHORITY: reference ================================================================================================ # Integrated Atlas data contract ## Purpose Connect canonical hydrology to community, logistics, telecom, energy and evidence context without inventing geometry or site merit. ## Domain rules - approximate community centroids are not port/project coordinates; - conceptual research corridors use `geometry = NULL` and are not routes/boundaries; - marine/fibre/service context may be related to communities without route geometry; - external projects use `role = external_reference`; - legacy screening classifications are provenance only; - `rights_governance` remains research-required unless specific authoritative evidence is attached; - legacy river/community links do not imply site proximity, consent or project selection; - no public property or visual style may encode site rank or merit while ranking is disabled. ================================================================================================ FILE: docs/data/provenance.md AUTHORITY: reference ================================================================================================ # Provenance ## Minimum provenance for material claims A material claim should be traceable to: - source identifier; - source title/authority; - source date where known; - retrieval date; - evidence identifier; - transformation/import version; - last verification date where relevant. ## Source registry Sources are controlled records. Do not duplicate the same source under several ad hoc URLs if it can be represented by one canonical source ID. ## Derived data Derived metrics must record: - input dataset version(s); - algorithm/model version; - assumptions; - units; - execution timestamp; - code version where practical. ## Source changes When a source changes, preserve the previous evidence state where needed for auditability. Do not silently rewrite historical research without recording the superseding state. ## User/owner direction Owner or project direction may define product intent and governance, but must not be represented as independent technical evidence. Use a distinct source/evidence classification for owner direction. ================================================================================================ FILE: docs/data/publishing.md AUTHORITY: reference ================================================================================================ # Data publishing ## Public release strategy The canonical database is live and mutable; public release artifacts are immutable and versioned. ```text PostGIS -> publish views -> QA -> PMTiles/COG/metadata -> object storage/CDN ``` ## Publish views The `publish` schema should contain explicit public/professional views. Avoid having the release script infer security from arbitrary application state. ## Artifacts Typical release may include: ```text manifest.json catalog.json *.pmtiles *.tif / COG metadata/*.json checksums.txt ``` ## Release manifest Must record: - release version; - generated timestamp; - source DB migration/version; - included collections; - artifact hashes; - classification/publication policy version; - QA result. ## Rollback Because artifacts are immutable, rollback should mean repointing the public release alias/config to a previous validated version, not rewriting files in place. ================================================================================================ FILE: docs/data/release-versioning.md AUTHORITY: reference ================================================================================================ # Data release versioning ## Separate versions Track independently: - application version; - database migration version; - data release version; - model/scenario-engine version; - policy version. ## Suggested data release format A date-based release is appropriate during research, for example: ```text 2026.08.30-r1 ``` If formal semantic compatibility requirements emerge, a semantic version can be introduced later. ## Immutability Published release identifiers must be immutable. Corrections create a new release. ## Scenario linkage Every persisted scenario result must record the data release or dataset snapshot and model version used to produce it. ================================================================================================ FILE: docs/data/spatial-standards.md AUTHORITY: reference ================================================================================================ # Spatial standards ## Canonical storage Use PostGIS geometry/geography with an explicit SRID. ## Web interchange Web map delivery typically uses WGS84/Web Mercator-compatible representations. Preserve source CRS metadata during ingestion and transform intentionally. ## Precision Do not publish more spatial precision than the source supports. Examples: - community centroid source → centroid-level representation; - region-only evidence → no fabricated point; - conceptual corridor → visibly conceptual line with source/assumption metadata. ## Geometry validity Ingestion QA must check: - valid geometry; - expected geometry type; - non-empty geometry where required; - coordinate bounds; - SRID; - unexpected geometry presence for records defined as non-spatial. ## Generalization Large layers should have zoom-appropriate simplification or tile generalization. The canonical geometry should remain unsimplified unless source data itself is generalized. ================================================================================================ FILE: docs/data/temporal-model.md AUTHORITY: reference ================================================================================================ # Temporal model Kristal Farms distinguishes **world time** from **knowledge time**. ## World/valid time When the statement or object is true: ```text valid_from valid_to ``` Examples: - project operating period; - regulatory decision validity; - planning period; - infrastructure commissioning. ## Knowledge/provenance time When Kristal Farms learned or recorded it: ```text published_at retrieved_at observed_at last_verified created_at updated_at ``` ## Timeline UI The map timeline should filter or style by valid time. It must not implicitly treat `retrieved_at` as the date the real-world state became true. ## Period labels Planning periods such as `2025-2026` should be stored in a normalized form suitable for ordering, while preserving the source label for display. ================================================================================================ FILE: docs/domain/glossary.md AUTHORITY: reference ================================================================================================ # Glossary **Asset** — Existing or confirmed physical infrastructure. **Candidate site** — A location under Kristal Farms study. This term does not imply preference unless ranking is explicitly enabled. **Compute hosting capacity** — Capacity demonstrated as supportable for compute under defined electrical/utility assumptions. Not synonymous with utility planning margin. **Corridor** — Linear infrastructure or conceptual route such as transmission, road, marine, or fibre. **Evidence** — A claim-supporting research object connected to one or more sources and subjects. **External reference** — A project used for technical, governance, regulatory, or logistics precedent and not automatically a Kristal Farms development site. **Observation** — A measured, transcribed, or published value tied to a subject and source/evidence. **Planning margin** — Utility planning metric after the applicable planning criterion. It is not automatically customer hosting capacity or firm surplus. **Scenario** — A controlled hypothetical configuration evaluated against a specific data/model version. **Source** — The original publication, filing, dataset, page, document, interview record, or other controlled reference supporting evidence. **Status record without geometry** — A valid evidence/reference record for which the source does not establish a publishable spatial geometry. **Anchor offtaker** — A counterparty that contractually commits to a material share of initial capacity or revenue and helps underwrite a deployment. It is not synonymous with investor or operator. **Beneficial owner** — The natural person(s) who ultimately own or control a legal entity, subject to the applicable legal definition and due-diligence standard. **Black-box tenancy** — Commercial shorthand for a tenant-controlled encrypted environment in which Kristal Farms operates shared physical services without routine access to private tenant compute content. **Content-blind by design** — An operating principle under which routine provider operations do not require access to plaintext application payloads, private models/datasets or tenant cryptographic keys. **Counterparty** — The legal entity entering a commercial relationship with Kristal Farms, together with the ownership/control structure relevant to eligibility review. **Effective control** — The ability to direct or materially determine an entity's decisions through ownership, voting rights, contractual rights, governance or other means; the transaction-specific legal meaning requires legal review. **Enhanced due diligence (EDD)** — Additional review required where ownership, jurisdiction, sanctions/trade exposure, institutional role or other risk factors create material uncertainty beyond standard commercial diligence. **Jurisdictional eligibility** — A project decision about whether a legal counterparty/control structure may proceed to contracting under Kristal Farms international tenancy policy. It is not a ranking of a country's population. **Tenant-controlled encrypted environment** — The normative term for the black-box tenancy model: the tenant controls private compute systems and cryptographic keys while Kristal Farms operates agreed shared infrastructure services. ================================================================================================ FILE: docs/domain/screening-governance.md AUTHORITY: reference ================================================================================================ # Screening governance ## Current state The active decision model is **unranked evidence screening**. Legacy tiers and historical priorities may be retained for provenance, but they are not active decision outputs. ## Policy fields The machine-readable policy file is `contracts/policy/kristal-farms-policy.yaml`. Required behavior while ranking is disabled: - no numeric composite site score; - no rank order presented as a recommendation; - no green/yellow/red opportunity classification; - no badge such as “best”, “top”, or “priority”; - no marker size encoding that implies preference; - no default sorting by legacy tier as if it were current priority. ## Evidence matrix Screening should instead track completeness/status by domain, for example: - energy; - hydrology; - environment; - rights/governance; - telecom; - logistics; - community; - regulation; - economics; - engineering. ## Enabling ranking later Ranking requires: 1. explicit governance decision; 2. documented methodology; 3. transparent criteria and weights; 4. evidence-quality handling; 5. traceable input values; 6. sensitivity analysis where appropriate; 7. an ADR and policy-version change. ================================================================================================ FILE: docs/frontend/accessibility.md AUTHORITY: reference ================================================================================================ # Accessibility The visual impact of the application must not depend on excluding keyboard, low-vision, or screen-reader users. ## Requirements - keyboard-accessible major controls; - meaningful focus order; - visible focus states; - non-color encoding for statuses; - sufficient contrast for text/controls; - reduced-motion option for cinematic transitions; - textual equivalent for essential map-derived facts; - accessible names for layer controls and inspector actions. ## Map limitations Maps are inherently difficult for assistive technologies. Provide searchable tables/inspectors for important datasets so core information is not available only by pointing at a geometry. ## Animation Respect `prefers-reduced-motion`. Important information should remain available when animations are reduced or disabled. ================================================================================================ FILE: docs/frontend/cartography.md AUTHORITY: reference ================================================================================================ # Cartography ## Goal The map should feel technically sophisticated and visually distinctive while preserving data semantics. ## Visual hierarchy 1. selected/focused subject; 2. active technical layers; 3. labels required for interpretation; 4. contextual base map; 5. decorative effects. ## Semantic styling Prefer styling by **object type, verification state, and hypothesis status**, not attractiveness or rank. Suggested symbol families: ```text ● community ◆ energy asset ▲ external reference project ━ verified infrastructure ┄ conceptual corridor ◌ scenario object ? insufficient/unknown evidence ``` ## Hypotheses Conceptual and scenario geometries must remain visibly distinct from observed/verified infrastructure. Dashes, halos, transparency, labels, and inspector badges may be combined. ## Uncertainty Uncertainty should be legible but not visually punitive. Avoid automatically mapping “unknown” to red, since red commonly implies negative evaluation. ## Terrain and globe Use terrain/globe in Showcase scenes where topography, remoteness, or geography materially improves understanding. Explorer should allow a more stable analytical view. ## Animated flows Energy or fibre flow animations must represent system relationships, not simulated precision unless driven by actual scenario outputs. ## Accessibility Do not rely on color alone. Ensure symbols, strokes, labels, and inspector text also communicate status. ## Interaction specification Hover, selection, relation constellations, approximate-geometry cues, camera behavior, and the dark “observation instrument” treatment are specified in [Map observatory interaction](map-observatory-interaction.md). This document remains the source for general cartographic semantics; the observatory document defines how those semantics behave interactively. ## Observatory v0.2.4 basemap behavior The product applies a stable Observatory theme over the contextual vector style: - generic park/protected-area and landuse/landcover fills are hidden to avoid zoom-threshold surface pop-in; - Natural Earth shaded relief is kept visible beyond the upstream default fade and then transitions into a neutral dark land background; - photographic imagery, when present, is a manually published local snapshot under `apps/web/public/imagery/`, never a runtime satellite API; - contextual hydrography and labels remain above photographic imagery; - all photographic imagery remains context-only unless separately governed as evidence. ================================================================================================ FILE: docs/frontend/design-system.md AUTHORITY: reference ================================================================================================ # Design system ## Product character The interface should communicate northern geography, infrastructure, precision, and technical seriousness without resembling a generic enterprise GIS theme. ## Two densities ### Showcase density - large editorial typography; - fewer controls; - cinematic spacing; - guided narrative; - strong visual hierarchy. ### Explorer density - compact technical controls; - persistent metadata/evidence access; - tables and filters; - predictable workstation layout. Shared tokens should keep both modes recognizably one product. ## Semantic tokens Define design tokens for object/status semantics rather than hardcoding colors in components. Example namespaces: ```text community.* asset.energy.* project.external_reference.* scenario.* evidence.verified evidence.unknown corridor.conceptual ``` Do not create `site.good`, `site.bad`, or equivalent ranking semantics while ranking is disabled. ## Map interaction character The map-specific expression of these tokens is defined in [Map observatory interaction](map-observatory-interaction.md). The “Observatory” language is intentionally restrained: precision, hierarchy, evidence state, and responsive focus create the technical character; permanent glow and decorative telemetry do not. ================================================================================================ FILE: docs/frontend/layer-catalog.md AUTHORITY: reference ================================================================================================ # Layer catalog ## Purpose The layer catalog makes the application data-driven. Generic layers are described declaratively and instantiated by shared rendering code. Machine schema: `contracts/layers/layer-catalog.schema.json` Example: `contracts/layers/layer-catalog.example.yaml` ## Catalog responsibilities A layer definition may control: - ID/title/group; - source type and collection; - geometry types; - renderer; - style token or expressions; - min/max zoom; - legend; - filters; - temporal behavior; - inspector fields; - evidence support; - export capability; - classification/permissions; - feature-state behavior. ## Source types Initial source types: ```text vector_tiles pmtiles ogc_features geojson_small cog api_derived scenario ``` ## Special layers A custom component is appropriate when a layer requires behavior not expressible through the generic catalog, such as an interactive scenario network or engineering 3D model. ## Validation Catalog configuration must be schema-validated in CI and at application build/startup. Unknown source types, missing IDs, invalid permissions, or malformed field mappings should fail fast. ================================================================================================ FILE: docs/frontend/map-observatory-interaction.md AUTHORITY: reference ================================================================================================ # Map observatory interaction ## Status This document defines the interaction and visual-behavior specification for the Kristal Farms map experience shared by **Explorer** and **Showcase**. The design language is called the **Observatory interaction language**. It borrows the calm, instrument-like qualities of astronomical observation interfaces without turning the application into decorative science fiction. This document is normative where it uses **MUST**, **MUST NOT**, **SHOULD**, and **MAY**. Related documents: - [Explorer](../product/explorer.md) - [Showcase](../product/showcase.md) - [Cartography](cartography.md) - [Design system](design-system.md) - [Layer catalog](layer-catalog.md) - [Accessibility](accessibility.md) - [State and permalinks](state-and-permalinks.md) - [Frontend architecture](../architecture/frontend.md) - [Explorer data contract](../product/explorer-data-contract.md) - [ADR-014 — Integrated atlas uses relations, not synthetic geometry](../adr/0014-integrated-atlas-uses-relations-not-synthetic-geometry.md) --- ## 1. Product intent The map is not a generic GIS canvas and not a futuristic decoration layer. It is an **instrument for observing territorial knowledge**. The interaction model should communicate the following progression: ```text WHERE? ↓ MAP OBJECT ↓ WHAT IS IT? ↓ ENTITY ↓ WHAT IS IT RELATED TO? ↓ RELATIONS ↓ WHY DO WE BELIEVE IT? ↓ EVIDENCE ``` The map is the entry point into the knowledge model, not the full knowledge model itself. ### 1.1 Core experience The signature interaction sequence is: ```text silence → detection → observation → investigation ``` - **Silence:** the map is calm and legible at rest. - **Detection:** nearby interactive features respond subtly to pointer proximity. - **Observation:** hover or focus reveals a compact factual summary. - **Investigation:** selection opens persistent evidence, relations, observations, and provenance. ### 1.2 Design principle The interface SHOULD reveal information progressively instead of rendering all labels, metadata, relationships, and evidence simultaneously. The visual sophistication of the application MUST come from hierarchy, precision, state transitions, and data semantics—not from permanent glow, animation, or visual noise. --- ## 2. Relationship to the existing cartographic identity The current Kristal Farms cartographic references establish a recognizable semantic palette and symbol language. The interactive application SHOULD preserve that identity while adapting it to a dark, screen-native environment. Recommended continuity: - turquoise remains a product/context accent; - blue remains associated with hydrology; - amber/orange remains associated with communities where the semantic token specifies it; - green remains associated with energy/reference energy objects where the semantic token specifies it; - hypothetical/scenario states remain visually distinguishable from observed or verified objects. The interactive interface SHOULD transform the medium rather than replace the vocabulary: ```text editorial map paper + ink + symbols ↓ interactive atlas terrain + darkness + signals ``` Colors MUST remain semantic tokens. Components MUST NOT hardcode ad-hoc colors to imply site quality, merit, attractiveness, or ranking. The current machine-readable visual authority is `packages/shared/visual_semantics.json`. Where this document and that file differ, implementation MUST follow the machine-readable rule until both are intentionally changed in the same pull request. Current canonical role rules include: ```text community circle hydrometric_station small_dot external_reference triangle conceptual_corridor panel_only unknown_geometry no_map_symbol ``` Current canonical evidence/status treatments include: ```text verified solid supported solid_light scoped outline unverified dashed_outline conflicting split_or_warning unknown question ``` --- ## 3. Visual hierarchy The active viewport SHOULD follow this order of attention: 1. selected or focused subject; 2. active technical layers; 3. labels required for interpretation; 4. hydrography and terrain context; 5. administrative/contextual geometry; 6. decorative effects. ### 3.1 Base map The dark map SHOULD retain geographic materiality rather than use a uniform black background. Recommended depth hierarchy: ```text UI / selected information highest luminance active technical layer high hydrography medium-high terrain/topography medium-low administrative boundaries low background lowest ``` The base map SHOULD make northern geography, coastlines, water, remoteness, and terrain legible without competing with active data. ### 3.2 Glow discipline Permanent glow MUST NOT be applied to every object. Glow/halo effects SHOULD be reserved for: - pointer/focus proximity; - active hover/focus; - selected entities; - temporary Showcase narrative emphasis. If everything glows, glow no longer communicates state. --- ## 4. Primary screen composition Explorer SHOULD allow the map to occupy most of the viewport. Persistent controls SHOULD be limited to compact functional zones rather than a permanently dominant GIS sidebar. A reference composition: ```text ┌─────────────────────────────────────────────────────────────────────┐ │ KRISTAL / NORTHERN ATLAS SEARCH LAYERS │ │ NUNAVIK · HYDROLOGY │ │ │ │ · │ │ · ◇ │ │ │ │ • │ │ · │ │ │ │ • • ▲ │ │ │ │ 58.70250, -68.52000 Z 6.42 RELEASE 2026.08.30 │ └─────────────────────────────────────────────────────────────────────┘ ``` The actual labels and release values are data-driven; the wireframe above is illustrative only. ### 4.1 HUD A compact map HUD MAY expose: - current geographic context; - cursor/center coordinates; - zoom level; - active layer count; - public release identifier; - scale; - north/bearing state. HUD information SHOULD be factual and useful. Decorative telemetry with no meaning SHOULD NOT be added solely to create an “astro” appearance. --- ## 5. Map object state model Interactive map features MUST have explicit UI states. Minimum states: ```text idle proximity hovered / keyboard-focused selected compared ``` A feature MAY also be visually dimmed as a derived presentation state when another object is selected, but `dimmed` is not a domain status. ### 5.1 Idle Idle objects SHOULD remain clear but restrained. ```text • ``` No permanent pulse is required. ### 5.2 Proximity When a pointer enters a small interaction radius around a feature, the feature MAY enter a proximity state before a hover card is shown. ```text ◉ ``` Recommended response: - slightly increased luminance; - thin outer ring or reticle; - no camera movement; - no persistent information panel. This state SHOULD feel like detection, not selection. ### 5.3 Hover / keyboard focus Hover or keyboard focus reveals a compact summary. The feature SHOULD gain a clear but restrained focus treatment such as: - an outer ring; - a reticle; - a short leader line when needed; - increased contrast relative to nearby objects. Hover/focus MUST NOT change the map camera. ### 5.4 Selected Selection is persistent until replaced or dismissed. Selected state SHOULD: - remain visually stable after the pointer leaves; - open or update the Entity Inspector; - optionally reduce competing layer contrast slightly; - serialize the entity ID to URL state where permitted. Selection MAY cause a small camera adjustment when required to keep the subject visible beside the Inspector. It MUST NOT produce aggressive camera motion. ### 5.5 Compared Compare mode SHOULD support at least two pinned entity IDs when the product flow enables comparison. Compare styling MUST NOT imply a winner, score, rank, or preferred option. --- ## 6. Pointer proximity and hover behavior ### 6.1 Detection target The visible symbol size and the pointer hit target are separate concerns. Small technical points, especially hydrometric stations, SHOULD retain precise visual geometry while exposing a larger invisible interaction target. The hit target SHOULD be large enough for reliable pointer acquisition without causing excessive overlap between nearby entities. ### 6.2 Hover delay The application SHOULD use a short hover-intent delay before opening a card. A starting range of approximately **80–120 ms** is recommended for prototype tuning. The delay is a UX tuning value, not a data contract. ### 6.3 Exit grace period Hover cards SHOULD remain interactive long enough for the pointer to move from the map feature into the card without immediate dismissal. The implementation SHOULD avoid flicker when crossing the feature/card boundary. ### 6.4 Overlapping candidates When multiple features are within the hit region, selection SHOULD be deterministic. Recommended ordering criteria: 1. rendered/topmost interactive layer; 2. shortest screen-space distance to pointer; 3. stable layer/entity ID as final tie-breaker. The application MUST NOT resolve overlap by hidden site merit or opportunity ranking. --- ## 7. Hover card The hover card is a **recognition surface**, not a full inspector. It should answer quickly: 1. What is this? 2. What is its relevant current state? 3. Why is it relevant in the current context? 4. What is the geometry/evidence confidence I should understand immediately? ### 7.1 Content budget A hover card SHOULD normally contain: - object type; - title/identifier; - secondary geographic/context label; - 2–4 high-value fields; - evidence/geometry qualifier; - selection affordance. It SHOULD NOT render the complete entity record. ### 7.2 Example: hydrometric station Illustrative structure: ```text HYDROMETRIC STATION VERIFIED 02WB003 Natashquan River ACTIVE DRAINAGE AREA 15,400 km² REGION Côte-Nord / Minganie ────────────────────────────────────────────── Official station position · Click to inspect ``` Values above are illustrative of card structure; rendered values MUST come from governed application data. ### 7.3 Example: community Illustrative structure: ```text COMMUNITY APPROX. AKULIVIK Nunavik / Hudson coast FIBRE Operating MARINE Regional port-system context ROAD No intercommunity road link ────────────────────────────────────────────── Reference point · not facility location ``` Community coordinates that are approximate reference points MUST NOT be presented as facility coordinates. ### 7.4 Placement The hover card SHOULD choose an anchor direction based on available viewport space. It SHOULD avoid: - clipping against viewport edges; - covering the selected feature when avoidable; - covering critical controls; - large pointer travel between the feature and card. A leader line MAY be used when the card is displaced from its source feature. --- ## 8. Entity Inspector The Entity Inspector is the primary investigation surface. It MUST contain more than a generic map popup and SHOULD expose governed context, evidence, relations, observations, provenance, and unknowns as appropriate to the entity type. ### 8.1 Recommended width On desktop Explorer layouts, a starting width in the approximate **380–460 px** range is recommended. Exact dimensions remain responsive design tokens. ### 8.2 Generic information architecture Recommended generic sections: ```text OVERVIEW EVIDENCE RELATIONS ``` Entity-specific sections MAY extend the model. For example: ```text hydrometric station OVERVIEW · OBSERVATIONS · HYDROLOGY · EVIDENCE community OVERVIEW · INFRASTRUCTURE · RELATIONS · EVIDENCE ``` ### 8.3 Evidence visibility Evidence status SHOULD be visible before the user opens a dedicated evidence section. Useful compact labels include concepts such as: ```text VERIFIED CONTEXTUAL APPROXIMATE GEOMETRY UNRESOLVED ``` Actual values MUST use governed status enums and data contracts rather than invented frontend-only truth states. ### 8.4 Unknowns Unknown or unresolved information MUST remain explicit. The Inspector MUST NOT silently omit an important unknown in a way that makes the record appear more complete than the evidence supports. --- ## 9. Evidence and uncertainty as visual language Evidence quality and geometry precision are not opportunity quality. They MUST be encoded independently from any site merit concept. ### 9.1 Non-color encoding Statuses SHOULD have a geometric/stroke treatment that remains understandable without color. A possible design family: ```text ● verified / exact presentation where supported ◉ supported/contextual ○ scoped/reference ◌ approximate or unresolved presentation state ? insufficient/unknown ``` These glyphs are a visual design direction, not a replacement for canonical status enums. ### 9.2 Approximate point geometry Approximate community/reference points SHOULD look approximate. A thin dashed or incomplete outer ring MAY be used to communicate that the point is a geographic reference rather than a precise facility location. The Inspector or hover card SHOULD state the limitation textually as well. ### 9.3 Do not punish uncertainty Unknown or unresolved data MUST NOT automatically be colored red. Red commonly implies failure or negative evaluation and would incorrectly conflate evidence completeness with opportunity quality. --- ## 10. Symbol anatomy A point symbol MAY communicate three layers of information without changing its apparent merit: ```text core = object family/type ring = evidence/geometry precision cue state = interaction cue ``` Example conceptual families: | Object | Current core rule | Precision/evidence treatment | | --- | --- | --- | | Community | circle | outer ring may show approximate reference geometry | | Hydrometric station | small dot; reticle may be added as interaction state | official geometry treatment when supported | | External reference project | triangle | governed reference/evidence treatment | | Conceptual corridor | panel only | no map symbol/line while current rule is active | | Unknown geometry | no map symbol | expose through Inspector/search/context only | Other object families use their catalog/design-system semantic token until a canonical role rule exists. Marker size MUST NOT be used as a hidden site-quality score. --- ## 11. Labels and progressive disclosure The interactive atlas SHOULD render fewer permanent labels than an editorial poster map. ### 11.1 Label priority At low zoom: - major geographic context; - selected/focused entity; - only essential community labels. At regional zoom: - more community labels; - selected technical features; - contextual hydrography. At technical zoom: - station IDs and local technical labels MAY become available where collision handling permits. ### 11.2 Hover labels Technical station identifiers and dense labels SHOULD prefer hover/focus disclosure over permanent map text when simultaneous rendering would cause clutter. ### 11.3 Selection emphasis When an entity is selected, non-essential neighboring labels MAY reduce contrast. They MUST remain available through search/inspection and MUST NOT disappear in a way that removes required context. --- ## 12. Linear and polygon features The observatory interaction model applies to more than points. ### 12.1 Rivers Hovering/focusing a river MAY highlight the rendered feature and show a compact card with: - canonical river name; - related monitoring station count or selected station where supported; - evidence/provenance summary; - inspection affordance. Example structure: ```text RIVER Natashquan River / Rivière Natashquan HYDROMETRIC OBSERVATION 02WB003 EVIDENCE Verified station metadata Click to inspect hydrology ``` Rendered values and relations MUST come from canonical data. ### 12.2 Polygons Polygons SHOULD use boundary/fill changes that preserve surrounding geography. Selection MUST NOT create the appearance of greater certainty than the source geometry provides. --- ## 13. Relations as constellations Relations are central to the integrated atlas, but relations are not automatically geometry. ### 13.1 Rule A relation without authoritative route/facility geometry MUST NOT be drawn as a geographic line merely to make the interface look connected. This is a direct application of [ADR-014](../adr/0014-integrated-atlas-uses-relations-not-synthetic-geometry.md). ### 13.2 Inspector constellation The preferred representation for non-geometric relationships is a small relation graph inside the Inspector. Example: ```text FIBRE ○ MARINE ○ ◎ ○ ENERGY ○ EVIDENCE ``` The center represents the selected entity. Satellites represent relation dimensions or related entities. This graph is **topological UI**, not map geometry. ### 13.3 Screen-space constellation Showcase MAY use temporary relation lines in screen space, anchored visually to a selected entity and UI labels. Screen-space relation lines: - MUST NOT be written into the map source as synthetic geographic geometry; - MUST NOT be exported as a route or infrastructure feature; - MUST disappear when the narrative/focus state ends; - SHOULD be labeled or styled clearly enough to avoid confusion with actual infrastructure; - MUST NOT be used to represent `conceptual_corridor` while the current `panel_only` rule is active. ### 13.4 Geographic relations with real geometry When governed geometry exists for an actual route, network, or feature, it MAY be rendered geographically using its normal semantic layer style. The existence of a relation alone is insufficient to create that geometry. --- ## 14. Conceptual corridor treatment Conceptual corridor context requires special care because a connecting line can be misread as an asserted route. ### 14.1 Explorer The current machine rule for `conceptual_corridor` is `panel_only`. Explorer MUST therefore use an ordered entity/context representation rather than a map line for conceptual corridor context. Example: ```text NORTHERN CORRIDOR CONTEXT Akulivik ↓ Inukjuak ↓ Kuujjuaq ↓ Nain ↓ Hopedale Conceptual relationship No route geometry asserted ``` Related map entities MAY receive temporary focus emphasis while this view is active. ### 14.2 Showcase The current `conceptual_corridor: panel_only` machine rule also applies to Showcase. A story MAY sequence camera focus across related entities, but it MUST NOT draw a connecting corridor trace while that rule is active. A future screen-space narrative trace would require an explicit change to the governing visual-semantics contract and corresponding documentation/tests. It must never be introduced by frontend styling alone. --- ## 15. Cursor and focus reticle Explorer MAY use a map-only reticle cursor to reinforce the instrument-like interaction model. Example: ```text │ ──┼── │ ``` Near an interactive feature: ```text │ ──◎── │ ``` Requirements: - custom cursor treatment MUST be limited to the map canvas; - standard pointer/text cursors MUST remain available over controls and text; - the interaction MUST remain usable without the custom cursor; - keyboard focus MUST provide equivalent discovery and selection states. --- ## 16. Observation lens / mobile targeting Hover does not exist on touch devices. The design language MUST have a touch-equivalent interaction. A future or optional **observation lens** MAY provide a center-screen targeting mode: ```text │ ───┼─── │ ``` As the user pans the map, the closest eligible feature to the lens becomes the focus candidate. A tap or explicit Inspect action selects it. The lens can also be useful for keyboard/gamepad-like navigation, but it MUST NOT become the only way to select a feature. --- ## 17. Camera behavior Camera motion MUST be tied to clear user or narrative intent. ### Explorer - hover/focus: **no camera movement**; - click/select: minor recentering MAY occur to preserve subject + Inspector visibility; - explicit “explore/focus” action: stronger transition MAY occur; - camera MUST remain interruptible by the user. ### Showcase Showcase MAY use cinematic camera transitions when they improve geographic understanding. Showcase camera behavior remains configuration-driven as specified in [Showcase](../product/showcase.md). ### Motion timing Exact transition durations are implementation tokens, not hard domain rules. As a starting direction: - ordinary Explorer selection transitions SHOULD feel short and functional; - Showcase scene transitions MAY be longer and cinematic. All essential information MUST remain available with reduced motion enabled. --- ## 18. Motion language Animation SHOULD represent a system response to user or narrative action. Recommended transitions: - outer ring drawing in on proximity/focus; - hover card reveal; - leader line reveal; - Inspector panel transition; - relation constellation assembling after explicit selection; - temporary subject emphasis in Showcase. Avoid: - continuous marker pulsing; - decorative particle fields; - unrelated HUD movement; - animated flows that imply measured direction, capacity, or precision when none exists. `prefers-reduced-motion` MUST be respected. --- ## 19. Compare mode Compare mode SHOULD present dimensions side by side without scoring. Example: ```text AKULIVIK NAIN TELECOM operating fibre unresolved backbone MARINE regional context scheduled service context ENERGY — remote diesel context GEOMETRY approximate approximate ``` The exact fields are entity/data dependent. Compare mode MUST NOT: - rank entities implicitly; - sort by hidden merit; - use “winner/loser” visual treatments; - convert evidence completeness into opportunity quality. Compare entity IDs MAY be stored in URL state where safe. --- ## 20. Explorer vs Showcase density The Observatory language is shared, but density differs. ### 20.1 Explorer Explorer prioritizes: - stable projection and camera behavior; - precise selection; - search and filters; - compact metadata; - evidence/provenance; - tables and export; - predictable workstation layout. ### 20.2 Showcase Showcase prioritizes: - large geographic composition; - fewer controls; - progressive narrative disclosure; - cinematic camera movement; - temporary terrain/globe effects; - temporary screen-space relation graphics. Showcase MUST NOT weaken evidence semantics merely for visual drama. --- ## 21. Frontend component model Recommended component structure: ```text MapWorkspace ├── MapViewport │ ├── BaseGeography │ ├── HydrographyLayers │ ├── CommunityLayers │ ├── HydrometricLayers │ ├── EnergyReferenceLayers │ └── FocusEffects ├── MapHUD │ ├── ContextHeader │ ├── Search │ ├── CoordinateReadout │ └── LayerControls ├── HoverController │ └── HoverCard ├── SelectionController ├── EntityInspector │ ├── Overview │ ├── Relations │ ├── Evidence │ └── EntitySpecificSections └── CompareTray ``` This is a logical decomposition, not a required directory structure. ### 21.1 Rendering responsibility MapLibre SHOULD render normal geographic feature layers directly. React SHOULD own interface surfaces around the map, including: - hover cards; - Inspector; - relation graph UI; - compare surfaces; - layer/search controls. DOM map markers SHOULD NOT be the default mechanism for large or ordinary point layers. ### 21.2 deck.gl deck.gl SHOULD remain optional for interactions or visualizations that justify a second rendering layer, such as: - large analytical overlays; - advanced relation/flow visualization; - specialized 3D/aggregation work. Basic communities, stations, and ordinary geographic features do not require deck.gl. --- ## 22. Feature state MapLibre `feature-state` is the preferred mechanism for ephemeral visual interaction state on compatible rendered features. Expected presentation states include: ```text hovered selected compared ``` `dimmed` MAY be derived by style logic when another entity is selected. These are UI states and MUST NOT be persisted as domain attributes. ### 22.1 Stable feature IDs Layers using feature-state MUST expose stable feature IDs compatible with the rendering source. Feature IDs SHOULD map cleanly to canonical entity IDs where practical. --- ## 23. Frontend state model Recommended local UI state: ```ts hoveredEntityId: string | null selectedEntityId: string | null compareEntityIds: string[] activeInspectorSection: string ``` Implementation MAY use a more structured state machine, but transient hover state MUST remain local UI state. Selected entity and safe compare IDs SHOULD participate in URL state as specified in [State and permalinks](state-and-permalinks.md). Remote entity/evidence records remain server state and SHOULD use the frontend query/cache layer. --- ## 24. Data loading behavior ### 24.1 Hover path Hover MUST be fast enough to feel immediate. Information needed for the hover card SHOULD be available from: - rendered feature properties; - a small local/indexed entity summary cache; - another preloaded lightweight representation. Hover SHOULD NOT require a full entity/evidence API round trip for every pointer movement. ### 24.2 Selection path Selection MAY fetch richer data from endpoints such as: ```text GET /entities/{id} GET /entities/{id}/evidence GET /entities/{id}/screening ``` The Inspector SHOULD show a stable selected state while detailed data loads. ### 24.3 Stale and versioned data The Inspector SHOULD make the active public/data release discoverable. Evidence timestamps and source-version information remain governed by the existing data contracts. --- ## 25. Layer catalog integration The existing layer catalog already defines source, renderer, style token, inspector fields, evidence support, and feature-state behavior. The first implementation SHOULD use those existing capabilities before expanding the machine schema. ### 25.1 Current configuration mapping The generic interaction system can derive: - whether a feature is inspectable from layer/catalog behavior; - card title from `inspector.title_field`; - card/Inspector fields from `inspector.fields`; - evidence affordance from `inspector.evidence_enabled`; - semantic styling from `display.style_token`. ### 25.2 Future schema extension If layer-specific hover cards require declarative field subsets, a future catalog schema version MAY introduce explicit interaction/card configuration. Illustrative only—not a current contract: ```yaml interaction: hover: true select: true hover_card: title_field: station_number subtitle_field: river_name fields: - status - gross_drainage_area_km2 - region ``` This example MUST NOT be treated as valid production configuration until the machine schema and example contract are updated together. --- ## 26. Search and non-map access Map discovery MUST NOT be the only way to reach important data. Explorer SHOULD provide search and, where appropriate, table/list access so users can locate entities by: - name; - identifier; - type; - region/context; - other governed searchable fields. Selecting an entity from search or a table SHOULD produce the same Inspector state as selecting it on the map. --- ## 27. Accessibility The Observatory interaction language MUST remain operable without precise pointer hover. Requirements: - major map actions keyboard accessible; - focused map entities receive the same factual summary as hover; - selection is possible without mouse hover; - important facts exist in Inspector/table/search surfaces; - focus state is visible without relying on color; - evidence/uncertainty cues are textual as well as graphical; - reduced motion is supported; - hover cards do not contain information unavailable elsewhere; - custom cursor effects are optional enhancements, not functional dependencies. Touch layouts MUST provide a selection path that does not depend on hover. --- ## 28. Performance requirements The interaction must feel like direct manipulation. Implementation SHOULD: - render ordinary feature layers in MapLibre rather than as many DOM markers; - avoid React rerenders on every raw pointer event; - throttle/debounce pointer queries appropriately; - use feature-state for visual hover/selection when possible; - keep hover-card data lightweight; - defer rich evidence loading until selection; - avoid expensive deck.gl layers when MapLibre is sufficient. The application SHOULD be tested on representative lower-powered laptops, not only high-end development hardware. --- ## 29. Interaction event flow Reference flow: ```text pointer move ↓ query rendered interactive features ↓ resolve deterministic candidate ↓ set proximity/hover feature-state ↓ short hover-intent delay ↓ render HoverCard from local summary click / Enter ↓ set selected entity ↓ serialize safe selection state ↓ open EntityInspector ↓ fetch entity + evidence + screening as needed ↓ render relations / provenance / observations ``` Leaving a feature clears transient hover state but MUST NOT clear a selected entity. --- ## 30. Testing ### 30.1 Unit/component tests Test at minimum: - deterministic hover candidate resolution; - hover delay cancellation; - card placement near viewport edges; - selected state surviving pointer exit; - selection from keyboard/search equivalent to map click; - relation graph not generating synthetic geographic features; - reduced-motion behavior; - safe URL serialization of selected/compare IDs. ### 30.2 Visual regression fixtures Curated deterministic fixtures SHOULD cover: - idle map; - point proximity; - hover card for a community; - hover card for a hydrometric station; - selected community + Inspector; - selected station + Inspector; - approximate geometry treatment; - verified vs hypothetical symbol treatment; - relation constellation in Inspector; - compare mode; - reduced-motion version; - narrow/mobile layout. Visual review MUST include semantic correctness, not only pixel similarity. ### 30.3 Integration tests At least one Explorer integration flow SHOULD verify: ```text search entity → select → Inspector opens → evidence loads → relation shown → URL captures selection → reload reconstructs view ``` --- ## 31. Acceptance criteria for the first Observatory implementation A first implementation is successful when all of the following are true. ### Map behavior - the map is visually calm at rest; - hover/focus is discoverable without permanent animation; - hover does not move the camera; - selected state is persistent and visually distinct; - labels remain legible without displaying all entity names simultaneously. ### Information behavior - hover answers identity + key state + evidence/precision at a glance; - click opens a richer Inspector rather than a larger popup; - important unknowns are visible; - approximate locations look and read as approximate; - relations without geometry are not drawn as geographic infrastructure. ### Architecture - ordinary layers are catalog-driven; - ordinary map features are rendered by MapLibre; - feature-state is used where appropriate; - transient hover state is not persisted to the domain model; - hover does not require full entity API requests; - selection integrates with canonical entity/evidence APIs. ### Accessibility - keyboard selection reaches equivalent information; - touch has an explicit selection path; - status is not communicated by color alone; - reduced-motion mode preserves all essential information. --- ## 32. Implementation sequence The Observatory language SHOULD be implemented incrementally. ### Stage A — Interaction foundation Build first: 1. dark base map and semantic symbols; 2. stable interactive feature IDs; 3. proximity/hover feature-state; 4. hover card with intelligent placement; 5. persistent selection; 6. Entity Inspector shell; 7. keyboard/touch equivalent interaction. This stage should prove the product signature before adding cinematic effects. ### Stage B — Evidence and relation depth Add: 1. evidence/provenance summary in Inspector; 2. entity-specific Inspector sections; 3. approximate-geometry treatments; 4. Inspector relation constellation; 5. shareable selection state; 6. line/polygon inspection behavior. ### Stage C — Professional Explorer depth Add: 1. compare mode; 2. advanced filters/timeline integration; 3. observation lens if user testing supports it; 4. richer keyboard navigation; 5. performance tuning for denser datasets. ### Stage D — Showcase expression Add selectively: 1. cinematic camera scenes; 2. temporary screen-space constellations; 3. narrative focus traces; 4. terrain/globe transitions; 5. stronger but still semantic motion treatments. --- ## 33. Explicit anti-patterns Do not implement the Observatory language as: - every marker pulsing continuously; - neon outlines on every layer; - star-field or particle decoration unrelated to data; - synthetic geographic lines for non-geometric relations; - auto-zoom on hover; - full metadata dumps in hover cards; - marker size as hidden opportunity score; - red = unknown / green = good; - separate interaction logic hard-coded for every ordinary layer; - DOM markers for all data points by default; - animation that suggests measured flows when only conceptual relations exist; - a custom cursor that makes ordinary controls harder to use. --- ## 34. Design review checklist Before merging a new interactive map behavior, reviewers should ask: ### Semantics - Does this graphic imply geometry, precision, capacity, ranking, or causality that the data does not support? - Is evidence quality being confused with opportunity quality? - Is an approximate location visually honest? ### Interaction - Does hover only reveal, while selection persists? - Can the same information be reached by keyboard/touch/search? - Does the user retain control of the camera? ### Visual hierarchy - Is the selected subject clearly dominant? - Is the base map quieter than active technical data? - Are glow and motion reserved for state changes? ### Architecture - Can the behavior be driven by the layer catalog and canonical entity IDs? - Is transient UI state kept out of domain data? - Is a non-geometric relation kept out of geographic sources? ### Evidence - Can the user discover what supports the claim? - Are unknowns and limitations visible? - Is the active data/release context discoverable? --- ## 35. Summary The Observatory interaction language should make Kristal Farms recognizable through restraint rather than spectacle. Its core rules are: 1. **The map is calm until the user observes something.** 2. **Hover reveals; click investigates.** 3. **Evidence and uncertainty are visible design primitives.** 4. **Relations are not geography unless governed geometry exists.** 5. **MapLibre owns ordinary geographic rendering; React owns investigation UI.** 6. **Motion responds to intent; it does not decorate idle state.** 7. **Explorer remains precise and analytical; Showcase may be cinematic.** 8. **Accessibility and touch are first-class, not fallback modes.** 9. **No visual treatment may imply site ranking while ranking is disabled.** 10. **The visual system should feel like a territorial observation instrument, not a generic GIS theme.** ================================================================================================ FILE: docs/frontend/offline-satellite.md AUTHORITY: reference ================================================================================================ # Offline satellite layer The Geographic Observatory can display real satellite imagery at high zoom without a runtime imagery provider. ## Product behavior - Low zoom: Observatory contextual basemap. - Regional zoom: Natural Earth relief fades gradually rather than to pitch black. - High zoom: a local photographic tile pyramid fades in when published. - Hydrography, boundaries, labels, stations and communities remain above it. - `Layers → Satellite imagery` controls visibility. - If no local snapshot has been published, the row is disabled and marked `LOCAL`. The layer reads only `/public/imagery/` assets included with the product release. It does not update automatically. ## Cartographic semantics Satellite imagery is **context only**. It must never be presented as evidence for a claim, a facility position, a corridor, a watershed boundary or a project geometry unless a separately governed evidence/geometry record exists. See `pipelines/imagery/README.md` for the manual build workflow. ================================================================================================ FILE: docs/frontend/state-and-permalinks.md AUTHORITY: reference ================================================================================================ # State and permalinks ## Shareable state A professional user should be able to send a link that reconstructs the analytical view. Recommended URL-state fields: - mode; - center/zoom/bearing/pitch; - selected entity ID; - visible layer IDs; - timeline position/range; - filter state; - compare selections where not sensitive. ## Privacy Never encode restricted scenario inputs, private notes, access tokens, or confidential entity names into shareable URLs. ## Stability Use stable entity and layer IDs. URL schemas should be versioned if major changes occur. ## Showcase Narrative scene URLs may use compact scene IDs and derive the rest from versioned story configuration. ================================================================================================ FILE: docs/index.md AUTHORITY: canonical ================================================================================================ # Kristal Farms documentation This documentation covers the **Kristal Farms infrastructure project** and the application/data system used to explain, research and evaluate it. ## Read in this order ### Project 1. [Project state](00-control/PROJECT_STATE.md) 2. [Strategic principles](00-control/STRATEGIC_PRINCIPLES.md) 3. [Project reference architecture — English](10-core/Kristal_Farms_Project_Reference_Architecture_EN.md) or [architecture de référence du projet — français](10-core/Architecture_de_reference_du_projet_Kristal_Farms_FR.md) 4. [Deployment strategy — English](10-core/deployment/DEPLOYMENT_STRATEGY_EN.md) or [stratégie de déploiement — français](10-core/deployment/STRATEGIE_DE_DEPLOIEMENT_FR.md) 5. [Corridor dossier strategy](00-control/CORRIDOR_DOSSIER_STRATEGY.md) 6. [Responsible international tenant governance](00-control/INTERNATIONAL_TENANT_GOVERNANCE.md) 7. [Plan de mobilisation internationale — français](10-core/strategy/PLAN_MOBILISATION_INTERNATIONALE_KRISTAL_FARMS_FR.md) 8. [Tenant-controlled encrypted environment — English](10-core/tenancy/BLACK_BOX_TENANCY_MODEL_EN.md) or [environnement chiffré sous contrôle du locataire — français](10-core/tenancy/MODELE_LOCATION_BLACK_BOX_FR.md) ### Application and data 1. [Application product vision](product/vision.md) 2. [Software & data platform architecture](architecture/overview.md) 3. [Information architecture](architecture/information-architecture.md) 4. [Kristal Farms domain principles](domain/kristal-farms-principles.md) 5. [Data model](data/data-model.md) 6. [Evidence model](data/evidence-model.md) 7. [Map observatory interaction](frontend/map-observatory-interaction.md) 8. [Layer catalog](frontend/layer-catalog.md) 9. [API overview](api/overview.md) 10. [Implementation plan](roadmap/implementation-plan.md) ### Mine infrastructure reuse and storage 1. [Mine reuse screening method](30-site-screening/mine-reuse/MINE_REUSE_SCREENING_METHOD.md) 2. [Underground compute / mine infrastructure reuse](30-site-screening/mine-reuse/UNDERGROUND_COMPUTE_REUSE.md) 3. [Mine-pit reservoir and pumped-storage research](30-site-screening/mine-reuse/MINE_RESERVOIR_PUMPED_STORAGE.md) 4. [Northern mine-reuse inventory](50-research/mines/NORTHERN_MINE_REUSE_INVENTORY.md) ### International tenancy and mobilization 1. [Plan de mobilisation internationale — français](10-core/strategy/PLAN_MOBILISATION_INTERNATIONALE_KRISTAL_FARMS_FR.md) 2. [Responsible international tenant governance](00-control/INTERNATIONAL_TENANT_GOVERNANCE.md) 3. [Tenant confidentiality boundary](security/TENANT_CONFIDENTIALITY_BOUNDARY.md) 4. [Tenant due-diligence runbook](operations/TENANT_DUE_DILIGENCE_RUNBOOK.md) 5. [International tenant landscape](50-research/commercial/INTERNATIONAL_TENANT_LANDSCAPE.md) ## Documentation authority The active authority order is defined in [Document Authority](00-control/DOCUMENT_AUTHORITY.md). In short: - current project-control documents govern intent and interpretation; - current project reference architecture governs the physical/commercial model; - source evidence governs factual claims within its actual scope; - assumptions remain assumptions; - archived material never silently overrides active state. ## Documentation philosophy The repository separates three kinds of active documentation: - **Normative:** rules the project data/software must obey. - **Descriptive:** how the current project/application implementation works. - **Decision records:** why a durable technical choice was made. Normative documents use terms such as **MUST**, **MUST NOT**, **SHOULD**, and **MAY** intentionally. ## Machine-readable contracts The `contracts/` directory contains schemas and policy files intended to be consumed by code, tests, CI and coding agents. Human documentation and machine contracts must remain consistent. ## Long-horizon material Optional human-infrastructure, learning and education concepts are isolated under [Long-Horizon Concepts](70-long-horizon/README.md). They are not prerequisites or commitments for the first energy/compute deployment. ================================================================================================ FILE: docs/product/explorer-data-contract.md AUTHORITY: reference ================================================================================================ # Explorer data contract ## Primary entity flows - select community → show marine/telecom/energy context and evidence; - select hydrometric station → show source/observations and related river; - select river → show evidence dimensions, monitoring station and contextual relations; - select external reference project → show role/status/source and linked context. ## API targets - `GET /catalog` - `GET /entities/{id}` - `GET /entities/{id}/evidence` - `GET /entities/{id}/screening` - `GET /search` - `GET /showcase/stories/kristal-farms-core-thesis` ## No implicit ranking List order defaults to name/type/relevance, never site merit. Marker size is not a merit signal. Evidence status is visually distinct from opportunity quality. ================================================================================================ FILE: docs/product/explorer.md AUTHORITY: reference ================================================================================================ # Explorer ## Purpose The Explorer is the professional workspace built on the same governed data used by the Showcase. ## Core capabilities - layer catalog; - dynamic legend; - search; - map selection; - filters; - temporal controls; - evidence panel; - metadata and provenance; - compare mode; - shareable URL state; - export/download subject to permissions. ## Evidence-first behavior Selecting a feature should reveal more than a popup. The primary inspector should answer: - What is this object? - Is it observed, referenced, hypothetical, or derived? - What sources support it? - When was it last verified? - What is unknown? - What data version is being viewed? ## Avoid - silent ranking; - traffic-light opportunity colors while ranking is disabled; - exact-looking markers for approximate locations; - derived capacity claims without methodology; - UI-only permission hiding. ## Observatory interaction language Explorer uses the shared [Map observatory interaction](../frontend/map-observatory-interaction.md) language: the map stays calm at rest, hover/focus performs lightweight recognition, and persistent selection opens the evidence-first Entity Inspector. Non-geometric relations are presented as UI relations rather than synthetic map geometry. ================================================================================================ FILE: docs/product/integrated-atlas.md AUTHORITY: reference ================================================================================================ # Integrated Atlas **Release date:** 2026-08-30 ## Purpose The integrated atlas connects hydrology, communities, marine logistics, telecom, energy references, environment context and screening state through canonical IDs, relations, evidence and observations. It does not force every piece of knowledge into map geometry. ## Current integrated content - 24 river references and 24 WSC hydrometric stations; - community reference points explicitly marked as approximate centroids where applicable; - conceptual research corridors with `geometry = NULL` and `not_route = true`; - Nunavik marine-management context without facility-specific heavy-lift inference; - operating/planned telecom relationships without invented cable geometry; - North Labrador ferry/service context without project-cargo certification; - selected external renewable-energy reference projects; - legacy environmental records retained only as unverified historical evidence. ## Public release Release `2026.08.30` is immutable and publishes only controlled public-safe context. Legacy screening tiers are not included in public community properties. ## Showcase / Explorer - `packages/catalog/catalog.json` defines the data-driven layer catalog; - `packages/showcase/story.json` defines the guided narrative without custom site logic; - `data/publish/current/` contains current public artifacts. ## Remaining gaps The atlas does not establish authoritative environment or rights/governance coverage for candidate projects. It also does not automatically materialize official river/basin geometry, full HYDAT flow series, project head, design flow, MW or site ranking. ================================================================================================ FILE: docs/product/scenario-studio.md AUTHORITY: reference ================================================================================================ # Scenario Studio Scenario Studio is a future analytical surface, not part of the minimum Showcase release. ## Principle A scenario is a controlled hypothesis over a known dataset version. It is never written back as observed truth. ## Initial scenario domains - generation capacity and profile; - priority community load; - reserve requirements; - storage; - compute minimum/maximum load; - curtailment/flexibility; - compute siting variant; - fibre assumptions; - optional heat reuse. ## Later domains - capex/opex; - hydrology; - construction logistics; - transmission/interconnection; - environmental constraints; - tariff/regulatory assumptions; - compute revenue models. ## UX The scenario UI should show assumptions next to outputs. It should be difficult to screenshot a result without also exposing that the result is scenario-derived. ================================================================================================ FILE: docs/product/showcase-data-contract.md AUTHORITY: reference ================================================================================================ # Showcase data contract The Showcase is configuration-driven through `packages/showcase/story.json`. Scenes select catalog layers and narrative keys; they do not contain custom site logic. Required interpretation rules: 1. existing remote systems are community infrastructure, not spare multi-MW compute supply; 2. marine/fibre context matters, but route/capacity claims require evidence; 3. WSC station points are monitoring assets, not dam sites; 4. missing geometry remains missing; 5. Kristal Farms architecture is explanatory: new generation → protected community interface → flexible compute → fibre; 6. economic frontier outputs are not project savings; 7. the final action opens the Explorer/Evidence Panel. The conceptual corridor illustration is a design reference only and is not a data source. ================================================================================================ FILE: docs/product/showcase.md AUTHORITY: reference ================================================================================================ # Showcase ## Purpose The Showcase is the public-first narrative mode of the Kristal Farms application. ## Characteristics - minimal persistent controls; - cinematic camera transitions; - selective use of terrain and globe; - synchronized map, diagrams, text, and key metrics; - progressive disclosure of technical detail; - a clear path into the professional Explorer. ## Recommended narrative structure 1. Northern energy context. 2. Remote communities and autonomous systems. 3. Existing renewable reference projects. 4. Constraint: existing grids are not assumed to provide multi-MW compute headroom. 5. Kristal Farms architecture: new generation → protected community interface → flexible compute → fibre. 6. Demonstration of evidence and open questions. 7. Transition to Explorer. ## Technical rule Showcase scenes are configuration-driven. Camera positions, active layers, narrative copy IDs, selected entities, and animation parameters should be stored in story configuration rather than hard-coded across page components. Example: ```yaml id: architecture-reveal camera: center: [-73.3, 58.4] zoom: 5.4 pitch: 48 layers: visible: - communities - reference_projects - conceptual_energy_flow focus_entity: REF-INNAVIK panel: architecture-intro ``` ## Observatory interaction language Showcase shares the [Map observatory interaction](../frontend/map-observatory-interaction.md) language with Explorer, but may use cinematic camera motion, temporary terrain/globe emphasis, and screen-space relation graphics. These effects must preserve evidence semantics and must not create synthetic geographic infrastructure. ================================================================================================ FILE: docs/reference/source-quality.md AUTHORITY: reference ================================================================================================ # Source quality Source quality is contextual, not a universal numeric truth. ## Useful classes Examples: - official regulator decision; - official utility planning filing; - official government dataset; - current operator asset page; - audited/company filing; - consultant report; - academic publication; - community/owner direction; - media report; - secondary aggregator. ## Rule Source class informs review and presentation but does not automatically determine whether a claim is true. Date, scope, methodology, and conflicts matter. ## Current research Controlled source IDs and quality labels are preserved in the canonical source/evidence model. Source descriptors remain attached through ingestion and publication rather than being flattened into map styling. ================================================================================================ FILE: docs/reference/status-enums.md AUTHORITY: reference ================================================================================================ # Status and enum reference This page summarizes baseline controlled vocabulary. Machine contracts remain authoritative where a schema exists. ## Data classification ```text public partner internal restricted ``` ## Project role ```text external_reference kristal_farms_candidate kristal_farms_project ``` ## Evidence verification ```text verified supported scoped unverified conflicting unknown ``` ## Scenario status ```text draft working shared archived ``` ## Scenario assumption source ```text user_input engineering_assumption derived evidence default ``` ## Compute siting variant ```text generation_side community_side split ``` New enum values require contract/schema review and migration consideration. ================================================================================================ FILE: docs/reference/units.md AUTHORITY: reference ================================================================================================ # Units ## Principle Store a numeric value with an explicit unit. Do not infer units from field names alone for generic observations. ## Preferred units Use SI units by default unless domain convention or source fidelity requires otherwise. Common canonical units: ```text Power: kW, MW Energy: kWh, MWh, GWh Distance: m, km Volume: L, m3 Mass: kg, t Emissions: kgCO2e, tCO2e Currency: explicit ISO currency + basis year when material Data rate: Mbps, Gbps, Tbps ``` ## Source fidelity Preserve original source unit in import metadata when conversion occurs. Record conversion method and avoid false precision. ## Percentages Store/display conventions must be explicit: `80%` should not ambiguously appear as numeric `80` in one system and `0.8` in another without schema definition. ================================================================================================ FILE: docs/scenarios/economic-method.md AUTHORITY: reference ================================================================================================ # Economic architecture method ## Question For the **same remote generation opportunity**, what enabling-infrastructure burden is associated with: A. long electrical export plus long road access; versus B. local digital-value export, initially represented by northern fibre funding-intensity proxies, with Kristal Farms-specific local infrastructure left explicitly unpriced? ## Evidence band The current model uses completed-project and public-program references for transmission, roads and northern fibre. These references are **not interchangeable unit construction costs** and are not promoted to site estimates. ## Frontier For each generic non-site stress case: `conventional_low = HV_km × transmission_low + road_km × road_low` `conventional_high = HV_km × transmission_high + road_km × road_high` `fibre_proxy_low/high = fibre_km × fibre_funding_proxy_low/high` `conservative remaining budget = conventional_low − fibre_proxy_high` `optimistic remaining budget = conventional_high − fibre_proxy_low` A positive value is **not savings**. It is only the remaining reference-component envelope available for still-unpriced Kristal Farms-specific infrastructure before parity on those compared components. ================================================================================================ FILE: docs/scenarios/engine-contract.md AUTHORITY: reference ================================================================================================ # Scenario engine contract ## Goal The scenario engine is independent of React and exposes deterministic, testable functions/services. ## Minimal inputs ```json { "generation_mw": 18, "community_priority_mw": 2.5, "reserve_mw": 1.0, "compute_min_mw": 0, "compute_max_mw": 14, "siting_variant": "generation_side" } ``` ## Minimal outputs Potential outputs: ```text annual_generation_mwh community_energy_mwh compute_energy_mwh compute_utilization curtailment_mwh storage_throughput_mwh heat_available_mwh_th constraint_events warnings ``` ## Mandatory dispatch rule Community priority load and required reserve constraints are satisfied before flexible compute whenever available generation/storage can do so. ## Validation rule Planning-margin observations cannot be used as a default source for `generation_mw` or `compute_max_mw`. ## Determinism Given the same scenario inputs, source datasets, model version, and deterministic settings, the engine should produce the same outputs. ================================================================================================ FILE: docs/scenarios/reproducibility.md AUTHORITY: reference ================================================================================================ # Scenario reproducibility Every saved evaluation must record enough context to reproduce it. ## Required metadata - scenario definition version; - canonical input values and units; - data release/snapshot ID; - model version; - policy version; - evaluation timestamp; - stochastic seed if any stochastic model is introduced; - warnings/errors. ## Model upgrades Do not overwrite historical results when the model changes. Re-evaluation creates a new result tied to the new model version. ## Exports Scenario exports should label outputs as modeled results and include assumptions plus version metadata. ================================================================================================ FILE: docs/scenarios/scenario-model.md AUTHORITY: reference ================================================================================================ # Scenario model ## Definition A scenario is an explicit hypothetical system configuration evaluated against a known dataset/model version. ## Core record ```text id name description owner/status geometry or linked place/site base_data_version model_version created_at updated_at metadata ``` ## Assumptions Each material assumption should carry: ```text parameter value unit source_type source/evidence reference when applicable notes ``` Source types: ```text user_input engineering_assumption derived evidence default ``` ## Initial system topology ```mermaid flowchart LR G[Generation] --> Bus[Protected community interface] Bus --> C[Priority community load] Bus --> S[Storage] Bus --> X[Flexible compute] X --> F[Fibre value export] X --> H[Optional heat reuse] ``` ## Siting variants ```text generation_side community_side split ``` No variant is globally preferred by the model. ================================================================================================ FILE: docs/security/TENANT_CONFIDENTIALITY_BOUNDARY.md AUTHORITY: reference ================================================================================================ # Tenant Confidentiality and Content-Blind Operations Boundary **Status:** Normative security/commercial boundary **Effective:** 2026-08-31 ## Purpose Kristal Farms is designed to operate shared physical infrastructure while tenants retain control of their private digital systems. The intended model is a **tenant-controlled encrypted environment**: the operator can run power, cooling, fibre, physical security and service telemetry without requiring routine access to tenant application content. The commercial shorthand **black-box tenancy** refers to this boundary. It does not mean an ungoverned facility, immunity from law, or absence of infrastructure telemetry. ## Trust boundary ### Kristal Farms-controlled plane Kristal Farms may control or operate, according to the service contract: - electrical service and metering; - curtailment interface; - cooling/service-water interfaces; - fibre handoff and shared network transport; - shared facility and perimeter security; - physical access coordination; - environmental, power and facility telemetry; - shared-infrastructure maintenance and incident response. ### Tenant-controlled plane The tenant controls, unless a separate managed-service agreement explicitly states otherwise: - server/accelerator configuration; - operating systems and hypervisors; - models and model weights; - datasets and databases; - prompts, application payloads and outputs; - tenant identities and application authorization; - encryption keys and secrets; - internal application logs and private workload telemetry. ## Content-blind-by-design controls Normal Kristal Farms operations **MUST NOT** require: - disclosure or escrow of tenant decryption keys; - routine access to plaintext application traffic; - routine inspection of tenant files, datasets, prompts, model weights or outputs; - installation of operator agents whose purpose is to inspect private application content; - covert content-monitoring or a standing decryption backdoor; - content inspection as the mechanism for enforcing commercial counterparty policy. If a tenant voluntarily shares content for support, that content becomes a separately controlled support artifact and must not be generalized into routine access rights. ## Operational telemetry that remains permitted Kristal Farms **MAY** process minimum necessary service telemetry, including: - power draw, voltage/current quality and energy state; - temperature, cooling demand, flow/pressure where applicable and environmental alarms; - physical-entry events and security-system alerts; - link state, aggregate bandwidth, routing/fault data and DDoS/security signals needed to protect shared infrastructure; - service availability, maintenance, billing and SLA records. Where network security controls are required, they SHOULD operate without decrypting tenant application payloads unless the tenant separately opts into a managed security service. ## Physical access A black-box tenancy may still require lawful and contractually defined physical access for life safety, fire response, electrical isolation, cooling failure, facility protection or agreed maintenance. Emergency physical intervention does not create a general right to access tenant logical systems or private content. Physical custody and logical access should be separated where practical. Access events should be logged and subject to role-based authorization. ## Cryptographic boundary Preferred design principles are: - tenant-generated or tenant-controlled keys; - no default Kristal Farms key escrow; - encryption in transit across shared networks; - encryption at rest for tenant-controlled storage where the tenant architecture supports it; - hardware-backed isolation/confidential-computing features where commercially appropriate; - documented key-recovery responsibility resting with the tenant unless a separate service explicitly changes that boundary. Kristal Farms must not market "zero knowledge" or "confidential computing" unless the actual implementation satisfies the technical meaning of those terms. The safer general description is **content-blind operations with tenant-controlled encryption**. ## Compliance boundary Kristal Farms performs **counterparty and jurisdictional due diligence** before and during the commercial relationship. It does not claim to validate the private substance of every computation. Compliance controls therefore rely on: - know-your-counterparty / beneficial-ownership review; - sanctions and trade-control screening; - contractual representations and covenants; - externally verifiable events and lawful notices; - facility/network abuse signals that do not require application-content decryption; - suspension/termination rights where contract or law permits. See `docs/00-control/INTERNATIONAL_TENANT_GOVERNANCE.md`. ## Legal requests When a valid legal request is received, Kristal Farms should: 1. validate authority and scope with legal counsel where appropriate; 2. identify what data Kristal Farms actually possesses or controls; 3. minimize disclosure to the legally required scope; 4. notify the tenant where legally permitted; 5. document the response; 6. avoid creating a persistent decryption capability that did not previously exist. This policy does not promise that a court, regulator or other lawful authority can never compel action. It promises that routine commercial operation does not depend on operator access to private tenant content. ## Incident response Tenant incidents and shared-infrastructure incidents must be distinguished. Kristal Farms is responsible for incidents within the shared-service boundary. A tenant remains responsible for incidents within its own systems unless a separate managed-service agreement says otherwise. Cross-boundary incident support should use the least access necessary and should be tenant-authorized except where immediate physical safety or binding law requires otherwise. ## Public wording Approved concise description: > **Kristal Farms operates the infrastructure. The tenant controls the compute.** Approved expanded description: > **Tenant environments are designed to remain encrypted and content-blind to routine Kristal Farms operations. Kristal Farms governs access to its infrastructure through counterparty due diligence and contract, not by inspecting private models, datasets or application content.** ================================================================================================ FILE: docs/security/threat-model.md AUTHORITY: reference ================================================================================================ # Threat model ## Assets to protect - restricted coordinates and infrastructure details; - partner/internal research sources; - user scenarios and annotations; - credentials/tokens; - data integrity/provenance; - public technical credibility. ## Representative threats ### Publication leakage Restricted fields/geometries accidentally included in public PMTiles or exports. Mitigation: explicit publish views, classification filters, release QA, artifact inspection. ### Authorization bypass User requests internal entity or export directly through API/tile endpoint. Mitigation: server-side authorization at every non-public service boundary. ### Data poisoning / incorrect import Automated research/import modifies canonical values incorrectly. Mitigation: raw/staging separation, provenance, review states, QA, immutable release history. ### Semantic misrepresentation A visualization turns planning margin into apparent compute capacity or hypotheses into facts. Mitigation: domain-policy tests, catalog semantics, inspector labels, ADR/policy enforcement. ### Credential exposure Secrets committed or exposed client-side. Mitigation: secret management, scanning, least-privilege roles, rotation procedures. ### Tenant confidentiality boundary failure Operator tooling, support access or incident response creates unnecessary access to private tenant models, datasets, payloads or keys. Mitigation: content-blind-by-design architecture, tenant-controlled keys, least-access support, physical/logical separation, access logging and no default key escrow. ### Counterparty-policy bypass A prohibited or unreviewed party obtains capacity through nominee ownership, undisclosed control, reseller/subtenant chains or material ownership changes. Mitigation: beneficial-ownership/effective-control review, sanctions/trade screening, contractual disclosure obligations, downstream eligibility controls and periodic re-review. ### False compliance assurance Kristal Farms marketing implies that private encrypted workloads have been inspected or certified as ethically compliant even though the service is intentionally content-blind. Mitigation: precise public wording, counterparty-based governance, explicit documentation of the visibility boundary and prohibition on unsupported workload-content claims. ================================================================================================ FILE: GOVERNANCE.md AUTHORITY: canonical ================================================================================================ # Repository governance ## Decision classes ### Product/data policy Examples: ranking permission, data classification, publication scope. These require explicit project governance and must be represented in versioned policy/configuration. ### Commercial counterparty governance International tenant, anchor-offtaker and tenant-operator eligibility is a project-governance decision. It must be represented in current C0 documentation and machine-readable policy. Counterparty screening applies before access and must remain separate from routine inspection of tenant private compute content. ### Architecture Durable technical choices are recorded as ADRs. ### Research/evidence Research claims require source/evidence records and may be superseded without deleting provenance. ## Maintainer responsibilities Maintainers are responsible for protecting architectural boundaries, reviewing public-data implications, and ensuring machine-readable contracts remain aligned with documentation. ## Ranking governance No maintainer or contributor may enable site ranking merely as a UI enhancement. Enabling ranking is a domain governance decision requiring methodology and a policy change. ## Tenant governance The current owner-directed policy excludes United States-based or United States-controlled counterparties from tenant, anchor-offtaker and tenant-operator roles. Other jurisdictions default to enhanced due diligence unless an explicit schedule says otherwise. A technology-origin embargo must not be inferred from this counterparty rule. Black-box tenancy is content-blind by design: governance is based on counterparty identity/control, sanctions/trade review, contract and external evidence rather than decryption of private tenant workloads. ## Founder/owner project direction Owner/founder direction may establish intended project strategy but does not become external evidence merely by being recorded. Direction from the founder and sole member of Initiative kOA should be preserved under `sources/owner-direction/` and translated into controlled project documents with explicit evidence gates. ## International resilience governance A diversified international tenant portfolio is an allowed resilience objective. Documentation must distinguish **commercial/diplomatic stakeholder diversification** from a military alliance or state security guarantee. No contributor may claim that foreign tenancy creates extraterritoriality, collective defence, automatic government intervention or immunity from Canadian law without explicit authoritative evidence. ================================================================================================ FILE: ORCHESTRATION.md AUTHORITY: canonical ================================================================================================ # Repository Orchestration Kristal Farms work follows a controlled chain from evidence to project decisions. ## Core chain **Source → research → reproducible pipeline → evidence/observation → validation → canonical data → decision gate → publishable release → product** The repository uses a directional dependency rule: ```text research/ -> pipelines/data/contracts/packages -> apps/services ``` `apps/` and `services/` must not execute exploratory research or ETL code at runtime. Community, Indigenous rights, environmental review, engineering, logistics, telecom and economics are independent evidence domains. No single technical layer can silently override the others. ## Working loop 1. Review open decisions and evidence gaps. 2. Update the relevant corridor or domain dossier. 3. Preserve source provenance and uncertainty. 4. Run automated validation and tests. 5. Promote only reviewed data into canonical/current state. 6. Regenerate publishable views from canonical data. 7. Review security, rights, privacy and public-release implications. 8. Record material architecture decisions in ADRs. ## Release gates A public or partner-facing release should not ship unless: - project scope and terminology are current; - numeric claims retain source/as-of context; - approximate, conceptual and verified geometry are visually distinct; - external references are not presented as Kristal Farms projects; - screening remains unranked unless governance explicitly changes that policy; - restricted data is excluded before artifact generation; - site-specific claims are no stronger than the underlying evidence; - current documentation, machine-readable contracts and publish outputs agree. See `docs/00-control/` and `docs/adr/`. ## Windows post-update due process `REBUILD_OBSERVATORY.pyw` is the canonical local post-update launcher. A successful run means governed publishers completed, the Python test suite passed, the TypeScript typecheck passed, the Next.js production build passed, and the development Observatory was health-checked before browser launch. Generated caches may be cleaned automatically; source data, `.venv`, `node_modules`, and Git history are never part of that cleanup. `START_OBSERVATORY.bat` is intentionally a quick-start path and does not substitute for post-update validation. ## Repository information architecture Project/domain authority is organized in the numbered documentation families, while software/data-platform implementation is organized by responsibility (`docs/architecture`, `docs/data`, `docs/product`, `docs/frontend`, `docs/api`, `docs/scenarios`). Historical material under `archive/` is provenance only and is excluded from default local search/index behavior. Specialist utilities live under `tools/`; the root retains only canonical launchers and repository-level control files. ================================================================================================ FILE: RELEASE_MANIFEST.json AUTHORITY: canonical ================================================================================================ { "project": "Kristal Farms", "release": "2026.08.30", "status": "research foundation / unranked screening", "canonical_repository": "kristal-farms", "operational_data_model": "PostgreSQL + PostGIS", "public_surfaces": [ "Showcase", "Explorer" ], "scenario_surface": "Scenario Studio", "ranking_allowed": false, "notes": [ "No site is selected by this release.", "Public geometry and evidence retain provenance and confidence semantics.", "Project-specific engineering and economics belong in corridor/site dossiers.", "Mine infrastructure reuse and mine-pit pumped storage are exploratory research only; no mine is selected.", "Historical/old open-pit mines remain eligible for reservoir screening; recent closure is only a research preference for preserved underground/industrial infrastructure." ] } ================================================================================================ FILE: SECURITY.md AUTHORITY: canonical ================================================================================================ # Security policy ## Reporting Do not disclose security vulnerabilities or restricted-data exposures through public issue content. Use the project's designated private security reporting channel once configured in the GitHub repository. ## Security-sensitive areas Particular attention is required for: - restricted geospatial data; - partner/internal source documents; - database credentials; - OIDC configuration; - public artifact generation; - export/download authorization; - scenario privacy; - tenant confidentiality and cryptographic separation; - provider/tenant logical-access boundaries; - due-diligence records containing ownership/control or compliance information. See [Security architecture](docs/architecture/security.md) and [Tenant Confidentiality Boundary](docs/security/TENANT_CONFIDENTIALITY_BOUNDARY.md).