v1 to v2 Concept Map

Relevant v1 concepts translated into v2 artifacts, schemas, verbs, Prism, agents, and Forgejo.

Source: docs/parity/v1-to-v2-concept-map.md

v1 to v2 Concept Map

This document preserves the v1 SciDEX concepts that still matter for v2. v1 is read-only reference material; do not patch v1 to satisfy v2 parity. The purpose here is to translate useful v1 semantics into v2 docs and implementation contracts without carrying forward obsolete mechanics.

What To Preserve

v1 concept Why it matters v2 home
“Every entity is an artifact” registry discipline Stable cross-references, provenance, dedupe, and lifecycle still define the product. design/spec-001-polymorphic-substrate.md, reference/verbs/artifact.md
Artifact lifecycle states and non-deletion norm Users and agents need old refs to keep resolving after merges, archives, and supersession. design/spec-085-artifact-governance-lifecycle.md, lifecycle verbs
Landscape and gap framework The v2 science loop still depends on landscapes, gaps, missions, evidence, and gap resolution. design/spec-027-landscape-missions.md, design/spec-052-gap-detection-engine.md
Agora/Senate/Pantheon governance ideas Debate, review, quality gates, and persona judgment remain important, but are expressed through artifacts, votes, signals, and agent work packets. design/spec-024-senate.md, design/spec-028-pantheon.md, design/spec-095-open-enrollment-debates.md
Schema governance and migration safety Schema changes need explicit proposals, validation, migration plans, and rollback thinking. design/spec-009-schema-evolution.md, runbooks/migrations.md
Artifact storage decision tree Small manifests, large blobs, external storage, and lineage remain the right separation. operations/artifact-repository-architecture.md, design/spec-057-dataset-publication.md
content_hash as dedupe key, not file integrity v1 had real incidents from confusing dedupe keys with byte hashes. v2 must keep checksum/provenance explicit. Blob-store helpers, artifact manifest fields, design/spec-111-artifact-lifecycle-and-deduplication.md
API stability contract Additive compatibility, stable canonical refs, opaque cursors, and sunset policy remain valid API expectations. api/versioning_policy.md, design/spec-125-api-styles-rest-vs-rpc.md
Emergency restore and artifact recovery runbooks Restore discipline and provenance-preserving recovery still apply, but target v2 stores and databases. runbooks/emergency_restore.md, operations/artifact-repository-architecture.md
Bio-competitive platform parity notes v2 parity is not only v1 feature parity; it must also track external platform capability gaps. design/spec-193-external-platform-parity.md, design/spec-194-beach-science-parity.md, design/spec-195-biomni-parity.md, design/spec-196-kdense-parity.md

What Not To Preserve

Do not copy these v1 mechanics into v2:

  • direct writes to the v1 scidex database;

  • v1 SQLite-era migration assumptions;

  • v1 artifact payload writes under /data/scidex-artifacts, /data/artifacts, or /home/ubuntu/scidex/data/scidex-artifacts;

  • archived GitHub artifact repositories as living v2 stores;

  • bespoke Flask/Jinja routes as the required pattern for every artifact type;

  • prompt libraries or persona policy inside substrate backend modules;

  • v1-only CLI scaffolding instructions that create custom route/template files instead of JSON Schemas and polymorphic verbs;

  • direct model calls from substrate workers for scientific judgment.

Artifact Types

v1’s artifact-kind docs described dataset_card, analysis_report, hypothesis_card, notebooks, figures, models, papers, gaps, hypotheses, and wiki pages as separately wired objects. v2 keeps the conceptual diversity but normalizes the mechanics:

User-facing thing v2 shape
Hypothesis hypothesis artifact plus evidence, comments, signals, links, markets, and review records.
Knowledge gap or open question knowledge_gap / open_question / mission artifacts, linked to landscapes and evidence.
Wiki page wiki_page artifact, usually rendered in Prism and optionally backed by Forgejo for living artifacts.
Paper paper artifact with citation metadata, PMID/DOI refs, full-text or PDF blob provenance when available.
Dataset dataset artifact plus blob locations, schema, provenance, license, and reproducibility metadata.
Notebook or analysis notebook / analysis artifacts with runtime provenance, outputs, and linked figures/results.
Figure or media Blob-backed artifact or artifact attachment with checksum, producer, and source refs.
Tool or skill tool / skill artifacts with schema, runtime, trust, cost, and lifecycle metadata.
Agent task agent_work_packet artifact routed to scidex-agents, not executed as substrate prompt code.

Storage Rules Carried Forward

v1’s best storage rule was the separation between small human-readable manifests and larger immutable payloads. v2 keeps that separation but changes the durable stores:

  • small structured metadata belongs in the artifact content, schema registry, or Forgejo-backed manifests;

  • large or binary payloads belong in S3 through substrate blob helpers or in Forgejo-backed artifact bundles;

  • every payload must record size, checksum, location, producer, and provenance;

  • artifact identity and lifecycle stay in substrate even when the bytes live in Forgejo or S3.

The old v1 artifact repository is frozen. If a v1 payload has to be recovered, copy it into a v2 store with a manifest that records the original path, source commit or database row, checksum, and recovery reason.

Governance And Lifecycle

v1’s governance docs established three norms that remain valid:

  1. artifacts are never silently deleted;

  2. duplicate or stale artifacts move through merge, deprecate, archive, or supersede flows;

  3. owners and reviewers need evented notifications and visible rationale.

In v2 those norms should be implemented through artifact lifecycle state, comments, signals, votes, links, Senate/governance artifacts, and event streams. Substrate records the state and enforces invariants. Agents can propose or review governance decisions, but they do so through substrate verbs.

Landscape And Gap Semantics

The v1 landscape-gap framework remains one of the clearest product concepts:

  • a landscape is the current map of a scientific domain;

  • a gap is a specific, contextual unknown inside a landscape;

  • every research action either enriches the map, probes a thin region, or fills a known gap;

  • gap resolution is a landscape-completion process, not just an answer string.

v2 expresses this as landscapes, gaps, missions, hypotheses, analyses, reviews, debates, evidence links, and rankings. Hardcoded scientific trajectories should not live in substrate workers. When judgment is required, substrate should write an agent_work_packet with source refs, trigger metadata, idempotency keys, reserved-budget signals, and acceptance criteria.

API Semantics

The v1 API stability contract maps to v2 as follows:

v1 stability rule v2 rule
Additive-only changes inside a major version Verb inputs/outputs, schemas, events, and REST resources must remain backward compatible unless a new version is declared.
Stable canonical artifact URIs Stable refs are type:id plus version where needed; Prism and API routes should not expose transient implementation IDs as canonical user refs.
Opaque signed cursors Pagination cursors should remain opaque and server-validated.
JSON-LD context growth is additive Contexts and schema vocabularies can expand but should not rename existing meanings silently.
Public CORS and cache discipline Public read surfaces should define explicit cache and CORS behavior.

Documentation Migration Checklist

Use this checklist when reviewing a v1 doc for v2 relevance:

  • Does it define a user-facing concept that still exists?

  • Does it define an invariant, safety rule, or incident lesson that still prevents data loss or bad science?

  • Can it be expressed through artifacts, schemas, verbs, Prism, agents, or Forgejo instead of v1-specific code paths?

  • Does the v2 target doc already cover it? If yes, link or tighten that doc instead of duplicating.

  • Does it tell the reader to write to v1, v1 artifact paths, archived GitHub repos, or v1 databases? If yes, do not copy those instructions.

Source v1 Docs Reviewed

The relevant v1 material came from these read-only files:

  • README.md

  • docs/api/v2-stability.md

  • docs/artifact_storage_guide.md

  • docs/contributor/adding-an-artifact-kind.md

  • docs/design/artifact_content_hash_semantics.md

  • docs/design/artifact_folder_layout.md

  • docs/design/governance_rules.md

  • docs/landscape-gap-framework/README.md

  • docs/runbooks/artifact-recovery.md

  • docs/runbooks/emergency_restore.md

  • docs/schema_governance_guide.md

  • docs/bio_competitive/README.md

These sources are historical provenance. The v2 docs linked above are the operational contract.