P1 pilot: add lingcod_msy_recovery.csv with its manifest

The first dataset to land in the published tree, and the first manifest
written against the schema sketch. Consumed by lecture-python-intro's
msy_fishery lecture, which currently reads it from a relative path — so the
downloaded notebook cannot resolve it. The repoint is the paired lecture PR.

Licence established before adding, per AGENTS.md: RAM Legacy is CC BY 4.0,
attribution-only, so rehosting this extract is permitted. Worth recording how
that was found — ramlegacy.org states no licence at all; the authority is the
Zenodo record behind its DOI (license id "cc-by-4.0", access_right "open").

Meeting a real file changed the schema in three ways, all folded back into
manifest-schema.yml:

- integrity splits into `migration` and `upstream`. Lingcod is a byte-perfect
  copy of what the lecture consumes, yet its upstream provenance cannot be
  re-derived at all. One "verified" field would have to overstate or
  understate it; two fields tell the truth.
- `builder_status` records `unrecovered`. This file is constructed but ships
  no builder — the bug AGENTS.md names. The tempting fix is to relabel it
  verbatim, which buries the gap; instead it is now visible in the catalog.
- `known_nulls` declares nulls that are correct. F/Fmsy is null in the
  terminal assessment year, which a blanket no-nulls validation rule would
  wrongly reject.

Part of QuantEcon/meta#338
See QuantEcon/meta#336

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: mmcky

lectures/lingcod_msy_recovery.csv

@@ -0,0 +1,83 @@
+year,B_over_Bmsy,F_over_Fmsy
+1928,3.859289617,0.12815534
+1929,3.842213115,0.177669903
+1930,3.825136612,0.198058252
+1931,3.790983607,0.19223301
+1932,3.756830601,0.142718447
+1933,3.756830601,0.224271845
+1934,3.705601093,0.14368932
+1935,3.705601093,0.170873786
+1936,3.671448087,0.133009709
+1937,3.671448087,0.173786408
+1938,3.654371585,0.146601942
+1939,3.637295082,0.127184466
+1940,3.637295082,0.145631068
+1941,3.637295082,0.117475728
+1942,3.637295082,0.067961165
+1943,3.654371585,0.131067961
+1944,3.654371585,0.132038835
+1945,3.654371585,0.130097087
+1946,3.637295082,0.216504854
+1947,3.603142077,0.430097087
+1948,3.50068306,0.462135922
+1949,3.398224044,0.413592233
+1950,3.31284153,0.45631068
+1951,3.227459016,0.453398058
+1952,3.142076503,0.350485437
+1953,3.090846995,0.246601942
+1954,3.073770492,0.290291262
+1955,3.056693989,0.308737864
+1956,3.039617486,0.355339806
+1957,3.005464481,0.526213592
+1958,2.920081967,0.539805825
+1959,2.851775956,0.466990291
+1960,2.800546448,0.417475728
+1961,2.74931694,0.449514563
+1962,2.698087432,0.386407767
+1963,2.663934426,0.391262136
+1964,2.629781421,0.340776699
+1965,2.612704918,0.413592233
+1966,2.578551913,0.518446602
+1967,2.527322404,0.57961165
+1968,2.476092896,0.612621359
+1969,2.407786885,0.575728155
+1970,2.339480874,0.850485437
+1971,2.237021858,1.077669903
+1972,2.117486339,1.563106796
+1973,1.929644809,1.766990291
+1974,1.741803279,1.951456311
+1975,1.572745902,1.951456311
+1976,1.449795082,2.077669903
+1977,1.321721311,1.485436893
+1978,1.270491803,1.941747573
+1979,1.166325137,2.718446602
+1980,1.00068306,3.378640777
+1981,0.840163934,3.378640777
+1982,0.712090164,3.504854369
+1983,0.594262295,2.67961165
+1984,0.544740437,2.805825243
+1985,0.488387978,3.951456311
+1986,0.403005464,3.854368932
+1987,0.37568306,4.019417476
+1988,0.37397541,4.310679612
+1989,0.358606557,4.834951456
+1990,0.3125,4.553398058
+1991,0.285177596,4.32038835
+1992,0.268101093,4.174757282
+1993,0.256147541,3.485436893
+1994,0.266393443,2.27184466
+1995,0.315915301,2.019417476
+1996,0.365437158,2.038834951
+1997,0.396174863,1.815533981
+1998,0.425204918,1.300970874
+1999,0.479849727,1.398058252
+2000,0.539617486,0.63592233
+2001,0.650614754,0.49223301
+2002,0.800887978,1.029126214
+2003,0.988729508,1.291262136
+2004,1.243169399,0.195145631
+2005,1.656420765,0.261165049
+2006,2.083333333,0.249514563
+2007,2.510245902,0.144660194
+2008,2.885928962,0.093203883
+2009,3.193306011,

lectures/lingcod_msy_recovery.csv.yml

@@ -0,0 +1,111 @@
+# Manifest for lingcod_msy_recovery.csv — the first manifest written against
+# the schema sketched in ../manifest-schema.yml (PLAN Phase 8, pilot P1).
+
+filename: lingcod_msy_recovery.csv
+title: Pacific Coast lingcod — biomass and fishing pressure relative to MSY
+description: >
+  Annual B/Bmsy and F/Fmsy for the U.S. Pacific Coast lingcod (Ophiodon
+  elongatus) fishery, 1928-2009. Illustrates a stock fished below its MSY
+  reference points and subsequently rebuilt.
+
+# Constructed, not verbatim: these are two ratio series for a single stock,
+# subset out of a database that ships as a multi-table release. Selecting the
+# stock and the columns is our processing, so the class is `constructed` — and
+# a constructed dataset is supposed to ship its builder. This one does not.
+# See `builder` below.
+class: constructed
+
+source:
+  name: RAM Legacy Stock Assessment Database
+  url: https://www.ramlegacy.org/
+  doi: 10.5281/zenodo.14043031
+  version: v4.66-assessment-only    # current upstream release; NOT known to be
+                                    # the release this extract was taken from
+  citation: >
+    Ricard, D., Minto, C., Jensen, O. P., & Baum, J. K. (2012). Evaluating the
+    knowledge base and status of commercially exploited marine species with the
+    RAM Legacy Stock Assessment Database. Fish and Fisheries, 13(4), 380-398.
+
+license:
+  name: CC BY 4.0
+  url: https://creativecommons.org/licenses/by/4.0/
+  redistribution: permitted
+  verified: 2026-07-16
+  # Established against the Zenodo record for v4.66, which reports license id
+  # "cc-by-4.0" and access_right "open". Not stated on ramlegacy.org itself --
+  # the homepage gives only the citation, so the Zenodo record is the
+  # authority. Attribution is the sole condition and the citation above
+  # carries it, so rehosting this extract is permitted.
+
+retrieved: null                     # unrecorded -- see integrity.upstream
+maintainer: QuantEcon
+
+# ---------------------------------------------------------------------------
+# Integrity (PLAN Phase 7)
+# ---------------------------------------------------------------------------
+# Two independent questions with different answers here, which is why they are
+# recorded separately rather than as one status field:
+#   migration -- does this match what the lecture consumed before the repoint?
+#   upstream  -- is this actually what RAM Legacy says?
+# A file can be a perfect copy of a lecture's data and still have unprovable
+# provenance. Collapsing both into one "verified" would overstate this file.
+
+integrity:
+  sha256: fc2f873f97a9b7c6d335ca88203c321b4451cf4b94feb16ca40e99551c49c092
+
+  migration:
+    status: verified
+    date: 2026-07-16
+    method: >
+      sha256 byte-compare against lecture-python-intro's copy at
+      lectures/datasets/lingcod_msy_recovery.csv, immediately before the
+      repoint. Identical, so the repoint cannot change lecture output.
+
+  upstream:
+    status: unverifiable
+    date: 2026-07-16
+    method: >
+      Cannot be re-derived. The extract does not record which RAM Legacy stock
+      id it came from, which database version, or what transformation produced
+      the two ratio columns, and no builder was committed with it. Verifying
+      would mean re-identifying the stock in a current release and confirming
+      the series match -- possible in principle, not done. Treat the values as
+      trusted-by-provenance-of-the-author, not as independently checked.
+
+# ---------------------------------------------------------------------------
+# Shape
+# ---------------------------------------------------------------------------
+
+schema:
+  format: csv
+  columns:
+    - {name: year, dtype: int64, description: calendar year}
+    - {name: B_over_Bmsy, dtype: float64, description: stock biomass relative to the biomass supporting MSY}
+    - {name: F_over_Fmsy, dtype: float64, description: fishing pressure relative to the pressure achieving MSY}
+  row_count_floor: 82
+  date_range: {start: 1928, end: 2009}
+  # F_over_Fmsy is null in the terminal year (2009) -- expected, and normal for
+  # a terminal assessment year. Recorded so PR validation does not "fix" it:
+  # a blanket no-nulls rule would reject this file wrongly.
+  known_nulls:
+    F_over_Fmsy: 1
+
+# ---------------------------------------------------------------------------
+# Consumers -- how a correction knows what to rebuild
+# ---------------------------------------------------------------------------
+
+consumers:
+  - repo: QuantEcon/lecture-python-intro
+    file: lectures/msy_fishery.md
+
+# ---------------------------------------------------------------------------
+# Builder
+# ---------------------------------------------------------------------------
+# AGENTS.md: "A constructed dataset without its committed builder is a bug."
+# This file is that bug, inherited rather than introduced -- it is one of the
+# constructed-but-unscripted set PLAN Phase 9 tracks. Recorded explicitly
+# instead of being quietly misclassified as verbatim, so the gap is visible in
+# the generated catalog rather than lost.
+
+builder: null
+builder_status: unrecovered         # unrecovered | committed | not-applicable

manifest-schema.yml

@@ -53,23 +53,45 @@ license:
   # Redistribution must be confirmed before a file is served from this repo —
   # unlicensed rehosting is a blocker, not a nice-to-have (AGENTS.md).
   redistribution: permitted
+  verified: 2026-07-16                  # when, and against what, this was
+                                        # established — a licence claim with no
+                                        # date is not evidence. P1 found the
+                                        # authority is often not the project
+                                        # homepage but its Zenodo/DOI record.
 
 retrieved: 2024-04-10                   # ISO date the bytes were obtained
 maintainer: QuantEcon                   # who fixes this when it breaks
 
 # ---------------------------------------------------------------------------
 # Integrity (PLAN Phase 7) — a file is not promoted with unknown status
 # ---------------------------------------------------------------------------
+# Two independent questions, and P1 (lingcod) proved they get different answers:
+# that file is a byte-perfect copy of what the lecture consumed, while its
+# upstream provenance cannot be re-derived at all. One combined "verified" field
+# would have had to either overstate or understate it, so they are split.
 
 integrity:
   sha256: null                          # of the committed file
-  verified: null                        # ISO date of the last check
-  method: >
-    How this was checked: re-fetch-and-compare for verbatim; re-run the builder
-    and compare the overlap window for constructed/dynamic; spot-check against
-    the cited publication for author-assembled. Say so plainly when full
-    verification is not possible.
-  status: unverified                    # verified | spot-checked | unverified | failing
+
+  # Does this match what the consuming lecture used before the repoint?
+  # Guards the migration: a mismatch means repointing silently changes output.
+  # Hard prerequisite for Phase 8.
+  migration:
+    status: unverified                  # verified | unverified | failing | not-applicable
+    date: null
+    method: null                        # e.g. sha256 compare against <repo>'s copy
+
+  # Is this actually what the upstream source says?
+  # Guards the provenance claim above.
+  upstream:
+    status: unverified                  # verified | spot-checked | unverifiable | unverified | failing
+    date: null
+    method: >
+      re-fetch-and-compare for verbatim; re-run the builder and compare the
+      overlap window for constructed/dynamic; spot-check against the cited
+      publication for author-assembled. Say so plainly when verification is
+      impossible — `unverifiable` with a reason is an honest answer and is
+      what the catalog should show. Silence is not.
 
 # ---------------------------------------------------------------------------
 # Shape — what a consumer can rely on; also the basis for PR validation tests
@@ -84,6 +106,12 @@ schema:
   row_count_floor: 5                    # PR validation fails below this
   date_range: {start: 1960, end: null}  # null end = tracks the moving source
 
+  # Nulls that are correct and must not fail validation. P1 found a real one:
+  # lingcod's F/Fmsy is null in its terminal assessment year, which a blanket
+  # no-nulls rule would reject. Declaring them makes the invariant tests
+  # (Phase 5) enforceable without hand-waving.
+  known_nulls: {}                       # e.g. {F_over_Fmsy: 1}
+
 # ---------------------------------------------------------------------------
 # Consumers — machine-readable, so a correction knows what to rebuild
 # ---------------------------------------------------------------------------
@@ -100,7 +128,13 @@ consumers: []
 # Builder — required for constructed and dynamic-snapshot; omit for verbatim
 # ---------------------------------------------------------------------------
 
-builder: scripts/business_cycle.py
+builder: scripts/business_cycle.py      # path to the committed builder, or null
+
+# AGENTS.md says a constructed dataset without its builder is a bug — but the
+# repo has inherited several (PLAN Phase 9), and P1's own pilot file is one.
+# The tempting workaround is to misclassify them as `verbatim`, which buries
+# the gap. This field keeps it visible in the generated catalog instead.
+builder_status: committed               # committed | unrecovered | not-applicable
 
 # Dynamic snapshots only. Drives the scheduled refresh-as-PR (PLAN Phase 5).
 cadence: annual                         # e.g. daily | weekly | monthly | annual