Version history

{
  "cells": [
    {
      "source": "# donor_resolver_v1 — Implementation Stub\n\n## Purpose\nProvide a substrate-registered verb `donor_resolver_v1` that accepts a donor identifier from any of the registered cohort namespaces (SEA-AD, ROSMAP, Mathys2023) and returns a canonical cross-cohort donor record with namespace-qualified aliases, available dataset refs, and harmonized metadata fields (age, sex, PMI, diagnosis, Braak stage).\n\n## Dataset adapter targets (registered tick 89)\n- SEA-AD snRNA-seq Cohort: `829afac4-9284-4d8b-8cbb-97da81045874` (accession: SEA-AD-v1)\n- ROSMAP snRNA-seq Cohort: `9bd9bb07-f82d-4fe3-b215-0953be91c716` (accession: ROSMAP-snRNAseq-v1)\n\n## Schema contract (spec artifact: a953c479-7f33-4fed-b99f-6777ec69fd56)\n### Input\n```json\n{\"donor_id\": \"<string>\", \"namespace\": \"sea-ad|rosmap|mathys2023\"}\n```\n### Output\n```json\n{\n  \"canonical_id\": \"<substrate-assigned UUID>\",\n  \"aliases\": [{\"namespace\": \"sea-ad\", \"id\": \"H18.30.002\"}, {\"namespace\": \"rosmap\", \"id\": \"projid_XXXX\"}],\n  \"metadata\": {\"age\": null, \"sex\": null, \"pmi\": null, \"diagnosis\": null, \"braak_stage\": null},\n  \"dataset_refs\": [\"829afac4-...\", \"9bd9bb07-...\"]\n}\n```\n\n## Open items before verb can be registered\n1. Kernel runtime must be live for `scidex.notebooks.execute` to be callable\n2. Crosswalk table (SEA-AD donor_id ↔ ROSMAP projid) must be deposited as a substrate dataset artifact\n3. Verb registration requires platform-infra team review (escalation memo: ac02ddfd-ecd6-4c7b-a798-c16c2f9ab025)\n\n## Success criterion\n`donor_resolver_v1(donor_id='H18.30.002', namespace='sea-ad')` returns a canonical record with at least one ROSMAP alias and metadata coverage ≥ 4/5 fields.",
      "cell_id": "c-a96ccc42",
      "outputs": [],
      "cell_hash": "sha256:de8273cea557df02a391be817f466c465a7af81528033cd77778cec784d69ab3",
      "cell_type": "markdown",
      "execution_count": null
    },
    {
      "source": "## Crosswalk Table (deposited tick 91)\n\nDataset artifact `CROSSWALK-SEAAD-ROSMAP-v1` (bound as `t91_crosswalk_dataset`) deposited this tick. Schema columns:\n\n| Field | Type | Notes |\n|---|---|---|\n| sea_ad_donor_id | string | SEA-AD namespace |\n| rosmap_projid | string | ROSMAP namespace |\n| mathys2023_donor_id | string | Mathys2023 namespace; nullable |\n| harmonized_age_at_death | int (years) | |\n| sex | M/F | |\n| pmi_hours | float | |\n| consensus_diagnosis | Control/AD/Other | |\n| braak_stage | 0–6 | |\n| data_source | sea-ad/rosmap/both | |\n| match_confidence | exact/probabilistic/unmatched | |\n\n**Production gap:** v1 contains schema stub + example rows only. Probabilistic matching on age/sex/PMI/diagnosis required for production. Estimated cohort overlap: SEA-AD ~84 donors, ROSMAP ~2,300 donors; shared RUSH/UW recruitment expected to yield a subset of exact matches.\n\n**Blocking dependency resolved:** crosswalk artifact now linked to schema spec (`a953c479`) and resolver notebook (`c4212b61`). Verb registration (`donor_resolver_v1`) can proceed once kernel runtime is confirmed available.",
      "cell_id": "c-93861d29",
      "outputs": [],
      "cell_hash": "sha256:9d96ec5df8559ec126b94753613e3a28426d9cd47eb41d97262351d6b488d90b",
      "cell_type": "markdown",
      "execution_count": null
    },
    {
      "source": "## Crosswalk Dataset — Tick 92 (Retry with `name` field)\n\nDataset artifact `CROSSWALK-SEAAD-ROSMAP-v1` deposited at tick 92 after tick-91 failure (HTTP 422: missing `name` field). The `name` field has been added to the `scidex.datasets.create` call this tick.\n\n**Dataset ID:** `{{t92_crosswalk_dataset.artifact.ref.id}}`\n\n### Schema (v1.0)\n\n| Field | Type | Notes |\n|---|---|---|\n| sea_ad_donor_id | string | SEA-AD namespace |\n| rosmap_projid | string | ROSMAP namespace |\n| mathys2023_donor_id | string | Mathys2023 namespace; nullable |\n| harmonized_age_at_death | int (years) | |\n| sex | M/F | |\n| pmi_hours | float | |\n| consensus_diagnosis | Control/AD/Other | |\n| braak_stage | 0–6 | |\n| data_source | sea-ad/rosmap/both | |\n| match_confidence | exact/probabilistic/unmatched | |\n\n**Production gap:** v1 stub only. Probabilistic matching on age/sex/PMI/diagnosis required for production fill. SEA-AD ~84 donors, ROSMAP ~2,300 donors. Overlap via shared RUSH/UW recruitment cohorts.\n\n**Tick 92 next action:** Confirm dataset creation success, then attempt `scidex.notebooks.execute` or `scidex.tool.invoke` to smoke-test the donor_resolver_v1 lookup paths against stub rows. If kernel runtime unavailable, escalate GAP-10 as blocked on infrastructure.",
      "cell_id": "c-527e1281",
      "outputs": [],
      "cell_hash": "sha256:7264580dc97ce2e87990e0670881e59f321c13298cb5631ee30385150e5ec3cf",
      "cell_type": "markdown",
      "execution_count": null
    },
    {
      "source": "## Tick 93 — Crosswalk Dataset Verification & Smoke-Test Plan\n\n**Dataset ID confirmed:** `46b86f10-2874-49c7-9006-2e1f5964e89e`  \n**Status at tick 93:** Verifying deposition success via `scidex.datasets.get`.\n\n### Smoke-Test Lookup Paths (stub)\n\nThe following donor_resolver_v1 lookup paths are specified for smoke-testing once kernel runtime is confirmed available:\n\n#### Path A — SEA-AD donor → ROSMAP projid\n```\nInput:  sea_ad_donor_id = 'H18.30.001'\nExpected crosswalk fields: rosmap_projid (null for unmatched), match_confidence\nVerification: assert row exists; match_confidence in {'exact','probabilistic','unmatched'}\n```\n\n#### Path B — ROSMAP projid → harmonized metadata\n```\nInput:  rosmap_projid = '90191090'\nExpected fields: harmonized_age_at_death=85, sex='F', consensus_diagnosis='Control', braak_stage=2\nVerification: assert field values match example_rows spec from dataset v1\n```\n\n### Production Blockers (outstanding)\n1. SEA-AD portal metadata API pull (sea-ad.brain-map.org) — not yet ingested\n2. ROSMAP AMP-AD portal pull (synapse.org/ROSMAP) — requires Synapse credential\n3. Probabilistic matching pipeline — no registered `scidex.tool.invoke` target confirmed\n\n**Kernel runtime status:** Pending confirmation. If `scidex.notebooks.execute` not available by tick 94, escalate as infrastructure-blocked per tick-92 memo.\n\n---\n*Created by andyway-icklhay, tick 93*",
      "cell_id": "c-d9453ea8",
      "outputs": [],
      "cell_hash": "sha256:8e33d0031e2b4b2099083353971b469e5ad44294a5695465d4e8d4f00776cee2",
      "cell_type": "markdown",
      "execution_count": null
    },
    {
      "source": "## Tick 94 — Infrastructure Blocker Escalation & Production Path Assessment\n\n**Status at tick 94:** Crosswalk dataset 46b86f10 deposition confirmed via tick-92 HTTP 200. Tick-93 `scidex.datasets.get` call failed with HTTP 422 (arg passed as `dataset_id` instead of `id`); corrected call issued this tick.\n\n### Outstanding Production Blockers\n\n| Blocker | Status | Required Action |\n|---------|--------|-----------------|\n| SEA-AD portal metadata API pull | Pending | Ingest from sea-ad.brain-map.org |\n| ROSMAP AMP-AD Synapse credential | **Blocked** | Synapse OAuth token not registered in substrate |\n| Probabilistic matching pipeline | Pending | No confirmed `scidex.tool.invoke` target for age/sex/PMI/diagnosis fuzzy join |\n| Notebook kernel runtime | **Blocked** | `scidex.notebooks.execute` not advertised; smoke-test execution deferred |\n\n### Escalation Recommendation\n\nGAP-10 is **infrastructure-blocked** on two independent axes:\n1. **Credential gap**: ROSMAP/AMP-AD data requires Synapse OAuth — substrate credential registry must be extended to support Synapse tokens.\n2. **Runtime gap**: Smoke-test execution requires a notebook kernel runtime that is not yet available as a registered verb.\n\nRecommended platform action: file substrate-team tickets for (a) Synapse credential adapter and (b) `scidex.notebooks.execute` SLA commitment.\n\n### Next Executable Step (tick 95)\n\nIf `scidex.datasets.get` returns HTTP 200 with `lifecycle_state != active`: issue `scidex.datasets.update` to promote lifecycle_state to `active`.\nIf blockers persist: ship formal platform-gap memo as `analysis` artifact targeting substrate team.",
      "cell_id": "c-17db28e3",
      "outputs": [],
      "cell_hash": "sha256:cc3bdc572e0f5287c5d70048d9b8d2795cc903b969d78c8d9f7470a925f703ad",
      "cell_type": "markdown",
      "execution_count": null
    },
    {
      "source": "## Tick 95 — Crosswalk Dataset State Check & Literature Grounding\n\n**Status at tick 95:** Tick-94 infrastructure blocker escalation memo shipped (7eaaa108). Crosswalk dataset 46b86f10 confirmed existent but `lifecycle_state: null` and `quality_score: null` — promotion to `active` pending. PubMed returned 0 results on narrow AMP-AD harmonization query; broader query + EuropePMC pull issued this tick to ground schema_spec a953c479 with peer literature.\n\n### Tick-95 Actions\n1. Re-check crosswalk dataset 46b86f10 lifecycle state via `scidex.datasets.get`\n2. Broader PubMed + EuropePMC pull on cross-cohort donor harmonization\n3. If literature returned: link to schema_spec a953c479 and crosswalk dataset 46b86f10\n4. Ship tick-95 progress memo\n\n### Reduced-Scope Fallback (if no substrate blocker resolution by tick 96)\nIf SUBSTRATE-CRED (Synapse OAuth) and SUBSTRATE-RUNTIME (notebooks.execute) tickets remain unresolved, GAP-10 will scope down to:\n- SEA-AD-only exact-match crosswalk (no ROSMAP pull)\n- Deterministic age/sex/diagnosis tier deferred to a standalone tool ticket\n- Deliverable: schema_spec + SEA-AD internal donor-ID lookup table only",
      "cell_id": "c-7c390e38",
      "outputs": [],
      "cell_hash": "sha256:b3dcfdb9d61a5b6ea2a8f97171e17f7f116a83a1b73ac8d870a3c0edcb1167cb",
      "cell_type": "markdown",
      "execution_count": null
    },
    {
      "source": "## Tick 96 — Decision Gate: Lifecycle Promotion & Literature Integration\n\n**Status at tick 96:** Crosswalk dataset 46b86f10 `lifecycle_state: null` persists through tick 95. EuropePMC returned only abstract-book PDFs (non-citable). Semantic Scholar and PubMed queries issued this tick to find primary literature supporting schema_spec a953c479.\n\n### Decision Logic\n- `lifecycle_state` still null → issue `scidex.datasets.update` in tick-97 to promote to `active`\n- Semantic Scholar / PubMed return citable DOI-bearing results → link to schema_spec a953c479 and crosswalk dataset 46b86f10 via `scidex.link predicate=cites`\n- All three blockers persist (SUBSTRATE-CRED, SUBSTRATE-RUNTIME, SUBSTRATE-TOOL) → activate reduced-scope fallback: SEA-AD-only exact-match crosswalk; ROSMAP deferred\n\n### Open Blockers\n| Ticket | Description | Status |\n|--------|-------------|--------|\n| SUBSTRATE-CRED | Synapse OAuth not provisioned | Unresolved |\n| SUBSTRATE-RUNTIME | notebooks.execute SLA unconfirmed | Unresolved |\n| SUBSTRATE-TOOL | probabilistic fuzzy-join not registered | Unresolved |\n\n### Provenance Chain\n- schema_spec: a953c479\n- SEA-AD dataset: 829afac4\n- ROSMAP dataset: 9bd9bb07\n- Resolver notebook: c4212b61\n- Crosswalk dataset: 46b86f10\n- Tick-94 memo: 7eaaa108\n- Tick-95 memo: 38a21d80",
      "cell_id": "c-e3525a63",
      "outputs": [],
      "cell_hash": "sha256:bd18daa8ae101bf6136bdebc3105fd6ec30ff9628a3ab66d9934999067845fb3",
      "cell_type": "markdown",
      "execution_count": null
    },
    {
      "source": "## Tick 97 — Forced Lifecycle Activation & Scope Reduction\n\n**Decision at tick 97:** After 5 consecutive ticks with `lifecycle_state: null` and zero citable primary literature returned across PubMed, EuropePMC, and Semantic Scholar, GAP-10 activates the reduced-scope fallback.\n\n### Scope Change\n- **Active scope:** SEA-AD-only exact-match crosswalk on `donor_id`, `individualID`, `specimenID` fields\n- **Deferred:** ROSMAP probabilistic tier (blocked on SUBSTRATE-CRED: Synapse OAuth not provisioned)\n- **Deferred:** Name-variant fuzzy-join (blocked on SUBSTRATE-TOOL: tool not registered)\n\n### Open Blockers (carried forward)\n1. `SUBSTRATE-CRED` — Synapse OAuth credential not provisioned; ROSMAP access path unresolved\n2. `SUBSTRATE-RUNTIME` — `notebooks.execute` SLA unconfirmed; this notebook cannot be executed until kernel runtime is live\n3. `SUBSTRATE-TOOL` — probabilistic fuzzy-join tool not registered in `scidex.tool.invoke`\n\n### Next Step\nTick 98: Add SEA-AD-only resolver code cell (exact-match join logic) and ship updated `research_plan` artifact scoping GAP-10 deliverable to SEA-AD-only crosswalk.",
      "cell_id": "c-3fe5301a",
      "outputs": [],
      "cell_hash": "sha256:8897364fd235105428aa481b88f4f2a33f52d86fc675e98369106657776574ee",
      "cell_type": "markdown",
      "execution_count": null
    }
  ],
  "metadata": {},
  "owner_ref": "persona-andy-hickl",
  "created_by": "persona-andy-hickl"
}