FIN Taproot Knowledge Curation Roadmap

0. Revision Summary

First cut. Defines Taproot — FIN’s canonical produce-industry knowledge base — and the curation discipline required to build and maintain it as a world-class data asset. Closes Pillars 3 (World Knowledge Corpus) and 9 (Knowledge Integrity) of the Platform North Star Roadmap. World-class data sets are maintained, not just captured; this doc specifies the maintenance.

1. What Taproot Is

Taproot is FIN’s structured knowledge base of the produce industry. It is the substance behind the claim that the agentic system “knows produce.” It exists at two layers:

• Taproot Central canon — FIN-curated, single source of truth for produce-industry reference knowledge. Lives under FIN Central. Includes commodity reference data, grower/vendor atlas, regulatory reference (FSMA, FDA, USDA, organic standards), seasonality, geography, market intelligence (AMS Market News).
• Taproot Tenant mirror + overlays — each tenant deployment receives a read-mirror of Taproot Central, plus tenant-specific overlays (vendors they trade with that aren’t yet in the central canon, internal naming conventions, proprietary metrics). Tenant overlays may be promoted into Central canon after curation review.

Taproot is not operational state — that is the CQRS projection layer (Pillar 2). Taproot is the world the operational projections cite against. When a watermelon profile says “this is a Sangria variety from Florida in May,” Taproot is what makes “Sangria,” “Florida,” and “May” mean something specific.

Brand-wise: Taproot is the internal name. The public-facing equivalent is Harvest Directory (anonymized, aggregated, public projections derived from Taproot + Plane 3 anonymized signals).

1.1 External-source gathering boundary

As of the 2026-05-20 Central Taproot freshness audit, this boundary is canonical:

• FIN Central Taproot / Knowledge Forge is the only layer that gathers external public or licensed sources such as USDA AMS, PACA, FDA, NOAA/NWS, AGROVOC, FAOSTAT, Federal Register, Google Trends, and market/news feeds.
• Tenant taproots do not gather external sources. Tenant systems receive Central Taproot mirror content, Central-derived signal projections, and their own operational tenant data.
• Tenant systems may overlay, cite, project, and reason over Central-derived evidence, and may request a Central refresh, but they should not call external public-data APIs directly.
• Existing tenant-side adapters for USDA/NWS/FDA-style live fetches are transition debt unless they are explicitly reworked into Central-only consumers or caller-supplied-payload evaluators.

This boundary protects freshness discipline, source licensing, provenance audits, and agent reasoning quality. It also prevents every tenant from becoming its own drifting crawler.

2. Knowledge Domains in Scope

Taproot covers ten primary domains, listed in priority order for build sequencing.

2.1 Commodity Reference (highest priority)

Per-commodity canonical record. The substance behind “this is a watermelon.”

• Botanical classification (species, variety)
• USDA grading standards (Extra Fancy, Fancy, No. 1, No. 2)
• Pack specifications by commodity (carton sizes, weights, count classes)
• Seasonality calendar (growing regions × months × peak/shoulder/off)
• Storage requirements (temperature, humidity, ethylene sensitivity, gas exposure)
• Shelf life by handling profile
• Defect taxonomy (named defects, severity classes, accept/reject thresholds)
• Quality measurement methods (brix, firmness, color, weight)
• Substitution graph (what can substitute for what in a customer order)
• Pricing benchmark sources (AMS Market News commodity codes)

Initial scope: top ~20 commodities by Nathel volume. Expansion target: 100+ within 18 months.

2.2 Vendor / Grower Atlas

Per-vendor, per-grower canonical record.

• Vendor classification (grower-shipper, broker, importer, repacker, regional distributor)
• Country / region of origin operations
• Certifications (organic, fair-trade, GAP, GFSI)
• Commodity mix
• Typical lead times (vendor-side observed, then operational-projection-confirmed)
• Quality reputation (qualitative; structurally derived from Pillar 2 operational scorecards over time)
• PACA license status
• Relationship history with Nathel (operational)

Initial scope: top ~100 vendors and growers serving NYC market. Expansion target: full national grower atlas + major international growers within 18 months.

2.3 Customer Reference

Per-customer canonical record (Nathel customers initially; later, multi-tenant customer overlap intelligence).

• Customer classification (restaurant group, retail chain, foodservice distributor, institutional buyer, wholesaler, secondary)
• Geographic concentration
• Typical buying patterns (commodity preferences, volume, seasonality)
• Service-level expectations (delivery windows, claim sensitivity, communication style)
• Account relationship history (operational)

Initial scope: top ~100 Nathel customers. Expansion target: broader as multi-tenant data accumulates.

2.4 Carrier and Logistics Reference

Per-carrier canonical record.

• Carrier classification (asset-based, brokerage, owner-operator)
• MC/DOT numbers
• Equipment types and capacity
• Service area
• Safety scores (FMCSA)
• Insurance status
• Reefer compliance reputation (structurally derived)
• Typical lanes (vendor origin → Nathel)

Initial scope: all carriers running active inbound to Nathel. Expansion target: broader as TURVO + Samsara corpora mature.

2.5 Geography and Growing Regions

Canonical record of agricultural regions that supply NYC.

• Region name + geographic boundary
• Climate zone
• Growing season calendar per crop
• Distance / typical transit time to NYC
• Major shippers from region
• Risk factors (weather patterns, labor disputes, regulatory issues)

Initial scope: top ~30 regions supplying NYC. Expansion target: comprehensive North American produce geography within 18 months; international regions where Nathel imports.

2.6 Regulatory Reference

Canonical reference for the regulatory framework produce operates under.

• FSMA 204 Food Traceability Rule (KDE/CTE requirements per commodity)
• USDA AMS organic certification standards
• PACA (Perishable Agricultural Commodities Act) provisions
• FDA food safety regulations
• State-level food safety regulations (NY state, NJ state for cross-river logistics)
• Federal/state pricing transparency rules
• Country-of-origin labeling requirements

Initial scope: comprehensive FSMA 204 + PACA + USDA organic. Expansion target: state-level + international import regulatory reference.

2.7 Market Intelligence

Canonical reference for produce market signals.

• USDA AMS Market News commodity codes + ingest of daily market reports
• Terminal market pricing references (Hunts Point Terminal Market historicals)
• USDA Economic Research Service produce outlook reports
• Trade publication archive (The Packer, Produce Business, etc.)
• Industry association publications (PMA, IFPA, United Fresh)

Initial scope: AMS Market News + Hunts Point Terminal Market. Expansion target: comprehensive trade publication archive (subject to licensing).

2.8 Industry Glossary and Terminology

The vocabulary of the industry.

• Common terms (FOB, CIF, dump, claim, lumper, dock, reefer, etc.)
• Regional variants (East Coast vs West Coast usage)
• Commodity-specific jargon
• Acronyms (PACA, FSMA, GAP, GFSI, PMA, IFPA, etc.)
• Slang and operator vernacular

Initial scope: ~200 core terms. Expansion target: comprehensive ~1000-term glossary.

2.9 Best Practices Reference

How-to references for industry-standard operations.

• Cold chain best practices
• QC inspection methodology by commodity
• Cross-docking discipline
• FIFO/FEFO inventory practices
• Claim filing and dispute resolution
• Vendor scorecard methodology (industry standard, not just FIN’s)
• Customer service-level frameworks

Initial scope: ~20 core best-practice references. Expansion target: ~100 with operator-contributed enrichment.

2.10 Historical Reference and Provenance

Historical data anchoring the present.

• Multi-year seasonality patterns
• Weather event historicals affecting supply
• Major industry events (recalls, regulation changes, market shocks)
• Vendor history (mergers, license suspensions, ownership changes)

Initial scope: rolling 5-year window. Expansion target: rolling 15-year window where data is available.

3. Source Taxonomy

Every Taproot entry has a provenance, classified by source type. Source type drives curation discipline and trust level.

Source Type	Description	Trust	Curation Effort
Authoritative	Federal/state regulator, USDA AMS, FDA, FMCSA, PACA, industry standards bodies	Highest	Low (ingest, structure, version-track)
Curated	FIN-authored synthesis grounded in authoritative sources + operational evidence	High	Medium (authored, reviewed, version-controlled)
Ingested	Trade publications, vendor self-reported, industry association pubs	Medium	Medium (sourced, attributed, dated)
Derived	Operational scorecards from Pillar 2 (vendor scorecards, carrier scorecards)	Medium-high (structurally observed)	Low (auto-projected with discipline gates)
Operator-contributed	Tenant operator authored content (e.g., Alex Cohen authored “how Nathel handles X”)	Variable	High (provenance-stamped, reviewed before promotion to canon)

Discipline. Every Taproot entry carries its source classification in frontmatter. Authoritative sources are linked + cached (drift monitored). Curated entries are versioned with a last_validated date. Operator-contributed entries cannot enter Central canon without curation review.

4. Curation Discipline

The discipline that makes Taproot a world-class data set.

4.1 The Curation Workflow

Every Taproot entry moves through four states:

• proposed — drafted but not yet validated. Visible to authors only.
• in_review — submitted for curation review. Visible to reviewers.
• approved — passed review; eligible for publish.
• published — live in Taproot Central canon.

Plus a maintenance state:

• deprecated — superseded; retained for history, not surfaced in retrieval.

State transitions are events on the events table: taproot.entry.proposed, taproot.entry.reviewed, taproot.entry.approved, taproot.entry.published, taproot.entry.deprecated.

4.2 Curator Roles

• Author — drafts entries (Rob initially; later, contributor agents + operator contributions)
• Reviewer — validates entries against source quality, structural correctness, and consistency with related entries
• Publisher — final gate; ensures the publish action propagates correctly (tenant mirrors update, retrieval indices rebuild)

For Wave 2 (now): Rob is all three roles. Discipline is preserved by review gates being explicit even if the same person performs all three steps.

For Wave 3+: separation of roles. Author can propose; reviewer must be different actor; publisher must be authorized.

4.3 Review Criteria

Every entry under review is checked for:

1. Source quality. Is the citation authoritative? Is it current?
2. Structural correctness. Does the entry conform to the doc_kind schema for its type?
3. Internal consistency. Does this entry contradict any existing canonical entry? If so, which is correct?
4. Coverage. Does this entry close a known gap, or is it duplicative?
5. Frontmatter completeness. doc_id, status, audience, sources, last_validated, review_cadence.
6. Wikilink validity. Every [[type:id]] reference resolves.
7. Anonymization compliance. No tenant-private data leaks into Central canon.

4.4 Curation Cadence

• Daily: triage queue of proposed entries; promote to in_review when reviewer-ready.
• Weekly: review queue walked; approve or reject batch.
• Monthly: sample of published entries re-validated against current authoritative sources (drift check).
• Quarterly: full sweep of one knowledge domain (rotating); deprecate stale, promote tenant overlays that have proven valuable.

5. Drift Monitoring

Authoritative sources change. Taproot must catch that.

5.1 What Drifts

• AMS Market News commodity codes change occasionally
• FSMA regulations get amended
• USDA grading standards get revised
• Carrier safety scores (FMCSA) update continuously
• Vendor licenses (PACA) get suspended / reinstated
• Industry association publications post new guidance
• Operational reality changes (a vendor stops shipping a commodity, a new growing region opens)

5.2 Drift Detection Mechanism

For every Taproot entry, the source is one of:

• Linked authoritative URL — fetched on a cadence; checksum + last-modified compared
• Authoritative API — polled on a cadence; structured diff compared
• Curated synthesis — last_validated date tracked; expired entries flagged for re-review

A new event kind: taproot.drift.detected — emitted when a source’s content differs from what Taproot has on record. Drift events route to the curation review queue with full diff context.

5.3 Drift Response

• Trivial drift (formatting, citation update): curator confirms; entry version-bumped.
• Substantive drift (regulation amended, commodity standard revised): entry held under review; downstream projections that depend on the entry are flagged with a staleness banner until the review concludes.
• Critical drift (a referenced authority publishes a contradicting standard): SEV2 alert via Pillar 6 incident response.

5.4 Drift Monitoring Cadence

Source Class	Polling Cadence
AMS Market News	Daily
FSMA / FDA / USDA regulations	Weekly
FMCSA carrier safety	Weekly
PACA license database	Weekly
Industry publications	Weekly (RSS where available)
Tenant-overlay sources	Per-tenant negotiated
Curated entries last_validated	Quarterly sweep

6. Resolver Discipline

The resolver matches incoming entity references (from operational events) against Taproot canonical entries. Resolver v1 decisions are already locked (per [project memory: resolver_v1_decisions]) — this section binds those decisions to Taproot.

6.1 Resolver Behavior

When an operational event references an entity (e.g., a TURVO shipment names a carrier “ABC Trucking LLC”), the resolver:

1. Searches Taproot canonical entries for matching entity
2. If found: binds the event to the canonical entity_id
3. If not found: emits signal.entity.unresolved and creates a candidate entry in proposed state for curation review
4. If ambiguous (multiple matches): emits signal.entity.ambiguous and routes to curation review

6.2 Promotion of Tenant Overlays

When a tenant overlay entity (e.g., a vendor unique to Nathel) accumulates sufficient operational evidence (N transactions over M weeks), it becomes a candidate for promotion to Taproot Central canon. Promotion is not automatic; it triggers a curation review.

Promotion criteria:

• Sufficient transaction volume (threshold per entity class)
• Stable identifying information (no churn in name, location, license)
• No anonymization conflict (tenant has not requested entity be held private)
• Reviewer confirms the entity is industry-meaningful (not, e.g., a one-off vendor)

6.3 Soft-Merge Discipline

Per resolver v1 decisions, merging entities is soft (reversible). When two tenant-overlay entries are determined to be the same canonical entity:

• Soft-merge event emitted: taproot.entity.soft_merged
• Both entries remain in their tenant overlays
• The canonical entry in Central inherits the merge; future events resolve to the canonical
• Un-merge possible (rare, but supported) within 30 days

7. Tenant Overlays vs Central Canon

The line between what’s Central and what’s tenant-only.

7.1 What Stays Tenant-Only

• Tenant-private vendors (vendor explicitly marked private)
• Tenant-specific naming conventions
• Tenant operational metrics derived from private events
• Tenant-private customer information
• Tenant-internal procedures that haven’t been generalized

7.2 What Promotes to Central

• Vendors that trade with N≥ 2 tenants
• Carriers that serve N≥ 2 tenants
• Commodity reference data (always Central; commodities don’t belong to a tenant)
• Regulatory reference (always Central)
• Geographic/region reference (always Central)
• Industry glossary (always Central)
• Best practices (after curation review confirms generalizability)

7.3 Anonymization at Promotion

Promotion of any entity from tenant overlay to Central canon goes through the Anonymization Policy. Operator names, contact details, internal codes that could identify the contributing tenant are stripped before publish.

8. World-Class Data Benchmarks

What “world-class” means, measurably.

8.1 Coverage Benchmarks

Domain	Wave 2 (now) target	Wave 3 (6mo) target	Wave 4 (18mo) target
Commodities profiled	5 (watermelon + 4 others)	20	100
Vendors in atlas	20	100	1000
Customers profiled	10	100	500
Carriers profiled	10	50	500
Growing regions	10	30	100
Regulatory references	core FSMA + PACA	comprehensive FSMA + PACA + USDA organic	+ state-level + international
Market intelligence	AMS daily for ~5 commodities	AMS daily for ~30 commodities + Hunts Point	+ trade publication archive
Glossary terms	50	200	1000
Best practice docs	5	20	100
Historical depth	1 year	5 year	15 year

8.2 Quality Benchmarks

• Provenance completeness: 100% of canonical entries cite a source. Always.
• Source freshness: ≥ 95% of authoritative-source entries validated against current source within the last quarter.
• Resolver hit rate: ≥ 95% of operational entity references resolve to canonical or candidate entries without curator intervention.
• Drift detection rate: drift detected within 7 days of upstream source change on monitored sources.
• Verifier reference-data pass rate: Pillar 5 entity-reference-validity verifier passes ≥ 99% (i.e., entities cited by agents resolve to real canonical entries).

8.3 Uniqueness Benchmarks

The aspects of Taproot that no public dataset matches:

• Operational scorecards (vendor, carrier, customer) derived from real PO-bound events at NYC produce wholesale tempo
• Cold-chain reality data (vs published “best practice”) at the commodity × season × lane granularity
• Multi-tenant aggregated intelligence (once Wave 3+)
• Procedure profiles (Pillar 5) capturing how the industry actually handles situations, distilled from real resolutions

These are the assets that make Taproot uniquely valuable; they cannot be cloned from public sources.

9. Phased Build

9.1 Phase T1 — Foundation (current 2-week sprint + W3-W4)

• Taproot folder structure established under docs/taproot/ in FIN Central vault
• doc_kind schemas for each of the 10 domains defined and added to projection spec amendments
• First commodity profile (watermelon) curated end-to-end as the template
• 4 additional commodities profiled (top Nathel SKUs: pick from tomato, citrus, banana, berry families)
• Top 20 Nathel vendors profiled (initial pass; minimal completeness OK)
• Core FSMA 204 + PACA regulatory references curated
• AMS Market News ingest live for 5 commodities

Acceptance: Agent can answer “what is a Sangria watermelon?” or “what’s the FSMA 204 KDE for a tomato load?” from Taproot, with citations, with verifier passes.

9.2 Phase T2 — Operator Enrichment (next 6 weeks)

• Operator-contribution workflow live (Alex Cohen, foreman, inspectors can propose entries)
• Curation review workflow live with explicit reviewer step
• Drift monitoring live for AMS, FSMA, PACA, FMCSA
• 20 commodities profiled, top 50 vendors, top 30 customers, 30 carriers
• Glossary at 100 terms
• 10 best-practice references curated

Acceptance: Resolver hit rate ≥ 90% on operational entity references; verifier reference-data pass rate ≥ 95%.

9.3 Phase T3 — Curation Maturity (months 4-6)

• Resolver v2 deployed (production-grade, with promotion-of-tenant-overlay support)
• Quarterly domain sweeps operational (rotating through domains)
• Tenant-overlay-to-Central promotion workflow proven
• Anonymization at promotion validated
• Coverage at Wave 3 benchmarks (§8.1)
• Quality benchmarks (§8.2) met

Acceptance: Taproot canon v1 complete; ready to be the reference layer for Tier 0 public MCP and the substrate for Harvest Directory.

9.4 Phase T4 — Public + Multi-Tenant (months 7-18)

• Harvest Directory public surface populated from Taproot Central (anonymized projections only)
• Multi-tenant promotion patterns mature (N≥ 3 tenants contributing overlays)
• Federated knowledge contributions live (per Anonymization Policy)
• Federal reference layer added (FDA, additional USDA, state-level)
• Coverage at Wave 4 benchmarks (§8.1)
• Trade publication archive licensed and integrated

Acceptance: Taproot canon v2 complete; demonstrably world-class on coverage and uniqueness benchmarks.

10. Acceptance Criteria

End of Phase T1.

• 5 commodity profiles, 20 vendors, core regulatory, AMS Market News ingest live
• Agent can answer reference questions with Taproot citations
• Verifier reference-data check enabled in harness

End of Phase T2.

• Operator contributions flowing
• Drift monitoring operational
• Coverage at intermediate benchmarks
• Resolver hit rate ≥ 90%

End of Phase T3.

• Taproot canon v1 complete (Wave 3 coverage benchmarks)
• Resolver v2 in production
• Quality benchmarks §8.2 met
• Tenant-overlay-to-Central promotion proven

End of Phase T4.

• Taproot canon v2 complete (Wave 4 coverage benchmarks)
• Harvest Directory public surface live
• Federated knowledge contributions live
• All uniqueness benchmarks (§8.3) demonstrable

11. Open Decisions

• Operator contribution incentives. What motivates Alex / foreman / inspectors to author entries? Default: workflow-integrated (writing entries earns better agent answers in their workflow); revisit if engagement is low.
• Trade publication licensing strategy. Self-license vs partnership vs scrape-with-attribution. Default: partnership where feasible (PMA, IFPA); explicit licensing deals otherwise; no scraping.
• AMS Market News ingest mechanism. USDA AMS publishes APIs and CSV feeds. Default: ingest both for redundancy; structure by commodity code; render as daily MD projections.
• Hunts Point Terminal Market historical pricing. Available how? Manual capture initially; explore data partnership for historical.
• Curator agent vs human curator. When does a curator agent take over routine curation steps? Default: never in Wave 2 (humans only); explicit per-domain policy from Wave 3.
• Federation of knowledge across FIN tenants vs other industry consortia. Default: FIN-only federation through Wave 3; explore industry consortium participation Wave 4+ if strategically advantageous.

12. Cross-Doc Dependencies

• Platform North Star Roadmap — this doc covers Pillars 3 and 9
• Projection Engineering Spec v0.2 — Taproot entries are doc-projections; doc_kind schemas land in the projection spec
• Self-Improving System Roadmap — verifiers (Pillar 5) depend on Taproot for entity reference validity, provenance walkability, business-rule conformance
• Operational Corpus Ingestion Roadmap — operational projections cite Taproot; Taproot uses derived data from operational corpus for vendor/carrier/customer scorecards
• Anonymization Policy v1 — gates promotion of any tenant-overlay entry to Central canon
• Demarcation Plan — Taproot Central lives on FIN Central deployment; tenant mirrors live on tenant deployments
• Data Signal Offerings — Taproot canon backs the data signal product offerings to business/consumer/government audiences
• Resolver v1 decisions (project memory) — binds operational events to Taproot entities

13. The Punchline

Taproot is the substance behind “knows produce.” It is not built once and forgotten; it is curated continuously. Ten knowledge domains, five source classes, four lifecycle states per entry, four reviewer criteria, daily-to-quarterly cadences depending on source velocity, soft-merge discipline for entity resolution, anonymization gates for tenant-to-Central promotion. Wave 3 produces canon v1. Wave 4 produces canon v2 + Harvest Directory public surface. The uniqueness lies in the operational data fused into the canon — that is what no public dataset can match, and what makes FIN’s data set world-class rather than merely comprehensive.

14. Audit Annotation - 2026-05-20

Roadmap audit tracker: FIN Agentic Harness and Knowledge Roadmap Audit Tracker.

Verification status: the Taproot source taxonomy and curation model are strategically valid, but the curation state events (taproot.entry.*) and drift event (taproot.drift.detected) appear roadmap-only in this checkout. They should be treated as planned work, not current runtime capability.

Execution note: provenance and freshness must become first-class runtime controls. Current read tools expose source/freshness metadata, but per-source SLA enforcement and agent-visible evidence staleness still need verifier and retrieval-surface implementation.

Central-source freshness note: current Knowledge Forge automation is not yet healthy end to end. NOAA weather and active-intelligence v2 are fresh in Central staging, but AMS is failing after crawl, PACA is not producing staged source docs, market-news terminal markets are failing, and several green crawls still fail extraction/quality. The remediation program must repair source freshness before agents are allowed to treat Central external evidence as current.