Document Affective Dynamics and the public Lab

README.md

@@ -16,9 +16,9 @@ mint dev --no-open --port 3333
 
 The live site deploys from this repository.
 
-Keep the site concise. Generated reference, SDK, Webhook and MCP pages follow reviewed versioned contracts.
+Keep the site concise. Generated reference, SDK, Webhook and MCP pages follow reviewed versioned definitions and compatibility policies.
 
-`openapi/heyrafiki.openapi.yaml` is the published API contract. Narrative pages explain it and never redefine it.
+`openapi/heyrafiki.openapi.yaml` is the published API definition. Narrative pages explain it and never redefine it.
 
 ## License
 

changelog.mdx

@@ -1,20 +1,29 @@
 ---
 title: "API changelog"
 description: "Released changes to the Heyrafiki API."
 keywords: ["Heyrafiki API changelog", "API releases", "OpenAPI changes"]
 rss: true
 ---
 
 Released API changes appear here. Product and website changes are on the [Heyrafiki changelog](https://heyrafiki.space/changelog).
 
+<Update label="20 August 2026" description="Public SDK betas and research tools" tags={["Published", "SDKs"]}>
+**Published** the JavaScript, Python, Go and Rust SDK public betas through their
+standard registries, joining the existing .NET beta. See [SDKs](/sdks) for
+version-pinned install commands and source repositories.
+
+**Added** the [Affective Dynamics guide](/research/affective-dynamics) and the
+public [Heyrafiki Lab](https://heyrafiki.space/resources/lab).
+</Update>
+
 <Update label="14 August 2026" description="API surface map" tags={["Documented", "Reference"]}>
-**Documented** the complete [API overview](/resources) as eight resource areas and 31 released operations. The generated endpoint reference and public contract remain the operation-level authorities.
+**Documented** the complete [API overview](/resources) as eight resource areas and 31 released operations. The generated endpoint reference and public API definition remain the operation-level authorities.
 </Update>
 
 <Update label="14 August 2026" description="Research evidence paths" tags={["Added", "Evidence"]}>
-**Added** a [research and evidence guide](/research/evidence) connecting public statements to the OpenAPI contract, Assurance Graph, synthetic fixtures, deterministic runners and stated limitations.
+**Added** a [research and evidence guide](/research/evidence) connecting public statements to the OpenAPI definition, Assurance Graph, synthetic fixtures, deterministic runners and stated limitations.
 
-**Added** the Stage 1 Assurance Graph protocol manuscript, prior-art search record and independent reviewer packet. The candidate is evaluated against five progressively stronger baselines before results are published.
+**Added** the Assurance Graph comparative protocol, manuscript, prior-art search record and independent reviewer packet.
 
 **Documented** First Light v2 as reproducible synthetic conformance evidence. It does not establish clinical validity or population effectiveness.
 </Update>

concepts/capabilities.mdx

@@ -1,14 +1,14 @@
 ---
 title: "Platform capabilities"
-description: "The resource families and contracts that make up the Heyrafiki Platform."
+description: "The resource families and interfaces that make up the Heyrafiki Platform."
 keywords: ["platform capabilities", "typed capabilities", "healthcare API architecture"]
 ---
 
-The public contract grows by capability. Generated endpoint pages remain the authority for callable operations.
+The public API grows by capability. Generated endpoint pages remain the authority for callable operations.
 
 ## Sandbox resources
 
-| Capability | Contract |
+| Capability | Interface |
 | --- | --- |
 | API discovery | Environment and available resource families |
 | Practitioner discovery | List and retrieve synthetic Practitioner profiles |
@@ -19,11 +19,12 @@
 
 ## Developer surfaces
 
-| Capability | Contract |
+| Capability | Interface |
 | --- | --- |
 | JavaScript SDK | Typed client and shared conformance fixtures |
 | Webhooks | Versioned events, signing, replay protection and bounded retries |
 | MCP | Thirteen read-only, scope-checked sandbox tools |
+| Public Lab | Browser-based tools using example data and published research boundaries |
 
 ## Resource families
 
@@ -35,4 +36,4 @@
 - Organizations, Insurers and network operations
 - Standards-based healthcare and reporting adapters
 
-Endpoint, event, package and tool behavior is governed by its versioned contract.
+Endpoint, event, package and tool behavior follows its versioned definition and compatibility policy.

docs.json

@@ -146,7 +146,7 @@
           },
           {
             "group": "Research and evidence",
-            "pages": ["research/evidence"]
+            "pages": ["research/evidence", "research/affective-dynamics"]
           }
         ]
       },

index.mdx

@@ -1,11 +1,11 @@
 ---
 title: "Mental Healthcare infrastructure"
 sidebarTitle: "Introduction"
 description: "Build Care, Cover and Claims workflows through the Heyrafiki API."
 keywords: ["Mental Healthcare API", "health insurance API", "Heyrafiki API"]
 ---
 
-The Heyrafiki API connects Practitioner discovery, Bookings, Benefits, Sessions, Claims, remittance and Webhooks through versioned REST contracts.
+The Heyrafiki API connects Practitioner discovery, Bookings, Benefits, Sessions, Claims, remittance and Webhooks through one versioned REST interface.
 
 Use the Sandbox to build complete integrations.
 
@@ -40,7 +40,7 @@
   </Card>
 </CardGroup>
 
-## Start with the contract
+## Start with the API
 
 <CardGroup cols={2}>
   <Card title="Authentication" icon="key" href="/authentication">

research/affective-dynamics.mdx

@@ -0,0 +1,107 @@
+---
+title: "Affective Dynamics"
+description: "Understand Heyrafiki's consent-governed approach to longitudinal affective context, example data and Practitioner review."
+keywords: ["Affective Dynamics", "longitudinal mental health data", "experience sampling", "Practitioner review"]
+---
+
+Affective Dynamics describes how repeated affective observations change over
+time. Heyrafiki uses it to organise longitudinal context for a Person and their
+Practitioner. It does not make a Diagnosis or decide what a pattern means.
+
+## Start with the public tools
+
+- [Use the browser Lab](https://heyrafiki.space/resources/lab#affective-dynamics)
+  to move example check-ins and see the descriptive summary change.
+- [Read the research note](https://heyrafiki.space/resources/articles/affective-dynamics-what-change-can-and-cannot-tell-us)
+  for the scientific basis and limitations.
+- [Run the public protocol](https://github.com/heyrafiki/proving-ground/tree/main/research/affective-dynamics)
+  for synthetic edge cases, expected boundaries and the reviewer checklist.
+
+## What the view describes
+
+| Description | Question it answers | Important limit |
+| --- | --- | --- |
+| Average | Where are the observations centred in this window? | The Instrument, window and missing observations affect the value. |
+| Variation | How spread out are the observations? | Variation does not preserve temporal order. |
+| Direction | Does the available sequence move up or down over elapsed time? | A short cluster is not treated as a trajectory. |
+| Successive change | How much do adjacent observations differ after accounting for elapsed time? | The summary does not identify a cause. |
+| Inertia | How strongly does one observation predict the next? | The value is withheld when intervals are irregular or variance is zero. |
+| Return | Does the sequence return toward its declared reference range? | If the return is not observed, the duration remains unresolved. |
+
+## Evidence carried with each observation
+
+Each observation keeps the fields needed to decide whether it is comparable
+and eligible for the requested purpose:
+
+- dimension identifier and version;
+- value and declared scale;
+- observed time and recorded time;
+- Consent reference and version;
+- source and source version;
+- quality state and weight; and
+- optional context references that do not contain Session content.
+
+The original observations, computed description and Practitioner
+interpretation remain separate records.
+
+## When a measure is withheld
+
+The view returns a clear empty or not-interpretable state when:
+
+- too few eligible check-ins are available;
+- the available period is too short;
+- timing is too irregular for lag-one autocorrelation;
+- the series has no variance;
+- no return is observed inside the available window;
+- Consent does not permit the read; or
+- the request crosses an Organization boundary.
+
+No missing observation is silently filled in.
+
+## Time and reconstruction
+
+`observed_at` records when an observation applied. `recorded_at` records when
+the system learned it. A read at a knowledge cutoff includes only observations
+whose `recorded_at` value is at or before that cutoff. This allows a reviewer to
+reconstruct what the system could have shown at that time.
+
+## Access and review
+
+| Audience | Access boundary |
+| --- | --- |
+| Person | May read their own consented view. |
+| Practitioner | May read a shared Client view inside an active Care relationship and record a separate review. |
+| Researcher | May use only an approved protocol, research scope and eligible de-identified data. |
+| System | May run committed synthetic fixtures for conformance testing. |
+
+The public Lab uses example data. The authenticated Platform preview remains
+feature-gated, and Affective Dynamics is not currently a public REST resource.
+Use the Proving Ground protocol for integration-independent evaluation.
+
+## Reproduce the public boundary
+
+```bash
+git clone https://github.com/heyrafiki/proving-ground.git
+cd proving-ground
+npm ci
+npm run test:affective-dynamics
+```
+
+The check validates nine synthetic case families, the declared comparators and
+the protocol's failure boundaries. Population, language and Instrument-specific
+clinical studies require their own approved protocol.
+
+## Published sources
+
+- [Jahng, Wood and Trull (2008)](https://doi.org/10.1037/a0014173) on
+  variability, temporal dependency and successive differences.
+- [Kuppens, Allen and Sheeber (2010)](https://doi.org/10.1177/0956797610372634)
+  on emotional inertia.
+- [Houben, Van Den Noortgate and Kuppens (2015)](https://doi.org/10.1037/a0038822)
+  on short-term emotion dynamics and well-being.
+- [Dejonckheere and colleagues (2019)](https://doi.org/10.1038/s41562-019-0555-0)
+  on incremental value beyond mean and variance.
+- [McNeish and colleagues (2021)](https://doi.org/10.1080/10705511.2021.1915788)
+  on measurement in intensive longitudinal data.
+- [Schneider and colleagues (2023)](https://doi.org/10.3758/s13428-022-01995-1)
+  on reliability and sampling error in within-person dynamics.

research/evidence.mdx

@@ -1,15 +1,15 @@
 ---
 title: "Research and evidence"
-description: "Follow Heyrafiki statements to public contracts, executable evidence and explicit research limitations."
+description: "Follow Heyrafiki statements to public API definitions, executable evidence and explicit research limitations."
 keywords: ["mental health research evidence", "reproducible conformance", "First Light", "Assurance Graph"]
 ---
 
-Heyrafiki publishes the evidence that another team can inspect and run. The public path starts with a defined statement and ends with a versioned contract, synthetic fixture, expected result, deterministic runner and visible limitation.
+Heyrafiki publishes evidence that another team can inspect and run. The public path starts with a defined statement and ends with a versioned definition, synthetic fixture, expected result, deterministic runner and visible limitation.
 
 ```mermaid
 flowchart LR
-    Statement["Defined statement"] --> Contract["Versioned contract"]
-    Contract --> Fixture["Synthetic fixture"]
+    Statement["Defined statement"] --> Definition["Versioned definition"]
+    Definition --> Fixture["Synthetic fixture"]
     Fixture --> Expected["Expected result"]
     Expected --> Runner["Deterministic runner"]
     Runner --> Limitation["Stated limitation"]
@@ -19,12 +19,12 @@
 
 | Authority | What it owns | Inspect it |
 | --- | --- | --- |
-| Contract | The public REST surface and machine-readable Assurance Graph | [heyrafiki/contract](https://github.com/heyrafiki/contract) |
+| API definition | The public REST interface and machine-readable Assurance Graph | [heyrafiki/contract](https://github.com/heyrafiki/contract) |
 | Proving Ground | Deterministic conformance suites, fixtures and expected results | [heyrafiki/proving-ground](https://github.com/heyrafiki/proving-ground) |
 | Docs | Integration guidance and the meaning of released public behavior | [heyrafiki/docs](https://github.com/heyrafiki/docs) |
-| SDK repositories | Language-specific source maintained against the public contract | [SDK guide](/sdks) |
+| SDK repositories | Language-specific source maintained against the public API definition | [SDK guide](/sdks) |
 
-The Platform implementation remains the authority for runtime behavior. Public repositories make contracts and selected evidence independently inspectable without becoming a second runtime authority.
+The Platform implementation remains the authority for runtime behavior. Public repositories make API definitions and selected evidence independently inspectable without becoming a second runtime authority.
 
 ## First Light v2
 
@@ -56,34 +56,34 @@
 
 ## What the current evidence supports
 
-The public suites support claims about contract coverage, deterministic scoring, bitemporal replay, Consent-aware access boundaries, audit completeness and rejection of declared adversarial mutations.
+The public suites support claims about API coverage, deterministic scoring, bitemporal replay, Consent-aware access boundaries, audit completeness and rejection of declared adversarial mutations.
 
 Separate clinical and population studies are required for:
 
 - clinical validity or diagnostic performance;
 - effectiveness for a Kenyan or other real population;
 - actuarial savings or health outcomes;
 - safety under every production condition;
-- scientific priority or patentability.
+- claims beyond the declared protocol and evidence.
 
 Those conclusions require a separate protocol, appropriate approvals, licensed instruments, representative data, baseline methods, uncertainty estimates and expert review.
 
 ## From architecture to a research result
 
 A research candidate is ready for formal evaluation only when its problem, assumptions, prior art, baseline, protocol, measures, data rights, failure implications and review owner are written down before outcome claims are made.
 
-The [Assurance Graph](/institutions/assurance-graph) provides the traceability layer. It connects public operations and controls to executable evidence. Scientific priority is evaluated separately through the comparative protocol and independent review.
+The [Assurance Graph](/institutions/assurance-graph) provides the traceability layer. It connects public operations and controls to executable evidence. Comparative research follows its declared protocol and independent review.
 
-### Candidate under comparative review
+### Comparative evaluation
 
-The current candidate tests a two-cutoff, Consent-conditional assurance-path query with fail-closed completeness. The protocol is in Stage 1 independent review. Results follow protocol freeze, comparative evaluation and independent reproduction.
+The public protocol tests a two-cutoff, Consent-conditional assurance-path query with fail-closed completeness. It declares the comparators, measures, stopping rules and independent review path before evaluation.
 
 <CardGroup cols={2}>
   <Card title="Read the evaluation protocol" icon="list-check" href="https://github.com/heyrafiki/proving-ground/blob/main/research/consent-aware-bitemporal-assurance-graph/protocol.md">
     Review the formal query, five baselines, fixed measures and stopping rules.
   </Card>
-  <Card title="Read the Stage 1 manuscript" icon="file-lines" href="https://github.com/heyrafiki/proving-ground/blob/main/research/consent-aware-bitemporal-assurance-graph/manuscript.md">
-    Inspect the article structure before any result is collected.
+  <Card title="Read the manuscript" icon="file-lines" href="https://github.com/heyrafiki/proving-ground/blob/main/research/consent-aware-bitemporal-assurance-graph/manuscript.md">
+    Inspect the article structure and declared evidence boundary.
   </Card>
   <Card title="Inspect the prior-art search" icon="magnifying-glass-chart" href="https://github.com/heyrafiki/proving-ground/blob/main/research/consent-aware-bitemporal-assurance-graph/prior-art-search.md">
     See the closest standards, papers and patent families found by the author search.
@@ -95,4 +95,4 @@
 
 ## Reporting a mismatch
 
-If a public statement, contract, fixture or result disagrees with another authority, open an issue in the repository that owns the mismatched artifact. Security and privacy findings should follow the private process in the [Security overview](/security/overview).
+If a public statement, API definition, fixture or result disagrees with another authority, open an issue in the repository that owns the mismatched artifact. Security and privacy findings should follow the private process in the [Security overview](/security/overview).