08. Jurisdiction plugins

Draft 0.1. Reference implementation: shared/gradRules/ (eleven modules), shared/artifactRendererHtml.js (the RENDERERS registry and renderArtifactHtml), shared/reviewedAsOf.js, shared/nyCompliance.js, api/family/generate-artifact.js.

8.1 Why plugins

The Record is above any jurisdiction. A state's graduation rule, a district's quarterly report, an ESA program's expense form: each is a read of the same record through a lens, and a render of that read into the paper a particular office asks for. Neither the read nor the render is the learner's identity, and neither ever alters the record or appears on a verifiable receipt. They are plugins: pure, cited, versioned, dated, replaceable.

Two plugin kinds exist today:

• rule sets (shared/gradRules/*): deterministic evaluators that classify the record's rows against a published requirement and return a citation-rich reading;
• artifact renderers (shared/artifactRendererHtml.js plus model builders such as shared/nyCompliance.js): pure functions from a render-agnostic model to a standalone printable HTML document.

8.2 The rule-set interface

A rule set is one module that exports a frozen RULES object, a classifier, an evaluator, and (optionally) a model builder for a paid artifact.

RULES metadata (MUST)

Functions

Behavior rules (MUST)

1. Pure and deterministic. No I/O, no network, no AI in this layer. Same input, same output, on client and server.
2. Every requirement, door, and caution carries a citation; the evaluator reads unit counts from RULES, never hard-codes them.
3. Conservative parsing: an unparsable credit counts 0; an unmappable course is surfaced in unmapped_courses, never guessed into a core subject.
4. Overflow beyond a core subject's requirement flows to electives (standard transcript-evaluation practice); the rule is stated in the module.
5. Vocabulary is neutral: recorded, remaining, complete, reaches, opens at. Never "behind", "chances", "qualify", "should". Doors are coverage reads, never admission predictions, match scores, or rankings.
6. The output stamps rules_version and evaluated_at so any rendered reading can be traced to the exact rule text that produced it.
7. Nothing from a plugin appears on a verifiable receipt. Doors are read to the learner; the operator never certifies eligibility for an institution.

8.3 The artifact-renderer interface

renderArtifactHtml(model, {preview, sample}) dispatches on model.artifact_type to a registered spec:

Modes: the clean render (paid, printable); preview: true (watermarked with a tiled stamp and interleaved strips, blanked under print media); sample: true (marked "SAMPLE, not for filing" but printable, for public reference pages). Preview and clean output are pixel-identical apart from the marks (the family sees the filled document free; the clean print is the paid service, the only paid family surface).

Registered artifact_types today: ny_ihip, ny_quarterly, pa_portfolio, esa_expense_quarterly, expense_529_annual, year_end_summary, portfolio_packet, good_student_letter, enrollment_letter, service_hours_letter, ny_graduation_plan, credit_evaluation_packet, annual_value_report.

Model builders take raw inputs and timeline entries (chapter 01, section 1.3, the compliance metadata hours, instruction_days, subjects, state_code) and return plain objects; for example buildIhipModel({studentName, age, grade, schoolYearStart, instructors, subjectPlans, quarters}) returns {artifact_type: "ny_ihip", student, school_year, instructors, quarters[4], required_hours, subjects[{subject, plan}], recurring}.

Disclosure text (MUST appear on every artifact with a regReference)

Prepared from your own records for your review and submission. This document is not legal advice. <regReference> is the source of truth for what your district or program requires: confirm current requirements there, and with your local district or program administrator, before you file.

Regulation and program requirements used to build this document were last reviewed <REVIEWED_AS_OF>.

REVIEWED_AS_OF (shared/reviewedAsOf.js, 2026-07-16 at the time of this draft) is one date for the regulation constants, printed on every paid artifact and shown on every state page; it is bumped by a human after re-verifying against primary sources.

8.4 Versioning rule (MUST)

• version is <jurisdiction>-<program>-<year>.<n>. Any change to a requirement, a citation, a door, a caution, or the classifier bumps n. A new statutory year is a new module file; a shipped version is never mutated (a reading produced under ny-homeschool-2026.1 must stay reproducible after .2 ships).
• verified_on is bumped only by a re-verification against primary sources, recorded in research_file.
• Every output carries rules_version and evaluated_at; every artifact carries REVIEWED_AS_OF.
• Roster-like facts that change on their own cycle (a state's diploma-organization list, an ESA vendor list) are linked, never hard-coded.

8.5 Registry at the time of this draft

8.6 Presence is earned

A plugin's presence in the registry is not a product decision by the operator; it is earned by an issuer in that jurisdiction. The earning party is an issuer (a school, network, or independent counselor) operating in that jurisdiction, who also becomes the module's maintained_by and owes its verified_on re-verification cadence. A jurisdiction with no issuer has no plugin, and the Record is complete without one.

8.7 What this does not prove

A plugin reading proves that the record's rows, classified by the stated rules on the stated date, cover the stated requirements to the stated extent. It does not prove that a district or program will accept the reading, that the rules have not changed since verified_on, or that a course titled to match a bucket was in fact that course. Every artifact says so in its footer; every reading carries the version and date that let a reader check.