<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:dc="http://purl.org/dc/elements/1.1/">
  <channel>
    <title>DEV Community: Michael Banigo</title>
    <description>The latest articles on DEV Community by Michael Banigo (@michael_banigo_6bea76d866).</description>
    <link>https://dev.to/michael_banigo_6bea76d866</link>
    <image>
      <url>https://media2.dev.to/dynamic/image/width=90,height=90,fit=cover,gravity=auto,format=auto/https:%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Fuser%2Fprofile_image%2F4208336%2Fd24c40c5-1020-4c3c-b1b0-bbcfe7fe3f39.png</url>
      <title>DEV Community: Michael Banigo</title>
      <link>https://dev.to/michael_banigo_6bea76d866</link>
    </image>
    <atom:link rel="self" type="application/rss+xml" href="https://dev.to/feed/michael_banigo_6bea76d866"/>
    <language>en</language>
    <item>
      <title>Five Free Back to School Guides: Encouragement Strategies, Study Plans and Reading Lists for Students, Lecturers and Researchers</title>
      <dc:creator>Michael Banigo</dc:creator>
      <pubDate>Thu, 29 Oct 2026 11:19:14 +0000</pubDate>
      <link>https://dev.to/michael_banigo_6bea76d866/five-free-back-to-school-guides-encouragement-strategies-study-plans-and-reading-lists-for-2d75</link>
      <guid>https://dev.to/michael_banigo_6bea76d866/five-free-back-to-school-guides-encouragement-strategies-study-plans-and-reading-lists-for-2d75</guid>
      <description>&lt;p&gt;Two weeks before term starts, the question on every forum is the same one, asked in different words: &lt;em&gt;what do I actually do now?&lt;/em&gt; For a student returning after a break, that question is about momentum. For a first-year, it is about the shape of a week. For a researcher, it is about a literature that will not stop growing. For a lecturer, it is about a class that is as nervous as you are.&lt;/p&gt;

&lt;p&gt;Five guides, one for each of those situations. Each is twenty pages or more, each is free to download, print and share, and each is written around one rule: &lt;strong&gt;no advice that you cannot act on tomorrow morning.&lt;/strong&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  The five guides at a glance
&lt;/h2&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Guide&lt;/th&gt;
&lt;th&gt;Who it is for&lt;/th&gt;
&lt;th&gt;What it gives you&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;a href="https://anyfreebook.com/guides/back-to-school-encouragement-strategies" rel="noopener noreferrer"&gt;Back to School Encouragement Strategies&lt;/a&gt;&lt;/td&gt;
&lt;td&gt;Returning students&lt;/td&gt;
&lt;td&gt;A seven-day reset before term, then a 30-day plan built around your worst week, not your best one&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;a href="https://anyfreebook.com/guides/first-30-days-university-starter-plan" rel="noopener noreferrer"&gt;The Fresher's First 30 Days&lt;/a&gt;&lt;/td&gt;
&lt;td&gt;New students and freshers&lt;/td&gt;
&lt;td&gt;Week one logistics, the lecture-to-review ratio, note-taking that survives until March, and a catch-up plan&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;a href="https://anyfreebook.com/guides/researchers-reentry-plan" rel="noopener noreferrer"&gt;The Researcher's Restart&lt;/a&gt;&lt;/td&gt;
&lt;td&gt;New and early-career researchers&lt;/td&gt;
&lt;td&gt;A three-pass reading method, an evidence ledger, a twelve-week plan, and how to survive a rejection&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;a href="https://anyfreebook.com/guides/lecturer-reentry-plan" rel="noopener noreferrer"&gt;The Lecturer's Re-entry Plan&lt;/a&gt;&lt;/td&gt;
&lt;td&gt;Lecturers, tutors and teaching fellows&lt;/td&gt;
&lt;td&gt;A fourteen-day plan before teaching, a five-session first week, assessment that students can use&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;a href="https://anyfreebook.com/guides/free-study-resources-reading-plans" rel="noopener noreferrer"&gt;Free Study Resources and Reading Plans&lt;/a&gt;&lt;/td&gt;
&lt;td&gt;Everyone&lt;/td&gt;
&lt;td&gt;The twelve open libraries, free textbooks by subject, open courseware, and six checks for a real download&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Each one is also published as a book on the site, so you can read it in the browser or take it with you: &lt;a href="https://anyfreebook.com/read/back-to-school-encouragement-strategies" rel="noopener noreferrer"&gt;back to school&lt;/a&gt;, &lt;a href="https://anyfreebook.com/read/first-30-days-university-starter-plan" rel="noopener noreferrer"&gt;first 30 days&lt;/a&gt;, &lt;a href="https://anyfreebook.com/read/researchers-reentry-plan" rel="noopener noreferrer"&gt;researcher's restart&lt;/a&gt;, &lt;a href="https://anyfreebook.com/read/lecturer-reentry-plan" rel="noopener noreferrer"&gt;lecturer's plan&lt;/a&gt;, &lt;a href="https://anyfreebook.com/read/free-study-resources-reading-plans" rel="noopener noreferrer"&gt;free study resources&lt;/a&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  Back to school encouragement strategies: for the student who has been away
&lt;/h2&gt;

&lt;p&gt;This is the guide for anyone whose last attempt ended badly. The memory of a failed term is more vivid than the evidence that you can finish one, and that is the real obstacle — not the material, not the money, not the family.&lt;/p&gt;

&lt;p&gt;The guide's premise is that the returning student who succeeds is not the one who wants it more. It is the one who built a system that still works on the worst week. So it starts by removing friction, not by generating motivation: a seven-day reset before term (paperwork and money first, because late applications are the most common reason a return gets expensive; then the physical backlog; then a timetable built around a real week rather than an ideal one), and then one habit at a time.&lt;/p&gt;

&lt;p&gt;Two ideas from it are worth repeating here. The &lt;strong&gt;floor, the standard and the stretch&lt;/strong&gt;: you design the routine around the floor — the version you can still do on a bad week — and treat the standard as the target. And the &lt;strong&gt;60/30/10 split&lt;/strong&gt; of a study week: 60% new material, 30% consolidation through retrieval and rewriting notes in your own words, 10% admin batched into one session. Returning students invert that, spending 60% on notes because notes feel productive and 10% on practice because practice feels slow. Marks come from practice.&lt;/p&gt;

&lt;h2&gt;
  
  
  The first 30 days at university: for the student who has never done this
&lt;/h2&gt;

&lt;p&gt;Nobody tells you how a week is supposed to work. Your lecturer talks about an essay with a reading week in between. Your flatmate has a colour-coded planner that looks like a decoration. Somebody in the seminar asks a question that assumes you have read four books already.&lt;/p&gt;

&lt;p&gt;The guide's first week has five things that must work by Friday: a timetable block, a deadline register, the reading list downloaded while the links still work, three names in your phone, and a place to work. Everything else can wait.&lt;/p&gt;

&lt;p&gt;Then the ratio that decides the term: &lt;strong&gt;for every hour of lecture, plan two hours of independent work&lt;/strong&gt;. And the notes: the Cornell page, with a cue column and a summary strip written after the session, which is a forty-eight-hour test — if you cannot write the summary, you did not understand it, and now you know what to re-read.&lt;/p&gt;

&lt;h2&gt;
  
  
  A reading and writing plan for new researchers
&lt;/h2&gt;

&lt;p&gt;Most new researchers do not fail because they cannot read. They fail because they read for six months and then discover that reading is not writing.&lt;/p&gt;

&lt;p&gt;The guide's answer is a three-pass method with a time budget per paper: a fifteen-minute survey that produces one sentence, a forty-five-minute argument pass that produces three claims marked agree, dispute or unclear, and a deep pass only for papers where something is disputed. Agreeing papers are for citations, not for the argument.&lt;/p&gt;

&lt;p&gt;The second idea is the &lt;strong&gt;evidence ledger&lt;/strong&gt; — one row for every claim your paper will make, with the best source found so far and a status of supported, weak, missing or contested. If more than three claims are missing, you are not writing yet. It is blunt, and it is the difference between reading and producing.&lt;/p&gt;

&lt;h2&gt;
  
  
  A first week of teaching that does not humiliate anyone
&lt;/h2&gt;

&lt;p&gt;For the lecturer coming back after a break, the uncomfortable finding is that the commonest student complaint is not difficulty with the content. It is not knowing what is expected.&lt;/p&gt;

&lt;p&gt;The guide is a fourteen-day plan before teaching and a four-week plan after, with minute-by-minute session plans. Day 14 audits the course against last year. Day 9 publishes the deadline map. Day 10 designs an ungraded diagnostic of eight questions. The rule for week one is specific: &lt;strong&gt;no new required reading&lt;/strong&gt;, because students arrive with a backlog they did not choose.&lt;/p&gt;

&lt;p&gt;And the part most courses never design for: the first session is a baseline and a first win, an eight-question diagnostic done alone and then in pairs, and a worked example from the messy original to the clean answer.&lt;/p&gt;

&lt;h2&gt;
  
  
  Free textbooks, open courseware, and how to tell a real download from a catalogue record
&lt;/h2&gt;

&lt;p&gt;The reference guide is the one people come back to. It lists the twelve open libraries with what each one actually holds and where it stops, then gives six checks that separate a file you can keep from a link that only looks free:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Signal&lt;/th&gt;
&lt;th&gt;A real download&lt;/th&gt;
&lt;th&gt;A catalogue record&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Link target&lt;/td&gt;
&lt;td&gt;Ends in .pdf, .epub, .zip, .mp3&lt;/td&gt;
&lt;td&gt;Ends in /item/, /record/, /search?&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;File size shown&lt;/td&gt;
&lt;td&gt;Yes&lt;/td&gt;
&lt;td&gt;No&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Licence shown&lt;/td&gt;
&lt;td&gt;CC BY, CC BY-SA, public domain&lt;/td&gt;
&lt;td&gt;"All rights reserved", or nothing&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Works offline&lt;/td&gt;
&lt;td&gt;Yes&lt;/td&gt;
&lt;td&gt;No, it needs the site&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Lasts if the site changes&lt;/td&gt;
&lt;td&gt;Yes, you have the file&lt;/td&gt;
&lt;td&gt;No&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;The licence point is the one that catches people. A Creative Commons licence controls &lt;strong&gt;reuse, not price&lt;/strong&gt;. CC BY lets you copy, adapt and redistribute with attribution. CC BY-SA asks you to keep the licence on adaptations. CC BY-NC forbids commercial use. CC BY-ND forbids adaptations. Those differences matter the moment you want to print a chapter, translate it, put it in a course pack, or republish it — which is exactly what happens in a school.&lt;/p&gt;

&lt;h2&gt;
  
  
  Where the free books come from
&lt;/h2&gt;

&lt;p&gt;Everything in these guides was found through open-access libraries: Project Gutenberg, Open Library, the Internet Archive, Google Books, PubMed Central, DOAJ, LibriVox, OpenAlex, Wikisource, Europeana, Zenodo and the Open Textbook Library.&lt;/p&gt;

&lt;p&gt;ANYFREEBOOK searches all of them live and marks every result as one of three things: a &lt;strong&gt;real download&lt;/strong&gt;, a &lt;strong&gt;borrow-only copy&lt;/strong&gt;, or a &lt;strong&gt;catalogue record&lt;/strong&gt;. That labelling is the product. A search engine cannot tell you a link is a lending queue, and neither can most library catalogues, so a student ends up with forty samples and calls it research. It would rather tell you that a specific book is not free anywhere than send you to a link that turns out to be a sample chapter behind a login.&lt;/p&gt;

&lt;h2&gt;
  
  
  Start with the one that fits
&lt;/h2&gt;

&lt;p&gt;If you have been away from study for a while, start with the &lt;a href="https://anyfreebook.com/guides/back-to-school-encouragement-strategies" rel="noopener noreferrer"&gt;re-entry plan&lt;/a&gt;. If you are in your first term, start with the &lt;a href="https://anyfreebook.com/guides/first-30-days-university-starter-plan" rel="noopener noreferrer"&gt;first 30 days&lt;/a&gt;. If you are about to teach again, the &lt;a href="https://anyfreebook.com/guides/lecturer-reentry-plan" rel="noopener noreferrer"&gt;lecturer's plan&lt;/a&gt; is the fourteen-day version. If you are about to write a paper, the &lt;a href="https://anyfreebook.com/guides/researchers-reentry-plan" rel="noopener noreferrer"&gt;researcher's restart&lt;/a&gt; has the method and the twelve weeks. And if you just want the shelf, take the &lt;a href="https://anyfreebook.com/guides/free-study-resources-reading-plans" rel="noopener noreferrer"&gt;free study resources guide&lt;/a&gt;.&lt;/p&gt;

&lt;p&gt;All five are free, and so is every library they point at. Send one to the person who has been putting off enrolling for two terms — that is usually the whole problem.&lt;/p&gt;

</description>
      <category>education</category>
      <category>study</category>
      <category>backtoschool</category>
      <category>productivity</category>
    </item>
    <item>
      <title>Free Study Resources and Reading Plans: 150 Books and Courses That Cost Nothing</title>
      <dc:creator>Michael Banigo</dc:creator>
      <pubDate>Thu, 29 Oct 2026 10:27:27 +0000</pubDate>
      <link>https://dev.to/michael_banigo_6bea76d866/free-study-resources-and-reading-plans-150-books-and-courses-that-cost-nothing-50oe</link>
      <guid>https://dev.to/michael_banigo_6bea76d866/free-study-resources-and-reading-plans-150-books-and-courses-that-cost-nothing-50oe</guid>
      <description>&lt;p&gt;You have been told a book is free. You clicked through, saw a cover image and the word "Read", and either hit a paywall three paragraphs in or got forty pages of a two-hundred-page book and a "buy" button. You downloaded it anyway, and it now sits in a folder called PDFs you have not opened since. You have done this eleven times.&lt;/p&gt;

&lt;p&gt;The problem is not that free books are hard to find. It is that "free" and "available" are the same thing, and they are not. Libraries are full of records: metadata about books you cannot download, catalogue entries for titles whose only copy sits in a reading room in Boston, and links that resolve to a lending queue rather than a file.&lt;/p&gt;

&lt;h2&gt;
  
  
  What the guide is
&lt;/h2&gt;

&lt;p&gt;The guide is a working map of the open shelf — what each source actually holds, how large it is, what format it uses, what it is good for, and where it stops — followed by the procedures for turning any of it into a plan you finish.&lt;/p&gt;

&lt;h3&gt;
  
  
  The twelve open libraries
&lt;/h3&gt;

&lt;p&gt;The working shelf. Sizes are orders of magnitude, not exact counts, and the guide says so.&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;#&lt;/th&gt;
&lt;th&gt;Source&lt;/th&gt;
&lt;th&gt;What it actually holds&lt;/th&gt;
&lt;th&gt;Size&lt;/th&gt;
&lt;th&gt;Formats&lt;/th&gt;
&lt;th&gt;Best for&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;1&lt;/td&gt;
&lt;td&gt;Project Gutenberg&lt;/td&gt;
&lt;td&gt;Digitised public-domain works, mostly pre-1930 literature&lt;/td&gt;
&lt;td&gt;~75,000 ebooks&lt;/td&gt;
&lt;td&gt;EPUB, Kindle, plain text, HTML&lt;/td&gt;
&lt;td&gt;Literature; offline reading&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;2&lt;/td&gt;
&lt;td&gt;Internet Archive / Open Library&lt;/td&gt;
&lt;td&gt;A lending library plus web archive: books, films, audio, software&lt;/td&gt;
&lt;td&gt;~250 million items&lt;/td&gt;
&lt;td&gt;PDF, EPUB, borrow-streamed, MP3, video&lt;/td&gt;
&lt;td&gt;Borrowable books; archival research&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;3&lt;/td&gt;
&lt;td&gt;OpenStax&lt;/td&gt;
&lt;td&gt;Peer-reviewed open textbooks&lt;/td&gt;
&lt;td&gt;~1,000+ titles&lt;/td&gt;
&lt;td&gt;PDF, online, Kindle, print-on-demand&lt;/td&gt;
&lt;td&gt;First-year university courses&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;4&lt;/td&gt;
&lt;td&gt;Open Textbook Library&lt;/td&gt;
&lt;td&gt;A catalogue of open textbooks with reviews and adoption info&lt;/td&gt;
&lt;td&gt;~4,000+ titles&lt;/td&gt;
&lt;td&gt;Mostly PDF and online&lt;/td&gt;
&lt;td&gt;Comparing textbook options&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;5&lt;/td&gt;
&lt;td&gt;BCcampus Open Textbook Collection&lt;/td&gt;
&lt;td&gt;Peer-reviewed open textbooks by subject, with attribution files&lt;/td&gt;
&lt;td&gt;~500+ titles&lt;/td&gt;
&lt;td&gt;PDF, DOCX, ebook&lt;/td&gt;
&lt;td&gt;Humanities and social science&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;6&lt;/td&gt;
&lt;td&gt;MIT OpenCourseWare&lt;/td&gt;
&lt;td&gt;Lecture notes, problem sets, exams, reading lists, often video&lt;/td&gt;
&lt;td&gt;~2,000+ courses&lt;/td&gt;
&lt;td&gt;PDF, HTML, video&lt;/td&gt;
&lt;td&gt;Studying a course you are not enrolled in&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;7&lt;/td&gt;
&lt;td&gt;OpenLearn (The Open University)&lt;/td&gt;
&lt;td&gt;Course materials built for distance learners&lt;/td&gt;
&lt;td&gt;~300+ courses&lt;/td&gt;
&lt;td&gt;PDF, HTML, video, quizzes&lt;/td&gt;
&lt;td&gt;Learning without a deadline or a fee&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;8&lt;/td&gt;
&lt;td&gt;OER Commons&lt;/td&gt;
&lt;td&gt;A discovery layer over many repositories&lt;/td&gt;
&lt;td&gt;Aggregates thousands of resources&lt;/td&gt;
&lt;td&gt;Mixed&lt;/td&gt;
&lt;td&gt;Subjects with thin open coverage&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;9&lt;/td&gt;
&lt;td&gt;DOAJ&lt;/td&gt;
&lt;td&gt;Peer-reviewed open-access journals and their metadata&lt;/td&gt;
&lt;td&gt;~19,000+ journals&lt;/td&gt;
&lt;td&gt;Articles, PDFs&lt;/td&gt;
&lt;td&gt;Free journals to read or submit to&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;10&lt;/td&gt;
&lt;td&gt;PubMed Central&lt;/td&gt;
&lt;td&gt;Free-to-read biomedical and life-science articles&lt;/td&gt;
&lt;td&gt;~9 million+ articles&lt;/td&gt;
&lt;td&gt;HTML, PDF&lt;/td&gt;
&lt;td&gt;Life sciences, medicine&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;11&lt;/td&gt;
&lt;td&gt;arXiv&lt;/td&gt;
&lt;td&gt;Preprints across physics, maths, CS, stats, economics&lt;/td&gt;
&lt;td&gt;~2.4 million+ papers&lt;/td&gt;
&lt;td&gt;PDF&lt;/td&gt;
&lt;td&gt;Newest research; a supervisor's reading list&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;12&lt;/td&gt;
&lt;td&gt;LibriVox&lt;/td&gt;
&lt;td&gt;Human-read public-domain audiobooks&lt;/td&gt;
&lt;td&gt;~10,000+ titles&lt;/td&gt;
&lt;td&gt;MP3, ZIP&lt;/td&gt;
&lt;td&gt;Long commutes; learning a language&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;h3&gt;
  
  
  Six checks to tell a real download from a catalogue record
&lt;/h3&gt;

&lt;p&gt;This is the section that saves the most time. The signals are concrete:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Signal&lt;/th&gt;
&lt;th&gt;Real download&lt;/th&gt;
&lt;th&gt;Catalogue record&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Link target&lt;/td&gt;
&lt;td&gt;Ends in .pdf/.epub/.zip/.mp3&lt;/td&gt;
&lt;td&gt;Ends in /item/, /record/, /search?&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;File size shown&lt;/td&gt;
&lt;td&gt;Yes&lt;/td&gt;
&lt;td&gt;No&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Licence shown&lt;/td&gt;
&lt;td&gt;CC BY, CC BY-SA, Public Domain&lt;/td&gt;
&lt;td&gt;"All rights reserved" or nothing&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Works offline&lt;/td&gt;
&lt;td&gt;Yes&lt;/td&gt;
&lt;td&gt;No, needs the site&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Text searchable in your own tools&lt;/td&gt;
&lt;td&gt;Yes&lt;/td&gt;
&lt;td&gt;No&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Lasts if the site changes&lt;/td&gt;
&lt;td&gt;Yes, you have the file&lt;/td&gt;
&lt;td&gt;No&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Then the three-minute habit, applied to anything you plan to build a term on:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Look for the file, not the "Read" button.&lt;/strong&gt;&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Check what the download actually is.&lt;/strong&gt; A "PDF" that is one page saying "purchase access" is a teaser. Read the last page of the introduction. If the last chapter is missing, it is a sample.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Check whether an account or an institution is required.&lt;/strong&gt; Institutional access is still paywalled if you are outside the institution.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Look for the licence.&lt;/strong&gt; No licence means all rights reserved.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Look for a second copy.&lt;/strong&gt; An OpenStax PDF plus a LibreTexts version plus an Internet Archive scan is a real open book.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Use the bibliographic record to confirm the edition.&lt;/strong&gt; Edition mismatches cost more marks than missing books.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;The licence point deserves its own note. A Creative Commons licence controls reuse, not price. &lt;strong&gt;CC BY&lt;/strong&gt; lets you copy, adapt and redistribute with attribution. &lt;strong&gt;CC BY-SA&lt;/strong&gt; asks you to keep the licence on adaptations. &lt;strong&gt;CC BY-NC&lt;/strong&gt; forbids commercial use. &lt;strong&gt;CC BY-ND&lt;/strong&gt; forbids adaptations. Those differences matter the moment you want to print a chapter, translate it, put it in a course pack, or republish it.&lt;/p&gt;

&lt;h3&gt;
  
  
  Building a reading list that gets finished
&lt;/h3&gt;

&lt;p&gt;Most free reading lists fail at week three, and the reason is arithmetic, not laziness. The guide's fix is the &lt;strong&gt;three-list system&lt;/strong&gt;: exactly one current book on your desk, a queue of the next three, and an unlimited, unranked, guilt-free someday list.&lt;/p&gt;

&lt;p&gt;The mix matters too, and it is not a link dump:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;One authoritative book on the subject — 40%.&lt;/strong&gt; Gives you the vocabulary and the shape of the field.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Three to five open textbooks and course notes — 30%.&lt;/strong&gt; Structured, tested, and they come with exercises.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Two or three classic or public-domain works — 20%.&lt;/strong&gt; Context, and the pleasure of reading something older.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Two or three recent papers — 10%.&lt;/strong&gt; Keeps you current and sharpens the other ninety per cent.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;The plan also has to survive a bad week, so each of the three twelve-week plans has a 30-minute version:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;If you have&lt;/th&gt;
&lt;th&gt;Do this&lt;/th&gt;
&lt;th&gt;Why it works&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;30 minutes a day&lt;/td&gt;
&lt;td&gt;One chapter of the anchor book, 40 pages&lt;/td&gt;
&lt;td&gt;Continuity beats volume&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;30 minutes a week&lt;/td&gt;
&lt;td&gt;One page of notes on where you got to, plus one question&lt;/td&gt;
&lt;td&gt;Prevents restart friction&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;30 minutes a month&lt;/td&gt;
&lt;td&gt;One podcast episode on the subject&lt;/td&gt;
&lt;td&gt;Keeps the thread alive&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;30 minutes and no signal&lt;/td&gt;
&lt;td&gt;A Gutenberg plain-text file, offline&lt;/td&gt;
&lt;td&gt;Works with no connection&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;30 minutes and a tired brain&lt;/td&gt;
&lt;td&gt;One classic, or one audiobook&lt;/td&gt;
&lt;td&gt;Low-effort entry keeps the chain&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Above those sit three twelve-week plans: &lt;strong&gt;Plan A&lt;/strong&gt;, the steady reader, three sessions a week at about 40 pages; &lt;strong&gt;Plan B&lt;/strong&gt;, the exam candidate, six sessions a week, targeted; &lt;strong&gt;Plan C&lt;/strong&gt;, the researcher, writing fortnightly at around 10 pages a week.&lt;/p&gt;

&lt;h2&gt;
  
  
  Download
&lt;/h2&gt;

&lt;p&gt;The full guide is free to download here: &lt;a href="https://anyfreebook.com/guides/free-study-resources-reading-plans" rel="noopener noreferrer"&gt;https://anyfreebook.com/guides/free-study-resources-reading-plans&lt;/a&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  The search behind it
&lt;/h2&gt;

&lt;p&gt;ANYFREEBOOK searches these libraries live — Project Gutenberg, Open Library, the Internet Archive, Google Books, PubMed Central, DOAJ, LibriVox, OpenAlex, Wikisource, Europeana, Zenodo and the Open Textbook Library — and marks every result as a &lt;strong&gt;real download&lt;/strong&gt;, a &lt;strong&gt;borrow-only copy&lt;/strong&gt;, or a &lt;strong&gt;catalogue record&lt;/strong&gt;. That labelling is the product: a search engine cannot tell you the link is a lending queue, and neither can most library catalogues, so a student ends up downloading forty samples and calls it research.&lt;/p&gt;

&lt;p&gt;Where the shelf is thin, the guide says so, and points to a real alternative. Its common mistakes are about over-collection:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Treating a search result as a book.&lt;/strong&gt; Try one title end to end before trusting it.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Downloading a sample and calling it a book.&lt;/strong&gt; Read the last page of the introduction first.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Building a list of fifty books.&lt;/strong&gt; Cut it to 40 per cent, then pick one as the current book.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Send it on
&lt;/h2&gt;

&lt;p&gt;Send this to the person with eleven PDFs and no reading list, or to the course convenor who assumes the reading list is a solved problem. It is free, and the six checks take three minutes.&lt;/p&gt;

&lt;p&gt;If you need a plan rather than a shelf, the returning-student 30-day plan and the first-30-days plan turn a list into a week you can keep.&lt;/p&gt;

</description>
      <category>books</category>
      <category>opensource</category>
      <category>opendata</category>
      <category>education</category>
    </item>
    <item>
      <title>The Lecturer's Re-entry Plan: Designing an Encouraging First Week of Teaching</title>
      <dc:creator>Michael Banigo</dc:creator>
      <pubDate>Thu, 29 Oct 2026 10:25:16 +0000</pubDate>
      <link>https://dev.to/michael_banigo_6bea76d866/the-lecturers-re-entry-plan-designing-an-encouraging-first-week-of-teaching-10d5</link>
      <guid>https://dev.to/michael_banigo_6bea76d866/the-lecturers-re-entry-plan-designing-an-encouraging-first-week-of-teaching-10d5</guid>
      <description>&lt;p&gt;Your slides feel behind. The reading list feels like a novel you wrote in another life. And the first email to the class — a subject line you have rewritten three times — feels like a first day. Then remember that you have had a break and they have not. Between the last session and the first one, your students had three weeks of unstructured reading, an exam period that cost some of them more sleep than it should have, and possibly a summer job, a hospital admission, a visa appointment or a family crisis.&lt;/p&gt;

&lt;p&gt;The single most common finding in student feedback about returning to a course is not difficulty with the content. It is not knowing what is expected of them.&lt;/p&gt;

&lt;p&gt;Three things are true of almost every returning class, and the guide treats all three as design problems rather than personality problems. They have lost the plot, not the ability: they can still reason, but they cannot reconstruct the vocabulary and shape of the course unaided. They are running on depleted attention, and most adults hold focused attention on a single complex narrative for fifteen to twenty-five minutes before performance drops. And they are performing for you: the quietness in the room is caution, not indifference.&lt;/p&gt;

&lt;h2&gt;
  
  
  What the guide is
&lt;/h2&gt;

&lt;p&gt;The guide is a fourteen-day plan before teaching, then a four-week plan after, with concrete timings, marks, session plans and checklists. It is written for lecturers, tutors, teaching fellows and graduate teaching assistants.&lt;/p&gt;

&lt;h3&gt;
  
  
  What the students are feeling, and what to do about it
&lt;/h3&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;What the student is feeling&lt;/th&gt;
&lt;th&gt;How it appears in the room&lt;/th&gt;
&lt;th&gt;The move that helps&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Unsure what is expected&lt;/td&gt;
&lt;td&gt;Silent first week, no questions, everything waits for a deadline&lt;/td&gt;
&lt;td&gt;State the next three deadlines out loud, in writing, in week one&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Behind on reading&lt;/td&gt;
&lt;td&gt;Blank faces at the start of the second session, no homework done&lt;/td&gt;
&lt;td&gt;Set one small, completable task per week, not five&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Anxious about being wrong&lt;/td&gt;
&lt;td&gt;No eye contact, no questions, head down&lt;/td&gt;
&lt;td&gt;Model your own error explicitly, once, early&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Lonely&lt;/td&gt;
&lt;td&gt;Arrive and leave alone, no study partner, no office hours visit&lt;/td&gt;
&lt;td&gt;Build in a pair that repeats, not a one-off mingle&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Oversubscribed with life&lt;/td&gt;
&lt;td&gt;Late, absent at 09:00, coursework piled on other modules&lt;/td&gt;
&lt;td&gt;Publish a deadline map; flag the heaviest week&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Convinced they cannot do the subject&lt;/td&gt;
&lt;td&gt;Asks permission to skip, avoids the hardest exercise&lt;/td&gt;
&lt;td&gt;Put one achievable win in week one&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;h3&gt;
  
  
  Three questions to ask before term
&lt;/h3&gt;

&lt;p&gt;Do not guess at their state. Ask, cheaply, and use the answers. First: &lt;strong&gt;what was the last thing you remember from this course?&lt;/strong&gt; A free-text box, three lines, no marks — it tells you what survived the break. Second: &lt;strong&gt;which weeks of the course feel heaviest right now?&lt;/strong&gt; A multiple-choice grid over the term weeks, so you know where to spread the load. Third: &lt;strong&gt;what would make the first three sessions useful rather than stressful?&lt;/strong&gt; Free text, read every answer before the first class meets.&lt;/p&gt;

&lt;p&gt;Put these in a five-minute anonymous form. If your institution has no survey tool, use a shared document or a one-question-per-line form; the format does not matter, the anonymity does. Ten to twenty responses will change your plan. Send it at least five days before the first session, and again after week three.&lt;/p&gt;

&lt;p&gt;The guide also insists on a small set of commitments before term, because the re-entry problem is mostly a scaffolding problem:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Rebuild the map before the detail.&lt;/strong&gt; One slide, one diagram, one page: where this course came from, where it is going, and what sits between here and the final assessment.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Remove the first hurdle.&lt;/strong&gt; Do not start with a definition nobody has met. Start with a question they can answer.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Name the break out loud.&lt;/strong&gt; Say that you have been away, that the material has moved, and that the first sessions are for getting back up to speed.&lt;/li&gt;
&lt;/ul&gt;

&lt;h3&gt;
  
  
  The fourteen-day plan
&lt;/h3&gt;

&lt;p&gt;Each day is 60 to 90 minutes of actual work. Day 14 is an audit against last year to find what has to be rebuilt from scratch. Day 13 is a one-paragraph course promise — what a student can do by week 12 that they cannot do now — reduced to a single sentence used in week one. Day 12 rebuilds the session skeleton for weeks one to four, minute by minute. Day 11 chooses the three week-one readings and checks each is readable in under 40 minutes. Day 10 designs the low-stakes diagnostic: eight questions, ten minutes, ungraded, no notes. Day 9 publishes the deadline map.&lt;/p&gt;

&lt;p&gt;The guide's advice on scope is the part experienced lecturers recognise: returning lecturers tend to over-change. Sort every element into three buckets and be ruthless about the third:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Keep.&lt;/strong&gt; Anything that worked, that students use, and that you can explain in one sentence. In most courses this is 60 to 70 per cent.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Change.&lt;/strong&gt; Anything that depends on a dead assumption: a pre-requisite nobody teaches any more, an assessment format students hated, a schedule that assumed a week of preparation you now know does not exist.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Retire.&lt;/strong&gt; Anything kept from habit or guilt. A course with fifteen readings instead of twenty-five is a better course.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;The rule for week one is specific: &lt;strong&gt;no new required reading&lt;/strong&gt;. Students arrive with a reading backlog they did not choose. Start the term with material you know cold, then add the demanding reading from week three, once the class has settled.&lt;/p&gt;

&lt;h3&gt;
  
  
  The five-session first week
&lt;/h3&gt;

&lt;p&gt;The session plan is minute-by-minute, which is what makes it usable. Session one opens with the course promise and the deadline map, then an ungraded diagnostic of eight questions done individually and then in pairs — a baseline plus a first win — then a worked example of one real problem, from the messy original to the clean answer. After the break there is a mini-lecture that rebuilds the map of the course with three ideas and three anchors, a think-pair-share on the anchor question with four answers taken, and a close that says what happens next and where to ask. Sessions two and three use a retrieval warm-up of three questions from the previous session, small-group tasks with roles printed on the sheet, and a marked sample answer compared against two student attempts. Session four ends with the week-one debrief. Session five is an in-class quiz marked by students against the answer key, then a clinic where students bring one problem and work it in pairs.&lt;/p&gt;

&lt;h2&gt;
  
  
  Download
&lt;/h2&gt;

&lt;p&gt;The full guide is free to download here: &lt;a href="https://anyfreebook.com/guides/lecturer-reentry-plan" rel="noopener noreferrer"&gt;https://anyfreebook.com/guides/lecturer-reentry-plan&lt;/a&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  Building the course on free material
&lt;/h2&gt;

&lt;p&gt;There is a section on the open teaching material your course can be built on, with an honest note on what free does and does not mean:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;OpenStax&lt;/strong&gt; — peer-reviewed textbooks in maths, science, business and economics.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;MIT OpenCourseWare and OpenLearn&lt;/strong&gt; — full course materials: lecture notes, problem sets, reading lists.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;LibreTexts&lt;/strong&gt; — collaborative notes for filling one gap in a reading list.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;The Open Textbook Library&lt;/strong&gt; — comparing whole-module texts, with reviews and adoption information.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Project Gutenberg&lt;/strong&gt; — primary-source literature in plain text and EPUB.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Open Library and the Internet Archive&lt;/strong&gt; — borrowing anything still in copyright.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;DOAJ and PubMed Central&lt;/strong&gt; — current peer-reviewed research.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Zenodo&lt;/strong&gt; — material you deposit yourself, with a DOI.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;ANYFREEBOOK searches those libraries live, along with Google Books, Wikisource, Europeana, OpenAlex and LibriVox, and marks each result as a &lt;strong&gt;real download&lt;/strong&gt;, a &lt;strong&gt;borrow-only copy&lt;/strong&gt; or a &lt;strong&gt;catalogue record&lt;/strong&gt;. For teaching this matters twice over: it keeps you from putting a dead link in a reading list, and it keeps you from telling a student that a book is free when it is only borrowable.&lt;/p&gt;

&lt;h2&gt;
  
  
  Send it on
&lt;/h2&gt;

&lt;p&gt;Send this to the colleague who is about to teach their first week back, or to the teaching assistant who will run the diagnostics without knowing what the plan was. The fourteen-day table alone is worth reading.&lt;/p&gt;

&lt;p&gt;If you are the student in that room rather than the person at the front, the first-30-days plan covers the week-one logistics from the other side of the desk.&lt;/p&gt;

</description>
      <category>teaching</category>
      <category>education</category>
      <category>highered</category>
      <category>productivity</category>
    </item>
    <item>
      <title>The Researcher's Restart: A Systematic Reading and Writing Plan for New Researchers</title>
      <dc:creator>Michael Banigo</dc:creator>
      <pubDate>Thu, 29 Oct 2026 10:22:17 +0000</pubDate>
      <link>https://dev.to/michael_banigo_6bea76d866/the-researchers-restart-a-systematic-reading-and-writing-plan-for-new-researchers-9jk</link>
      <guid>https://dev.to/michael_banigo_6bea76d866/the-researchers-restart-a-systematic-reading-and-writing-plan-for-new-researchers-9jk</guid>
      <description>&lt;p&gt;You have a broad area, a supervisor, and a deadline somewhere in the distance. You do not have a research question. You have a folder of PDFs you opened once, and every time you sit down to read, the literature gets larger rather than smaller. Six months in, you realise you have been consuming and not producing, and the annual review is closer than it was.&lt;/p&gt;

&lt;p&gt;Most new researchers do not fail because they cannot read. They fail because they read for six months and then discover that reading is not writing. A literature does not get smaller when you consume it. It becomes a room you are standing in, with walls you cannot see past.&lt;/p&gt;

&lt;p&gt;The trouble is that almost all advice on this is either encouragement or a reading list. The useful thing is a procedure: what to write down, in what order, and what "done" looks like each month.&lt;/p&gt;

&lt;h2&gt;
  
  
  What the guide is
&lt;/h2&gt;

&lt;p&gt;It is a working system rather than encouragement, and it is written as a checklist you run weekly rather than a book you read once. It covers the first six months of a project, a triage method for a literature you cannot read, a note format that turns reading into an argument, a twelve-week plan that ends with a submitted paper, and an appendix that takes you from a blank page to a submitted draft in a fortnight.&lt;/p&gt;

&lt;h3&gt;
  
  
  The first six months are for narrowing, not producing
&lt;/h3&gt;

&lt;p&gt;The standard advice to spend a year reading is bad advice for anyone with a funding review or a supervisor who asks what you did this month. The first six months have one job: turn a broad area into a question small enough to answer in a year.&lt;/p&gt;

&lt;p&gt;Before opening a database, the guide asks for twenty minutes writing half a page about what you currently believe about the field. What is the central disagreement? What do your colleagues argue about at coffee? Once you hold a position, you can read for it, and reading for a position is roughly three times faster than reading in order to be informed.&lt;/p&gt;

&lt;p&gt;Three artefacts should exist at the end of month six:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;A one-page scoping memo.&lt;/strong&gt; The question in one sentence, why it matters in three sentences, and what already exists that you have checked.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;A triage list of forty to sixty papers.&lt;/strong&gt; Every paper you looked at, each with a one-line verdict: core, useful, background, or irrelevant.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;A two-page proposal.&lt;/strong&gt; The question, the method, the data, the timeline, and the two risks you think will kill it.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;And there is a six-month map with hours per week attached, from twenty in month one to thirty in month six.&lt;/p&gt;

&lt;h3&gt;
  
  
  The three-pass method
&lt;/h3&gt;

&lt;p&gt;This is the spine of the guide, and it has a table with a time budget per paper:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Pass&lt;/th&gt;
&lt;th&gt;Time per paper&lt;/th&gt;
&lt;th&gt;What you read&lt;/th&gt;
&lt;th&gt;What you write&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;1: Survey&lt;/td&gt;
&lt;td&gt;15 to 20 minutes&lt;/td&gt;
&lt;td&gt;Abstract, intro, figures, conclusion&lt;/td&gt;
&lt;td&gt;One sentence: what did this change?&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;2: Argument&lt;/td&gt;
&lt;td&gt;45 to 60 minutes&lt;/td&gt;
&lt;td&gt;Full text, methods and results included&lt;/td&gt;
&lt;td&gt;Three claims, marked agree, dispute, or unclear&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;3: Deep&lt;/td&gt;
&lt;td&gt;2 to 3 hours&lt;/td&gt;
&lt;td&gt;Everything, plus supplement and data&lt;/td&gt;
&lt;td&gt;A note per claim, with page numbers&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;The rule that cuts most noise: only papers with at least one &lt;em&gt;dispute&lt;/em&gt; are worth a pass three. Agreeing papers are for citations, not for the argument. And the honest arithmetic that follows — aim to finish pass three on five to eight papers per month, not thirty. Twenty-five full readings in a year is already serious work.&lt;/p&gt;

&lt;h3&gt;
  
  
  One note per claim, not per paper
&lt;/h3&gt;

&lt;p&gt;A paper usually contains three to seven claims that matter to you. The guide's fix is to stop taking notes about papers and start taking notes about claims: the claim in your own words, the source, the exact location, the evidence type, your verdict.&lt;/p&gt;

&lt;p&gt;Then there is the &lt;strong&gt;evidence ledger&lt;/strong&gt; — one table of every claim your paper will make, one row each, with the best source found so far and a status of supported, weak, missing, or contested. The procedure is blunt: if more than three claims are marked missing, you are not writing yet. Go and find the evidence.&lt;/p&gt;

&lt;p&gt;The guide also has a &lt;strong&gt;disputes file&lt;/strong&gt; — every time a paper contradicts your working position, write both claims side by side and say which you believe and why. That file gives you the shape of your contribution, and it supplies the last paragraph of your introduction, which is where weak papers usually die in review.&lt;/p&gt;

&lt;h3&gt;
  
  
  Writing, and surviving a rejection
&lt;/h3&gt;

&lt;p&gt;IMRaD with word budgets, so the paper is a finite object: a 200-to-250-word abstract, a 600-to-900-word introduction, 700 to 1,200 words of methods. That totals 3,700 to 6,000 words for a first paper, which is normal. Outline first, prose second, and draft each section in a separate file with a filename and a word target.&lt;/p&gt;

&lt;p&gt;The rejection section is the one I would hand to a colleague. It gives a &lt;strong&gt;two-week response procedure&lt;/strong&gt;: wait three days before replying to anyone, then separate the reviews into three lists — genuinely fatal, fixable, and misunderstanding or preference. Most reviewers' comments fall into the third list, and conflating the three is what makes people give up.&lt;/p&gt;

&lt;p&gt;The steps, in order:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Wait three days.&lt;/strong&gt; Read the reviews once, write down everything that stung, and reply to nobody.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Separate the three lists.&lt;/strong&gt; Fatal, fixable, and misunderstanding-or-preference. Most comments sit in the third.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Read the reviews again as a stranger.&lt;/strong&gt; If two independent reviewers mention the same gap, it is a gap.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Decide the journal separately from your mood.&lt;/strong&gt; If the top journal rejects you, submit to the second on your list within a week, with the referee reports attached.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Revise before you resubmit.&lt;/strong&gt; Three weeks minimum. Revising with the reports in front of you is a rewrite, not a patch.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Answer every point.&lt;/strong&gt; Quote each comment, answer it in one to three sentences, and do not argue in the letter.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;The closing line is the point of the whole guide: a rejected paper with a written revision plan is worth more than an accepted paper you learned nothing from.&lt;/p&gt;

&lt;h2&gt;
  
  
  Download
&lt;/h2&gt;

&lt;p&gt;The full guide is free to download here: &lt;a href="https://anyfreebook.com/guides/researchers-reentry-plan" rel="noopener noreferrer"&gt;https://anyfreebook.com/guides/researchers-reentry-plan&lt;/a&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  The open literature, for free
&lt;/h2&gt;

&lt;p&gt;The guide has a section on open access that is practical rather than idealistic, including a five-step route to a specific paper you cannot afford: find the DOI, try the resolver, try Unpaywall, search the repository layer, then ask the author. Every paywalled paper has a legal route.&lt;/p&gt;

&lt;p&gt;ANYFREEBOOK searches the open libraries live — Project Gutenberg, Open Library, the Internet Archive, Google Books, PubMed Central, DOAJ, LibriVox, OpenAlex, Wikisource, Europeana, Zenodo and the Open Textbook Library — and marks each result as a &lt;strong&gt;real download&lt;/strong&gt;, a &lt;strong&gt;borrow-only copy&lt;/strong&gt;, or a &lt;strong&gt;catalogue record&lt;/strong&gt;. For a researcher that third label matters most: a link that says "free" and gives you a lending queue or a forty-page sample will not put a citation in your paper.&lt;/p&gt;

&lt;p&gt;The three tiers, in plain terms:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Real download&lt;/strong&gt; — a free, legally readable copy of that exact title, resolved from the source's own metadata.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Borrow-only copy&lt;/strong&gt; — a real Internet Archive copy that the Archive's own record says is loan-only. There is no file to fetch.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Catalogue record&lt;/strong&gt; — a record or a search-results page. The book exists; the copy does not.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Send it on
&lt;/h2&gt;

&lt;p&gt;Send this to the person who has been "starting the literature review" for three months, or to the one who took their first desk rejection personally. The three-pass method and the evidence ledger are the parts worth stealing even if you never download the file.&lt;/p&gt;

&lt;p&gt;If you teach rather than research, the lecturer's re-entry plan covers the first week of a course you have to reopen to a class that is also nervous. If you are still deciding whether to go back at all, the returning-student 30-day plan starts earlier.&lt;/p&gt;

</description>
      <category>research</category>
      <category>academicwriting</category>
      <category>phd</category>
      <category>openscience</category>
    </item>
    <item>
      <title>The Fresher's First 30 Days: A Starter Study Plan for New University Students</title>
      <dc:creator>Michael Banigo</dc:creator>
      <pubDate>Thu, 29 Oct 2026 10:19:02 +0000</pubDate>
      <link>https://dev.to/michael_banigo_6bea76d866/the-freshers-first-30-days-a-starter-study-plan-for-new-university-students-dfg</link>
      <guid>https://dev.to/michael_banigo_6bea76d866/the-freshers-first-30-days-a-starter-study-plan-for-new-university-students-dfg</guid>
      <description>&lt;p&gt;Nobody tells you how a week is supposed to work. Your lecturer talks about an essay with a reading week between now and it. Your flatmate has a colour-coded planner that looks like a decoration. Someone in your seminar asks a question that clearly assumes you have read four books already. Meanwhile you have attended three lectures, understood perhaps half of each, and are quietly convinced that everyone else got a different set of instructions.&lt;/p&gt;

&lt;p&gt;The first week of university is not about learning. It is about finding out where everything is and who to ask. Students who treat week one as a study sprint arrive at week two exhausted and behind. Students who treat it as a logistics project arrive with a timetable, three names in their phone and a clear idea of what the course expects.&lt;/p&gt;

&lt;h2&gt;
  
  
  What the guide covers
&lt;/h2&gt;

&lt;p&gt;The guide runs the first month day by day, but the useful part is the reasoning underneath it.&lt;/p&gt;

&lt;h3&gt;
  
  
  Week one: five things that must work
&lt;/h3&gt;

&lt;p&gt;By the end of the first week you should have:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;A working timetable block.&lt;/strong&gt; Two or three fixed slots per week, protected as if they were lectures. Even 90 minutes each.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;A deadline register.&lt;/strong&gt; One page: every assessed deadline, exam date and reading week date, with the week number next to each. Update it every Sunday.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;The reading list, downloaded.&lt;/strong&gt; Every item, saved now while the database still works and the links are live. Books marked "available in the library" often are not, and the reserve shelf has a three-day loan limit.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Three names.&lt;/strong&gt; One lecturer or module leader, one administrative contact, one classmate who seems to know how things work.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;A place to work.&lt;/strong&gt; On campus, find the room you will actually use. At home, clear the kitchen table.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;On day one the guide says the most important thing you do is find out where the reading list lives and how you submit work. Two questions, asked at the induction desk, the lecturer, or a second-year. Write the answers down.&lt;/p&gt;

&lt;h3&gt;
  
  
  The lecture-to-review ratio
&lt;/h3&gt;

&lt;p&gt;The rough, tested rule: &lt;strong&gt;for every hour of lecture, plan two hours of independent work.&lt;/strong&gt; One hour preparing the next lecture, one hour reviewing the last. A module with 10 lecture hours a week means 20 hours of independent work, which sounds brutal until you realise reading is not the same as sitting at a desk staring at a wall.&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Situation&lt;/th&gt;
&lt;th&gt;Lecture hours&lt;/th&gt;
&lt;th&gt;Independent hours&lt;/th&gt;
&lt;th&gt;Weekly total&lt;/th&gt;
&lt;th&gt;Realistic?&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Reading-heavy humanities module&lt;/td&gt;
&lt;td&gt;10&lt;/td&gt;
&lt;td&gt;25-30&lt;/td&gt;
&lt;td&gt;35-40&lt;/td&gt;
&lt;td&gt;Yes, if you read on paper and take notes actively&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;STEM module with problem sets&lt;/td&gt;
&lt;td&gt;12&lt;/td&gt;
&lt;td&gt;24-30&lt;/td&gt;
&lt;td&gt;36-42&lt;/td&gt;
&lt;td&gt;Yes, if problem sets are done weekly, not in a rush&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Assessment-heavy final-year module&lt;/td&gt;
&lt;td&gt;8&lt;/td&gt;
&lt;td&gt;30-40&lt;/td&gt;
&lt;td&gt;38-48&lt;/td&gt;
&lt;td&gt;Yes, but term-time pressure rises&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Group project module&lt;/td&gt;
&lt;td&gt;6&lt;/td&gt;
&lt;td&gt;20-25&lt;/td&gt;
&lt;td&gt;26-31&lt;/td&gt;
&lt;td&gt;Yes, plus meeting time you cannot control&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Part-time or employed&lt;/td&gt;
&lt;td&gt;5&lt;/td&gt;
&lt;td&gt;12-15&lt;/td&gt;
&lt;td&gt;17-20&lt;/td&gt;
&lt;td&gt;Yes, cut lecture replay, keep reading&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;The ratio is not about precision. Students under-budget independent work, then blame themselves at the end. Budget it up front.&lt;/p&gt;

&lt;h3&gt;
  
  
  The three ways a week can go
&lt;/h3&gt;

&lt;p&gt;Every week goes one of three ways, and the difference is almost always whether you read before the session that needed it. A &lt;strong&gt;type A week&lt;/strong&gt; is prepared: you read first, the lecture confirms what you half-know, the tutorial feels like a conversation. A &lt;strong&gt;type B week&lt;/strong&gt; is reactive: you did not read, you understand perhaps 40 per cent in the room, and you spend Sunday reconstructing the lecture from slides. A &lt;strong&gt;type C week&lt;/strong&gt; is detached: you did not read, the lecture went over your head, you avoided the tutorial, and you have decided this week will be reclaimed later. It will not be — it costs 2 hours of avoidance now, then 15 hours of catch-up in week seven plus guilt.&lt;/p&gt;

&lt;p&gt;The rule is unglamorous: read before the session, always, even if the reading is only twenty minutes.&lt;/p&gt;

&lt;h3&gt;
  
  
  Notes worth having in March
&lt;/h3&gt;

&lt;p&gt;The guide compares five note-taking methods honestly, then does something better: it shows the &lt;strong&gt;Cornell page&lt;/strong&gt; concretely. A narrow right-hand cue column with questions you would actually ask, a wide left column with notes in your own words, and a two-to-three-sentence summary strip written after the lecture. That summary strip is a 48-hour-old test — if you cannot write it, you did not understand the session, and now you know what to re-read.&lt;/p&gt;

&lt;p&gt;There is also a &lt;strong&gt;weekly note-cleaning routine&lt;/strong&gt;: twenty-five minutes, Sunday, every week, not optional and not "when I have time".&lt;/p&gt;

&lt;p&gt;And a set of reminders about where to keep notes:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;One place per module.&lt;/strong&gt; Notes scattered across six apps are notes you cannot find in week nine.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Searchable filenames.&lt;/strong&gt; A file called &lt;code&gt;lecture-03-ch4.docx&lt;/code&gt; costs nothing to rename now and everything later.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Backups you do not have to think about.&lt;/strong&gt; Cloud sync, not a USB stick in a drawer.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;A format you can read on a bad day.&lt;/strong&gt; Text and paper beat a PDF of slides when you are tired and on a train.&lt;/li&gt;
&lt;/ul&gt;

&lt;h3&gt;
  
  
  The timetable, the catch-up plan, the money
&lt;/h3&gt;

&lt;p&gt;The timetable section gives you a template and then a 30-minute procedure for building your real one: list every fixed commitment first, mark your peak hours, then place study into the gaps. Saturday and Sunday carry the flex, so if you are behind, Sunday's catch-up blocks absorb the gap without destroying the week.&lt;/p&gt;

&lt;p&gt;When you fall behind, the guide is specific about it in five steps — measure the gap honestly, triage by category, apply a plan matched to how far behind you are, use the five-hour catch-up day, and prevent the next gap. It also lists the ten mistakes that cost students whole terms, and the three that matter most:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Treating the first week as a study sprint.&lt;/strong&gt; Week one is for building the machine, not for running it.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Choosing a timetable you would like rather than one you can keep.&lt;/strong&gt; A timetable that fits your life is worth more than an ambitious one you abandon.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Rereading notes instead of retrieving.&lt;/strong&gt; Close the book and write what you remember.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;There is also a two-week revision plan built on active recall rather than rereading, plus sections on money, admin, housing, and the adjustments first-generation, mature and international students need.&lt;/p&gt;

&lt;h2&gt;
  
  
  Download
&lt;/h2&gt;

&lt;p&gt;The full guide is free to download here: &lt;a href="https://anyfreebook.com/guides/first-30-days-university-starter-plan" rel="noopener noreferrer"&gt;https://anyfreebook.com/guides/first-30-days-university-starter-plan&lt;/a&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  The free libraries your course is built on
&lt;/h2&gt;

&lt;p&gt;A university course assumes you own its books. You often do not. The guide has a section on finding the free version of each required text and a table of what each source is actually good for:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;The Open Textbook Library&lt;/strong&gt; — comparing whole-module texts, with reviews and adoption history.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;OpenStax&lt;/strong&gt; — peer-reviewed textbooks for first-year maths, science and economics.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;LibreTexts&lt;/strong&gt; — collaborative notes, best for filling one specific gap quickly.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Project Gutenberg&lt;/strong&gt; — public-domain literature and language texts, in EPUB and plain text.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Open Library and the Internet Archive&lt;/strong&gt; — borrowing the in-copyright edition of your course text.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;PubMed Central and DOAJ&lt;/strong&gt; — current articles in life sciences and peer-reviewed open journals.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;MIT OpenCourseWare and OpenLearn&lt;/strong&gt; — full course materials if you want to study a course you are not enrolled in.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;ANYFREEBOOK searches those libraries live, plus Google Books, Wikisource, Europeana, Zenodo, OpenAlex and LibriVox, and labels every hit as a &lt;strong&gt;real download&lt;/strong&gt;, a &lt;strong&gt;borrow-only copy&lt;/strong&gt; or a &lt;strong&gt;catalogue record&lt;/strong&gt;. It would rather tell you that a specific book is not free anywhere than send you to a link that turns out to be a sample chapter behind a login.&lt;/p&gt;

&lt;h2&gt;
  
  
  Send it on
&lt;/h2&gt;

&lt;p&gt;Send this to the person in your seminar who looks like they are keeping up but might just be good at hiding it. Or to the friend who has been reading the module page for a fortnight without opening a single PDF. It is free, and it takes twenty minutes to read the week-one section.&lt;/p&gt;

&lt;p&gt;If you are returning to study rather than starting, the companion guide is a 30-day re-entry plan for students who have been away for a while.&lt;/p&gt;

</description>
      <category>education</category>
      <category>university</category>
      <category>study</category>
      <category>productivity</category>
    </item>
    <item>
      <title>The Fresher's First 30 Days: A Starter Study Plan for New University Students</title>
      <dc:creator>Michael Banigo</dc:creator>
      <pubDate>Thu, 29 Oct 2026 10:08:22 +0000</pubDate>
      <link>https://dev.to/michael_banigo_6bea76d866/the-freshers-first-30-days-a-starter-study-plan-for-new-university-students-2kae</link>
      <guid>https://dev.to/michael_banigo_6bea76d866/the-freshers-first-30-days-a-starter-study-plan-for-new-university-students-2kae</guid>
      <description>&lt;p&gt;Nobody tells you how a week is supposed to work. Your lecturer talks about an essay with a reading week between now and it. Your flatmate has a colour-coded planner that looks like a decoration. Someone in your seminar asks a question that clearly assumes you have read four books already. Meanwhile you have attended three lectures, understood perhaps half of each, and are quietly convinced that everyone else got a different set of instructions.&lt;/p&gt;

&lt;p&gt;The first week of university is not about learning. It is about finding out where everything is and who to ask. Students who treat week one as a study sprint arrive at week two exhausted and behind. Students who treat it as a logistics project arrive with a timetable, three names in their phone and a clear idea of what the course expects.&lt;/p&gt;

&lt;h2&gt;
  
  
  What the guide covers
&lt;/h2&gt;

&lt;p&gt;The guide runs the first month day by day, but the useful part is the reasoning underneath it.&lt;/p&gt;

&lt;h3&gt;
  
  
  Week one: five things that must work
&lt;/h3&gt;

&lt;p&gt;By the end of the first week you should have:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;A working timetable block.&lt;/strong&gt; Two or three fixed slots per week, protected as if they were lectures. Even 90 minutes each.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;A deadline register.&lt;/strong&gt; One page: every assessed deadline, exam date and reading week date, with the week number next to each. Update it every Sunday.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;The reading list, downloaded.&lt;/strong&gt; Every item, saved now while the database still works and the links are live. Books marked "available in the library" often are not, and the reserve shelf has a three-day loan limit.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Three names.&lt;/strong&gt; One lecturer or module leader, one administrative contact, one classmate who seems to know how things work.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;A place to work.&lt;/strong&gt; On campus, find the room you will actually use. At home, clear the kitchen table.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;On day one the guide says the most important thing you do is find out where the reading list lives and how you submit work. Two questions, asked at the induction desk, the lecturer, or a second-year. Write the answers down.&lt;/p&gt;

&lt;h3&gt;
  
  
  The lecture-to-review ratio
&lt;/h3&gt;

&lt;p&gt;The rough, tested rule: &lt;strong&gt;for every hour of lecture, plan two hours of independent work.&lt;/strong&gt; One hour preparing the next lecture, one hour reviewing the last. A module with 10 lecture hours a week means 20 hours of independent work, which sounds brutal until you realise reading is not the same as sitting at a desk staring at a wall.&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Situation&lt;/th&gt;
&lt;th&gt;Lecture hours&lt;/th&gt;
&lt;th&gt;Independent hours&lt;/th&gt;
&lt;th&gt;Weekly total&lt;/th&gt;
&lt;th&gt;Realistic?&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Reading-heavy humanities module&lt;/td&gt;
&lt;td&gt;10&lt;/td&gt;
&lt;td&gt;25-30&lt;/td&gt;
&lt;td&gt;35-40&lt;/td&gt;
&lt;td&gt;Yes, if you read on paper and take notes actively&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;STEM module with problem sets&lt;/td&gt;
&lt;td&gt;12&lt;/td&gt;
&lt;td&gt;24-30&lt;/td&gt;
&lt;td&gt;36-42&lt;/td&gt;
&lt;td&gt;Yes, if problem sets are done weekly, not in a rush&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Assessment-heavy final-year module&lt;/td&gt;
&lt;td&gt;8&lt;/td&gt;
&lt;td&gt;30-40&lt;/td&gt;
&lt;td&gt;38-48&lt;/td&gt;
&lt;td&gt;Yes, but term-time pressure rises&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Group project module&lt;/td&gt;
&lt;td&gt;6&lt;/td&gt;
&lt;td&gt;20-25&lt;/td&gt;
&lt;td&gt;26-31&lt;/td&gt;
&lt;td&gt;Yes, plus meeting time you cannot control&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Part-time or employed&lt;/td&gt;
&lt;td&gt;5&lt;/td&gt;
&lt;td&gt;12-15&lt;/td&gt;
&lt;td&gt;17-20&lt;/td&gt;
&lt;td&gt;Yes, cut lecture replay, keep reading&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;The ratio is not about precision. Students under-budget independent work, then blame themselves at the end. Budget it up front.&lt;/p&gt;

&lt;h3&gt;
  
  
  The three ways a week can go
&lt;/h3&gt;

&lt;p&gt;Every week goes one of three ways, and the difference is almost always whether you read before the session that needed it. A &lt;strong&gt;type A week&lt;/strong&gt; is prepared: you read first, the lecture confirms what you half-know, the tutorial feels like a conversation. A &lt;strong&gt;type B week&lt;/strong&gt; is reactive: you did not read, you understand perhaps 40 per cent in the room, and you spend Sunday reconstructing the lecture from slides. A &lt;strong&gt;type C week&lt;/strong&gt; is detached: you did not read, the lecture went over your head, you avoided the tutorial, and you have decided this week will be reclaimed later. It will not be — it costs 2 hours of avoidance now, then 15 hours of catch-up in week seven plus guilt.&lt;/p&gt;

&lt;p&gt;The rule is unglamorous: read before the session, always, even if the reading is only twenty minutes.&lt;/p&gt;

&lt;h3&gt;
  
  
  Notes worth having in March
&lt;/h3&gt;

&lt;p&gt;The guide compares five note-taking methods honestly, then does something better: it shows the &lt;strong&gt;Cornell page&lt;/strong&gt; concretely. A narrow right-hand cue column with questions you would actually ask, a wide left column with notes in your own words, and a two-to-three-sentence summary strip written after the lecture. That summary strip is a 48-hour-old test — if you cannot write it, you did not understand the session, and now you know what to re-read.&lt;/p&gt;

&lt;p&gt;There is also a &lt;strong&gt;weekly note-cleaning routine&lt;/strong&gt;: twenty-five minutes, Sunday, every week, not optional and not "when I have time".&lt;/p&gt;

&lt;p&gt;And a set of reminders about where to keep notes:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;One place per module.&lt;/strong&gt; Notes scattered across six apps are notes you cannot find in week nine.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Searchable filenames.&lt;/strong&gt; A file called &lt;code&gt;lecture-03-ch4.docx&lt;/code&gt; costs nothing to rename now and everything later.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Backups you do not have to think about.&lt;/strong&gt; Cloud sync, not a USB stick in a drawer.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;A format you can read on a bad day.&lt;/strong&gt; Text and paper beat a PDF of slides when you are tired and on a train.&lt;/li&gt;
&lt;/ul&gt;

&lt;h3&gt;
  
  
  The timetable, the catch-up plan, the money
&lt;/h3&gt;

&lt;p&gt;The timetable section gives you a template and then a 30-minute procedure for building your real one: list every fixed commitment first, mark your peak hours, then place study into the gaps. Saturday and Sunday carry the flex, so if you are behind, Sunday's catch-up blocks absorb the gap without destroying the week.&lt;/p&gt;

&lt;p&gt;When you fall behind, the guide is specific about it in five steps — measure the gap honestly, triage by category, apply a plan matched to how far behind you are, use the five-hour catch-up day, and prevent the next gap. It also lists the ten mistakes that cost students whole terms, and the three that matter most:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Treating the first week as a study sprint.&lt;/strong&gt; Week one is for building the machine, not for running it.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Choosing a timetable you would like rather than one you can keep.&lt;/strong&gt; A timetable that fits your life is worth more than an ambitious one you abandon.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Rereading notes instead of retrieving.&lt;/strong&gt; Close the book and write what you remember.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;There is also a two-week revision plan built on active recall rather than rereading, plus sections on money, admin, housing, and the adjustments first-generation, mature and international students need.&lt;/p&gt;

&lt;h2&gt;
  
  
  Download
&lt;/h2&gt;

&lt;p&gt;The full guide is free to download here: &lt;a href="https://anyfreebook.com/guides/first-30-days-university-starter-plan" rel="noopener noreferrer"&gt;https://anyfreebook.com/guides/first-30-days-university-starter-plan&lt;/a&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  The free libraries your course is built on
&lt;/h2&gt;

&lt;p&gt;A university course assumes you own its books. You often do not. The guide has a section on finding the free version of each required text and a table of what each source is actually good for:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;The Open Textbook Library&lt;/strong&gt; — comparing whole-module texts, with reviews and adoption history.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;OpenStax&lt;/strong&gt; — peer-reviewed textbooks for first-year maths, science and economics.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;LibreTexts&lt;/strong&gt; — collaborative notes, best for filling one specific gap quickly.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Project Gutenberg&lt;/strong&gt; — public-domain literature and language texts, in EPUB and plain text.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Open Library and the Internet Archive&lt;/strong&gt; — borrowing the in-copyright edition of your course text.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;PubMed Central and DOAJ&lt;/strong&gt; — current articles in life sciences and peer-reviewed open journals.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;MIT OpenCourseWare and OpenLearn&lt;/strong&gt; — full course materials if you want to study a course you are not enrolled in.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;ANYFREEBOOK searches those libraries live, plus Google Books, Wikisource, Europeana, Zenodo, OpenAlex and LibriVox, and labels every hit as a &lt;strong&gt;real download&lt;/strong&gt;, a &lt;strong&gt;borrow-only copy&lt;/strong&gt; or a &lt;strong&gt;catalogue record&lt;/strong&gt;. It would rather tell you that a specific book is not free anywhere than send you to a link that turns out to be a sample chapter behind a login.&lt;/p&gt;

&lt;h2&gt;
  
  
  Send it on
&lt;/h2&gt;

&lt;p&gt;Send this to the person in your seminar who looks like they are keeping up but might just be good at hiding it. Or to the friend who has been reading the module page for a fortnight without opening a single PDF. It is free, and it takes twenty minutes to read the week-one section.&lt;/p&gt;

&lt;p&gt;If you are returning to study rather than starting, the companion guide is a 30-day re-entry plan for students who have been away for a while.&lt;/p&gt;

</description>
      <category>education</category>
      <category>university</category>
      <category>study</category>
      <category>productivity</category>
    </item>
    <item>
      <title>Back to School Encouragement Strategies: A 30-Day Re-entry Plan for Returning Students</title>
      <dc:creator>Michael Banigo</dc:creator>
      <pubDate>Thu, 29 Oct 2026 10:00:59 +0000</pubDate>
      <link>https://dev.to/michael_banigo_6bea76d866/back-to-school-encouragement-strategies-a-30-day-re-entry-plan-for-returning-students-174p</link>
      <guid>https://dev.to/michael_banigo_6bea76d866/back-to-school-encouragement-strategies-a-30-day-re-entry-plan-for-returning-students-174p</guid>
      <description>&lt;p&gt;You have been away for two years. The course is still there, the reading list still exists, and the deadline is still six weeks away. Every time you open the module page you get the same result: a flash of the old version of yourself, a calculation about whether you can still do this, and a tab closing. You have tried to start four times. The hardest part is not the material. It is that the last attempt ended badly and the memory of it is more vivid than the evidence that you are capable of finishing.&lt;/p&gt;

&lt;p&gt;Coming back is harder than starting, and it is worth saying why. Freshers get a pack list, a room, a tutor and a term plan. You get your own history, and history is the heaviest thing a person carries into a classroom. You already know what studying feels like, which is exactly why one bad day can convince you the whole return is a mistake.&lt;/p&gt;

&lt;p&gt;Three things make the re-entry harder. You are starting behind, joining a cohort that has been running for weeks and building a shared vocabulary from zero. The reasons you left are still true unless something structural changed, so returning to the same course with the same constraints is not a restart, it is a repeat of the same decision. And your identity has moved on: a course written for eighteen-year-olds can feel designed to exclude someone with a rent bill, when the fix is usually structural — part-time options, asynchronous modules, evening classes, credit for prior work.&lt;/p&gt;

&lt;h2&gt;
  
  
  What the guide is
&lt;/h2&gt;

&lt;p&gt;The guide is built around a single premise: the returning student who succeeds is not the one who wants it more, it is the one who designed a system that works on their worst week. So it does not start with motivation. It starts with removing friction and then installing one habit at a time.&lt;/p&gt;

&lt;h3&gt;
  
  
  The seven-day reset before term
&lt;/h3&gt;

&lt;p&gt;The week before term is the only window where you have time and no new obligations. The guide spends one day on each of the seven.&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Day 1, paperwork and money.&lt;/strong&gt; Find every re-enrolment deadline and write every date on one sheet. Ask for the total cost of the term in writing — fees, materials, travel, equipment, assessment costs. Then apply for anything with a deadline inside three weeks, because late applications are the most common reason a returning student cannot afford the term they planned.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Day 2, clear the physical backlog.&lt;/strong&gt; Thirty-five focused minutes with a timer: clear every work surface, put the previous attempt in one box out of sight, build one study station, and pack two bags.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Day 3, rebuild the timetable around real life.&lt;/strong&gt; Take a real week, not an ideal one. Study goes in the gaps that already exist, and you protect at least one gap entirely.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Day 4, set up the tools.&lt;/strong&gt; Tracking columns for date, planned hours, actual hours and a one-line note. Work backwards from every assessment to set reminders two weeks and one week ahead. One folder per module, consistent file names.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Days 5 to 7&lt;/strong&gt;, people, a single dry run, and then rest.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;The timetable rule is the one people quote back. A student with a full-time job typically has 8 to 12 free hours a week. Study into 12 and you break by week three. Study into 8 and you are still there in December. The worked example — two evenings of 90 and 120 minutes at the library, one lunchtime hour on campus, one evening hour at home, one Saturday morning, one Sunday review — totals 8 hours 15 minutes. The guide is explicit that you should copy the pattern, not the hours.&lt;/p&gt;

&lt;h3&gt;
  
  
  The 30-day plan
&lt;/h3&gt;

&lt;p&gt;Then comes the actual term plan, four weeks of it, with one focus, one habit to install, one thing to finish and one review per week:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Week&lt;/th&gt;
&lt;th&gt;Focus&lt;/th&gt;
&lt;th&gt;The habit to install&lt;/th&gt;
&lt;th&gt;The thing to finish&lt;/th&gt;
&lt;th&gt;Hours&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;0&lt;/td&gt;
&lt;td&gt;Remove friction&lt;/td&gt;
&lt;td&gt;Start same day, same place&lt;/td&gt;
&lt;td&gt;Setup: timetable, tools, contacts&lt;/td&gt;
&lt;td&gt;6&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;1&lt;/td&gt;
&lt;td&gt;Establish the pattern&lt;/td&gt;
&lt;td&gt;Sit down at the same time daily&lt;/td&gt;
&lt;td&gt;First submitted piece of work&lt;/td&gt;
&lt;td&gt;6-9&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;2&lt;/td&gt;
&lt;td&gt;Make it routine&lt;/td&gt;
&lt;td&gt;Weekly review every Sunday&lt;/td&gt;
&lt;td&gt;First module unit understood&lt;/td&gt;
&lt;td&gt;8-11&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;3&lt;/td&gt;
&lt;td&gt;Consolidate&lt;/td&gt;
&lt;td&gt;Two 50-minute deep blocks a week&lt;/td&gt;
&lt;td&gt;One past paper attempted&lt;/td&gt;
&lt;td&gt;9-12&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;4&lt;/td&gt;
&lt;td&gt;Extend and review&lt;/td&gt;
&lt;td&gt;Keep the floor on bad weeks&lt;/td&gt;
&lt;td&gt;Plan for the next 8 weeks&lt;/td&gt;
&lt;td&gt;10-14&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;There is also a section on the day you cannot face it, which most motivation advice skips. It gives you a five-minute contract, a Tuesday box for the tasks you keep deferring, a recovery protocol after a missed week, and an honest section on when stepping down is the right decision rather than a failure.&lt;/p&gt;

&lt;p&gt;The guide lists the classic mistakes that end returning students, and three of them recur:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Treating the restart like the first time.&lt;/strong&gt; You recreate what worked before at the same intensity on the same timetable. If that pattern ended in burnout, you are setting up the same collapse. Change one variable.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Waiting to feel ready.&lt;/strong&gt; Readiness is a mood, and moods are outputs of action, not inputs. Build the first two weeks on minimum viable effort and let the habit form before you increase the load.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Mistaking a slow start for no progress.&lt;/strong&gt; The first fortnight looks empty. It is the foundation, and it is the part most people skip, which is why most people quit in month three.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Two details worth pulling out. First, the &lt;strong&gt;60/30/10 split&lt;/strong&gt; of the week: 60% new material, 30% consolidation through retrieval practice and rewriting notes in your own words, 10% admin batched into one session. Returning students tend to invert this, spending 60% on notes because notes feel productive and 10% on practice because practice feels slow. Marks come from practice. Second, the &lt;strong&gt;floor, the standard, and the stretch&lt;/strong&gt; — you design the routine around the floor, the version you can still do on a bad week, and treat the standard as the target.&lt;/p&gt;

&lt;h2&gt;
  
  
  Download
&lt;/h2&gt;

&lt;p&gt;The full guide is free to download here: &lt;a href="https://anyfreebook.com/guides/back-to-school-encouragement-strategies" rel="noopener noreferrer"&gt;https://anyfreebook.com/guides/back-to-school-encouragement-strategies&lt;/a&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  The free libraries behind the advice
&lt;/h2&gt;

&lt;p&gt;Money is one of the three things that makes a return hard, and the guide spends a page on it with a table of free sources, each with what it is, what it is best for and one title worth starting with:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;OpenStax&lt;/strong&gt; — peer-reviewed open textbooks in maths, science, business and economics.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;MIT OpenCourseWare&lt;/strong&gt; — lecture materials and problem sets from real courses.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Project Gutenberg&lt;/strong&gt; — public-domain ebooks in EPUB and plain text for literature and languages.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Open Library and the Internet Archive&lt;/strong&gt; — the in-copyright course text, borrowed rather than bought.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;DOAJ and DOAB&lt;/strong&gt; — current research articles and open-access monographs.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;PubMed Central&lt;/strong&gt; — free full-text biomedical archive.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;LibreTexts&lt;/strong&gt; — collaborative notes for filling one specific gap.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;The Open Textbook Library&lt;/strong&gt; — a curated directory for choosing a whole-module text.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;ANYFREEBOOK searches these libraries live — along with Google Books, Wikisource, Europeana, Zenodo, OpenAlex and LibriVox — and marks every result as one of three things: a &lt;strong&gt;real download&lt;/strong&gt;, a &lt;strong&gt;borrow-only copy&lt;/strong&gt;, or a &lt;strong&gt;catalogue record&lt;/strong&gt; that only looks free. That honesty is the point of the product. It would rather show you three usable books than thirty blue links that resolve to a borrowing queue or a sample chapter.&lt;/p&gt;

&lt;h2&gt;
  
  
  If you know someone in this position
&lt;/h2&gt;

&lt;p&gt;Send this to the student who has been putting off enrolling for two terms, and to the one who told you they would start after the next break. The guide is free, and so is every library it points at.&lt;/p&gt;

&lt;p&gt;If the hardest part for you is not restarting but the first month of a course you have just started, the companion guide — a week-by-week starter plan for new students — covers reading, notes and catching up when you fall behind.&lt;/p&gt;

</description>
      <category>productivity</category>
      <category>study</category>
      <category>backtoschool</category>
      <category>education</category>
    </item>
    <item>
      <title>Recording who was in the room: session history, two partial unique indexes, and the RLS hole it uncovered</title>
      <dc:creator>Michael Banigo</dc:creator>
      <pubDate>Wed, 28 Oct 2026 17:28:21 +0000</pubDate>
      <link>https://dev.to/michael_banigo_6bea76d866/recording-who-was-in-the-room-session-history-two-partial-unique-indexes-and-the-rls-hole-it-2b12</link>
      <guid>https://dev.to/michael_banigo_6bea76d866/recording-who-was-in-the-room-session-history-two-partial-unique-indexes-and-the-rls-hole-it-2b12</guid>
      <description>&lt;p&gt;A live classroom that keeps one row is not a classroom with history. It is a classroom with a current state. The difference shows up the week a teacher asks the question that actually matters: &lt;em&gt;who was in my session on the 14th, and for how long?&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;We added that. Getting it right turned up two bugs worth writing down — one in the schema, because of how Postgres treats NULL in a unique index, and one in a row-level security policy that had been quietly handing anyone the keys to somebody else's institution.&lt;/p&gt;

&lt;h2&gt;
  
  
  What "history" needs to answer
&lt;/h2&gt;

&lt;p&gt;Three questions, and each one forces a different shape of data:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;How long did the session run?&lt;/strong&gt; — a session, with a start and an end.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Who was there?&lt;/strong&gt; — one row per attendee per session.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Was the same person there twice, or two different people?&lt;/strong&gt; — a stable identity for an attendee who never signed in.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;The third question is the one that breaks the obvious design.&lt;/p&gt;

&lt;h2&gt;
  
  
  Two tables, not one
&lt;/h2&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight sql"&gt;&lt;code&gt;&lt;span class="k"&gt;create&lt;/span&gt; &lt;span class="k"&gt;table&lt;/span&gt; &lt;span class="n"&gt;if&lt;/span&gt; &lt;span class="k"&gt;not&lt;/span&gt; &lt;span class="k"&gt;exists&lt;/span&gt; &lt;span class="k"&gt;public&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;classroom_sessions&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;
  &lt;span class="n"&gt;id&lt;/span&gt; &lt;span class="n"&gt;uuid&lt;/span&gt; &lt;span class="k"&gt;default&lt;/span&gt; &lt;span class="n"&gt;gen_random_uuid&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt; &lt;span class="k"&gt;primary&lt;/span&gt; &lt;span class="k"&gt;key&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;classroom_id&lt;/span&gt; &lt;span class="n"&gt;uuid&lt;/span&gt; &lt;span class="k"&gt;references&lt;/span&gt; &lt;span class="k"&gt;public&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;classrooms&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;id&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;on&lt;/span&gt; &lt;span class="k"&gt;delete&lt;/span&gt; &lt;span class="k"&gt;cascade&lt;/span&gt; &lt;span class="k"&gt;not&lt;/span&gt; &lt;span class="k"&gt;null&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;host_id&lt;/span&gt; &lt;span class="n"&gt;uuid&lt;/span&gt; &lt;span class="k"&gt;references&lt;/span&gt; &lt;span class="k"&gt;public&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;profiles&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;id&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;on&lt;/span&gt; &lt;span class="k"&gt;delete&lt;/span&gt; &lt;span class="k"&gt;set&lt;/span&gt; &lt;span class="k"&gt;null&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;started_at&lt;/span&gt; &lt;span class="n"&gt;timestamptz&lt;/span&gt; &lt;span class="k"&gt;not&lt;/span&gt; &lt;span class="k"&gt;null&lt;/span&gt; &lt;span class="k"&gt;default&lt;/span&gt; &lt;span class="n"&gt;now&lt;/span&gt;&lt;span class="p"&gt;(),&lt;/span&gt;
  &lt;span class="n"&gt;ended_at&lt;/span&gt; &lt;span class="n"&gt;timestamptz&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;duration_seconds&lt;/span&gt; &lt;span class="nb"&gt;int&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;attendee_count&lt;/span&gt; &lt;span class="nb"&gt;int&lt;/span&gt; &lt;span class="k"&gt;default&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;title&lt;/span&gt; &lt;span class="nb"&gt;text&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;created_at&lt;/span&gt; &lt;span class="n"&gt;timestamptz&lt;/span&gt; &lt;span class="k"&gt;default&lt;/span&gt; &lt;span class="n"&gt;now&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt;
&lt;span class="p"&gt;);&lt;/span&gt;

&lt;span class="k"&gt;create&lt;/span&gt; &lt;span class="k"&gt;table&lt;/span&gt; &lt;span class="n"&gt;if&lt;/span&gt; &lt;span class="k"&gt;not&lt;/span&gt; &lt;span class="k"&gt;exists&lt;/span&gt; &lt;span class="k"&gt;public&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;classroom_session_attendance&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;
  &lt;span class="n"&gt;id&lt;/span&gt; &lt;span class="n"&gt;uuid&lt;/span&gt; &lt;span class="k"&gt;default&lt;/span&gt; &lt;span class="n"&gt;gen_random_uuid&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt; &lt;span class="k"&gt;primary&lt;/span&gt; &lt;span class="k"&gt;key&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;session_id&lt;/span&gt; &lt;span class="n"&gt;uuid&lt;/span&gt; &lt;span class="k"&gt;references&lt;/span&gt; &lt;span class="k"&gt;public&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;classroom_sessions&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;id&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;on&lt;/span&gt; &lt;span class="k"&gt;delete&lt;/span&gt; &lt;span class="k"&gt;cascade&lt;/span&gt; &lt;span class="k"&gt;not&lt;/span&gt; &lt;span class="k"&gt;null&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;classroom_id&lt;/span&gt; &lt;span class="n"&gt;uuid&lt;/span&gt; &lt;span class="k"&gt;references&lt;/span&gt; &lt;span class="k"&gt;public&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;classrooms&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;id&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;on&lt;/span&gt; &lt;span class="k"&gt;delete&lt;/span&gt; &lt;span class="k"&gt;cascade&lt;/span&gt; &lt;span class="k"&gt;not&lt;/span&gt; &lt;span class="k"&gt;null&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;user_id&lt;/span&gt; &lt;span class="n"&gt;uuid&lt;/span&gt; &lt;span class="k"&gt;references&lt;/span&gt; &lt;span class="k"&gt;public&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;profiles&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;id&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;on&lt;/span&gt; &lt;span class="k"&gt;delete&lt;/span&gt; &lt;span class="k"&gt;set&lt;/span&gt; &lt;span class="k"&gt;null&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;guest_id&lt;/span&gt; &lt;span class="nb"&gt;text&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;display_name&lt;/span&gt; &lt;span class="nb"&gt;text&lt;/span&gt; &lt;span class="k"&gt;not&lt;/span&gt; &lt;span class="k"&gt;null&lt;/span&gt; &lt;span class="k"&gt;default&lt;/span&gt; &lt;span class="s1"&gt;'Guest'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;joined_at&lt;/span&gt; &lt;span class="n"&gt;timestamptz&lt;/span&gt; &lt;span class="k"&gt;not&lt;/span&gt; &lt;span class="k"&gt;null&lt;/span&gt; &lt;span class="k"&gt;default&lt;/span&gt; &lt;span class="n"&gt;now&lt;/span&gt;&lt;span class="p"&gt;(),&lt;/span&gt;
  &lt;span class="n"&gt;left_at&lt;/span&gt; &lt;span class="n"&gt;timestamptz&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;watch_seconds&lt;/span&gt; &lt;span class="nb"&gt;int&lt;/span&gt; &lt;span class="k"&gt;default&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="k"&gt;check&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;user_id&lt;/span&gt; &lt;span class="k"&gt;is&lt;/span&gt; &lt;span class="k"&gt;not&lt;/span&gt; &lt;span class="k"&gt;null&lt;/span&gt; &lt;span class="k"&gt;or&lt;/span&gt; &lt;span class="n"&gt;guest_id&lt;/span&gt; &lt;span class="k"&gt;is&lt;/span&gt; &lt;span class="k"&gt;not&lt;/span&gt; &lt;span class="k"&gt;null&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="p"&gt;);&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The &lt;code&gt;check&lt;/code&gt; constraint is the first statement of intent: an attendance row must identify &lt;em&gt;someone&lt;/em&gt;. Either a signed-in profile, or a guest id. Not neither.&lt;/p&gt;

&lt;p&gt;Note that &lt;code&gt;user_id&lt;/code&gt; and &lt;code&gt;guest_id&lt;/code&gt; are mutually exclusive in practice but not by constraint. That is deliberate, and it is the direct cause of the bug below.&lt;/p&gt;

&lt;h2&gt;
  
  
  The bug: one composite unique index does not work
&lt;/h2&gt;

&lt;p&gt;The natural instinct is one unique index over the whole identity triple:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight sql"&gt;&lt;code&gt;&lt;span class="c1"&gt;-- WRONG. Do not do this.&lt;/span&gt;
&lt;span class="k"&gt;create&lt;/span&gt; &lt;span class="k"&gt;unique&lt;/span&gt; &lt;span class="k"&gt;index&lt;/span&gt; &lt;span class="n"&gt;uq_att&lt;/span&gt; &lt;span class="k"&gt;on&lt;/span&gt; &lt;span class="n"&gt;classroom_session_attendance&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;session_id&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;user_id&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;guest_id&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;It looks correct. It enforces "one row per attendee per session" — except it does not, because in Postgres NULL never equals another NULL.&lt;/p&gt;

&lt;p&gt;&lt;code&gt;NULL = NULL&lt;/code&gt; evaluates to NULL, not to true. A unique index treats rows as duplicates only when the comparison is &lt;em&gt;true&lt;/em&gt;. So a signed-in attendee, whose row is &lt;code&gt;(session_id, 'abc-123', NULL)&lt;/code&gt;, can be inserted any number of times: the second row's &lt;code&gt;guest_id&lt;/code&gt; is also NULL, and NULL is not equal to NULL, so the index sees no conflict.&lt;/p&gt;

&lt;p&gt;In practice that means every reconnect — every refresh, every flaky network, every tab opened twice — adds another row for the same person. The attendance count inflates, the list of names fills with duplicates, and nothing errors. It fails silently, which is the worst way for it to fail.&lt;/p&gt;

&lt;p&gt;The fix is two partial unique indexes, one per identity kind:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight sql"&gt;&lt;code&gt;&lt;span class="k"&gt;create&lt;/span&gt; &lt;span class="k"&gt;unique&lt;/span&gt; &lt;span class="k"&gt;index&lt;/span&gt; &lt;span class="n"&gt;if&lt;/span&gt; &lt;span class="k"&gt;not&lt;/span&gt; &lt;span class="k"&gt;exists&lt;/span&gt; &lt;span class="n"&gt;uq_class_sess_att_user&lt;/span&gt;
  &lt;span class="k"&gt;on&lt;/span&gt; &lt;span class="k"&gt;public&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;classroom_session_attendance&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;session_id&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;user_id&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="k"&gt;where&lt;/span&gt; &lt;span class="n"&gt;user_id&lt;/span&gt; &lt;span class="k"&gt;is&lt;/span&gt; &lt;span class="k"&gt;not&lt;/span&gt; &lt;span class="k"&gt;null&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="k"&gt;create&lt;/span&gt; &lt;span class="k"&gt;unique&lt;/span&gt; &lt;span class="k"&gt;index&lt;/span&gt; &lt;span class="n"&gt;if&lt;/span&gt; &lt;span class="k"&gt;not&lt;/span&gt; &lt;span class="k"&gt;exists&lt;/span&gt; &lt;span class="n"&gt;uq_class_sess_att_guest&lt;/span&gt;
  &lt;span class="k"&gt;on&lt;/span&gt; &lt;span class="k"&gt;public&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;classroom_session_attendance&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;session_id&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;guest_id&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="k"&gt;where&lt;/span&gt; &lt;span class="n"&gt;guest_id&lt;/span&gt; &lt;span class="k"&gt;is&lt;/span&gt; &lt;span class="k"&gt;not&lt;/span&gt; &lt;span class="k"&gt;null&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Each index covers only the rows it applies to. The &lt;code&gt;where&lt;/code&gt; clause is what makes the NULL problem disappear: rows with a NULL &lt;code&gt;user_id&lt;/code&gt; are not in the user index at all, so they cannot conflict there, and the guest index handles them with a real, non-NULL value.&lt;/p&gt;

&lt;p&gt;The client has to match, which means the upsert conflict target is chosen at runtime:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// Signed-in attendees are keyed on user_id, anonymous ones on guest_id.&lt;/span&gt;
&lt;span class="c1"&gt;// A single composite conflict target would not work, because a NULL&lt;/span&gt;
&lt;span class="c1"&gt;// guest_id never equals another NULL and would insert a duplicate row&lt;/span&gt;
&lt;span class="c1"&gt;// on every reconnect.&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;conflict&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;user&lt;/span&gt; &lt;span class="p"&gt;?&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;session_id,user_id&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt; &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;session_id,guest_id&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nx"&gt;sb&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="k"&gt;from&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;classroom_session_attendance&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;).&lt;/span&gt;&lt;span class="nf"&gt;upsert&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
  &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nx"&gt;session_id&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;classroom_id&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="na"&gt;user_id&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;user&lt;/span&gt;&lt;span class="p"&gt;?.&lt;/span&gt;&lt;span class="nx"&gt;id&lt;/span&gt; &lt;span class="o"&gt;??&lt;/span&gt; &lt;span class="kc"&gt;null&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="na"&gt;guest_id&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;user&lt;/span&gt; &lt;span class="p"&gt;?&lt;/span&gt; &lt;span class="kc"&gt;null&lt;/span&gt; &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nf"&gt;getGuestId&lt;/span&gt;&lt;span class="p"&gt;(),&lt;/span&gt; &lt;span class="nx"&gt;display_name&lt;/span&gt; &lt;span class="p"&gt;},&lt;/span&gt;
  &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;onConflict&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;conflict&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;);&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  The anonymous attendee needs a stable identity
&lt;/h2&gt;

&lt;p&gt;A signed-in attendee has a profile id, so their identity is free. An anonymous visitor does not, and "the person who was there" has to mean something across two separate sessions a week apart.&lt;/p&gt;

&lt;p&gt;The answer is a random id kept in &lt;code&gt;localStorage&lt;/code&gt;:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;getGuestId&lt;/span&gt;&lt;span class="p"&gt;():&lt;/span&gt; &lt;span class="kr"&gt;string&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;KEY&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;afb_guest_id&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;typeof&lt;/span&gt; &lt;span class="nb"&gt;window&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;undefined&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;guest-server&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="kd"&gt;let&lt;/span&gt; &lt;span class="nx"&gt;id&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;localStorage&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;getItem&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;KEY&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="nx"&gt;id&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="nx"&gt;id&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;`g_&lt;/span&gt;&lt;span class="p"&gt;${&lt;/span&gt;&lt;span class="nb"&gt;Math&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;random&lt;/span&gt;&lt;span class="p"&gt;().&lt;/span&gt;&lt;span class="nf"&gt;toString&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;36&lt;/span&gt;&lt;span class="p"&gt;).&lt;/span&gt;&lt;span class="nf"&gt;slice&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;2&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;10&lt;/span&gt;&lt;span class="p"&gt;)}${&lt;/span&gt;&lt;span class="nb"&gt;Date&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;now&lt;/span&gt;&lt;span class="p"&gt;().&lt;/span&gt;&lt;span class="nf"&gt;toString&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;36&lt;/span&gt;&lt;span class="p"&gt;)}&lt;/span&gt;&lt;span class="s2"&gt;`&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="nx"&gt;localStorage&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;setItem&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;KEY&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;id&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nx"&gt;id&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;It is not a fingerprint, not a tracking identifier, and not derived from anything about the person. It is a handle so that the same anonymous browser looks like the same attendee next time, and so that the host sees "g_k3f9x2ab" rather than a new stranger every class.&lt;/p&gt;

&lt;p&gt;The host panel shows the display name where there is one and marks the rest as a guest, so nobody is misled about who actually signed up.&lt;/p&gt;

&lt;h2&gt;
  
  
  Let the database own the derived numbers
&lt;/h2&gt;

&lt;p&gt;Two fields on the session row are derived: how long it ran, and how many people attended. The obvious implementation computes them in the browser, and the obvious implementation is wrong — a browser that closes, a tab that is killed, or a client that simply forgets produces a session with a wrong duration or a wrong count, and there is nothing to compare against.&lt;/p&gt;

&lt;p&gt;Two triggers instead:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight sql"&gt;&lt;code&gt;&lt;span class="c1"&gt;-- Keep the denormalised counter true whenever an attendee row changes.&lt;/span&gt;
&lt;span class="k"&gt;create&lt;/span&gt; &lt;span class="k"&gt;or&lt;/span&gt; &lt;span class="k"&gt;replace&lt;/span&gt; &lt;span class="k"&gt;function&lt;/span&gt; &lt;span class="k"&gt;public&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;bump_classroom_session_counts&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt; &lt;span class="k"&gt;returns&lt;/span&gt; &lt;span class="k"&gt;trigger&lt;/span&gt; &lt;span class="k"&gt;as&lt;/span&gt; &lt;span class="err"&gt;$$&lt;/span&gt;
&lt;span class="k"&gt;declare&lt;/span&gt;
  &lt;span class="n"&gt;v_session&lt;/span&gt; &lt;span class="n"&gt;uuid&lt;/span&gt; &lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;coalesce&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;new&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;session_id&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="k"&gt;old&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;session_id&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;span class="k"&gt;begin&lt;/span&gt;
  &lt;span class="k"&gt;update&lt;/span&gt; &lt;span class="k"&gt;public&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;classroom_sessions&lt;/span&gt;
  &lt;span class="k"&gt;set&lt;/span&gt; &lt;span class="n"&gt;attendee_count&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;
        &lt;span class="k"&gt;select&lt;/span&gt; &lt;span class="k"&gt;count&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;*&lt;/span&gt;&lt;span class="p"&gt;)::&lt;/span&gt;&lt;span class="nb"&gt;int&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="k"&gt;public&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;classroom_session_attendance&lt;/span&gt; &lt;span class="k"&gt;where&lt;/span&gt; &lt;span class="n"&gt;session_id&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;v_session&lt;/span&gt;
      &lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="k"&gt;where&lt;/span&gt; &lt;span class="n"&gt;id&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;v_session&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="k"&gt;null&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;end&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="err"&gt;$$&lt;/span&gt; &lt;span class="k"&gt;language&lt;/span&gt; &lt;span class="n"&gt;plpgsql&lt;/span&gt; &lt;span class="k"&gt;security&lt;/span&gt; &lt;span class="k"&gt;definer&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="c1"&gt;-- Fill in the duration when a session ends.&lt;/span&gt;
&lt;span class="k"&gt;create&lt;/span&gt; &lt;span class="k"&gt;or&lt;/span&gt; &lt;span class="k"&gt;replace&lt;/span&gt; &lt;span class="k"&gt;function&lt;/span&gt; &lt;span class="k"&gt;public&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;set_classroom_session_duration&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt; &lt;span class="k"&gt;returns&lt;/span&gt; &lt;span class="k"&gt;trigger&lt;/span&gt; &lt;span class="k"&gt;as&lt;/span&gt; &lt;span class="err"&gt;$$&lt;/span&gt;
&lt;span class="k"&gt;begin&lt;/span&gt;
  &lt;span class="n"&gt;if&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;ended_at&lt;/span&gt; &lt;span class="k"&gt;is&lt;/span&gt; &lt;span class="k"&gt;not&lt;/span&gt; &lt;span class="k"&gt;null&lt;/span&gt; &lt;span class="k"&gt;and&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;new&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;duration_seconds&lt;/span&gt; &lt;span class="k"&gt;is&lt;/span&gt; &lt;span class="k"&gt;null&lt;/span&gt; &lt;span class="k"&gt;or&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;duration_seconds&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;then&lt;/span&gt;
    &lt;span class="k"&gt;new&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;duration_seconds&lt;/span&gt; &lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;greatest&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="k"&gt;extract&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;epoch&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;new&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;ended_at&lt;/span&gt; &lt;span class="o"&gt;-&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;started_at&lt;/span&gt;&lt;span class="p"&gt;))::&lt;/span&gt;&lt;span class="nb"&gt;int&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="k"&gt;end&lt;/span&gt; &lt;span class="n"&gt;if&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;end&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="err"&gt;$$&lt;/span&gt; &lt;span class="k"&gt;language&lt;/span&gt; &lt;span class="n"&gt;plpgsql&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The duration trigger is &lt;code&gt;before update&lt;/code&gt;, so it writes into the row that is being updated. The count trigger is &lt;code&gt;after insert or delete&lt;/code&gt; on the attendance table and re-derives the count. &lt;code&gt;security definer&lt;/code&gt; matters here: the trigger updates &lt;code&gt;classroom_sessions&lt;/code&gt;, and without it the update would run as the invoking user, who may well not be allowed to write session rows.&lt;/p&gt;

&lt;p&gt;The client then only has to write &lt;code&gt;ended_at&lt;/code&gt; and let the database work out the rest:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;endClassroomSession&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;sessionId&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kr"&gt;string&lt;/span&gt;&lt;span class="p"&gt;):&lt;/span&gt; &lt;span class="nb"&gt;Promise&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;error&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kr"&gt;string&lt;/span&gt; &lt;span class="o"&gt;|&lt;/span&gt; &lt;span class="kc"&gt;null&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;sb&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nf"&gt;createClient&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nx"&gt;error&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nx"&gt;sb&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="k"&gt;from&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;classroom_sessions&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;update&lt;/span&gt;&lt;span class="p"&gt;({&lt;/span&gt; &lt;span class="na"&gt;ended_at&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;Date&lt;/span&gt;&lt;span class="p"&gt;().&lt;/span&gt;&lt;span class="nf"&gt;toISOString&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt; &lt;span class="p"&gt;})&lt;/span&gt;
    &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;eq&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;id&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;sessionId&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;error&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;error&lt;/span&gt;&lt;span class="p"&gt;?.&lt;/span&gt;&lt;span class="nx"&gt;message&lt;/span&gt; &lt;span class="o"&gt;??&lt;/span&gt; &lt;span class="kc"&gt;null&lt;/span&gt; &lt;span class="p"&gt;};&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Verified against production: a seeded 42-minute session with two signed-in attendees and one guest came back as &lt;code&gt;duration_seconds: 2520&lt;/code&gt; and &lt;code&gt;attendee_count: 3&lt;/code&gt;, both written by the triggers rather than by the client.&lt;/p&gt;

&lt;h2&gt;
  
  
  The hole: "self-join" was "take over"
&lt;/h2&gt;

&lt;p&gt;The other half of this change was letting a reader join an institution without an invite. The existing policy on &lt;code&gt;institution_members&lt;/code&gt; looked like this:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight sql"&gt;&lt;code&gt;&lt;span class="k"&gt;create&lt;/span&gt; &lt;span class="n"&gt;policy&lt;/span&gt; &lt;span class="nv"&gt;"admins add members"&lt;/span&gt; &lt;span class="k"&gt;on&lt;/span&gt; &lt;span class="k"&gt;public&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;institution_members&lt;/span&gt;
  &lt;span class="k"&gt;for&lt;/span&gt; &lt;span class="k"&gt;insert&lt;/span&gt; &lt;span class="k"&gt;with&lt;/span&gt; &lt;span class="k"&gt;check&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;auth&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;uid&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;profile_id&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Read it carefully. It permits an insert when the row's &lt;code&gt;profile_id&lt;/code&gt; is the current user — and says nothing at all about the &lt;code&gt;role&lt;/code&gt; column. The role is attacker-controlled data in that row.&lt;/p&gt;

&lt;p&gt;So any signed-in user could insert themselves into any institution with &lt;code&gt;role = 'owner'&lt;/code&gt;. Not "join" — take over. The owner of the institution would then find their own institution controlled by a stranger, and every downstream permission check that trusts the owner role would be answering for the wrong person.&lt;/p&gt;

&lt;p&gt;The fix is to constrain the role in the same policy, so that a self-insert can only ever be a student:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight sql"&gt;&lt;code&gt;&lt;span class="k"&gt;create&lt;/span&gt; &lt;span class="n"&gt;policy&lt;/span&gt; &lt;span class="nv"&gt;"admins add members"&lt;/span&gt; &lt;span class="k"&gt;on&lt;/span&gt; &lt;span class="k"&gt;public&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;institution_members&lt;/span&gt;
  &lt;span class="k"&gt;for&lt;/span&gt; &lt;span class="k"&gt;insert&lt;/span&gt; &lt;span class="k"&gt;with&lt;/span&gt; &lt;span class="k"&gt;check&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;
    &lt;span class="p"&gt;(&lt;/span&gt;
      &lt;span class="n"&gt;auth&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;uid&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;profile_id&lt;/span&gt;
      &lt;span class="k"&gt;and&lt;/span&gt; &lt;span class="k"&gt;role&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s1"&gt;'student'&lt;/span&gt;
    &lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="k"&gt;or&lt;/span&gt; &lt;span class="k"&gt;exists&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;select&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="k"&gt;public&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;institutions&lt;/span&gt; &lt;span class="n"&gt;i&lt;/span&gt; &lt;span class="k"&gt;where&lt;/span&gt; &lt;span class="n"&gt;i&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;id&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;institution_id&lt;/span&gt; &lt;span class="k"&gt;and&lt;/span&gt; &lt;span class="n"&gt;i&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;owner_id&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;auth&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;uid&lt;/span&gt;&lt;span class="p"&gt;())&lt;/span&gt;
    &lt;span class="k"&gt;or&lt;/span&gt; &lt;span class="k"&gt;exists&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;
      &lt;span class="k"&gt;select&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="k"&gt;public&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;institution_members&lt;/span&gt; &lt;span class="n"&gt;m&lt;/span&gt;
      &lt;span class="k"&gt;where&lt;/span&gt; &lt;span class="n"&gt;m&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;institution_id&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;institution_members&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;institution_id&lt;/span&gt;
        &lt;span class="k"&gt;and&lt;/span&gt; &lt;span class="n"&gt;m&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;profile_id&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;auth&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;uid&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt;
        &lt;span class="k"&gt;and&lt;/span&gt; &lt;span class="n"&gt;m&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="k"&gt;role&lt;/span&gt; &lt;span class="k"&gt;in&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'owner'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="s1"&gt;'admin'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="p"&gt;);&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The three branches are: you are joining yourself, and only as a student; or you own the institution; or you are an owner or admin of it. Owners and admins are still added by owners and admins. Nobody can grant themselves a role they were not given.&lt;/p&gt;

&lt;p&gt;There is a matching change in the client, because the database rule is not the whole story. The client must not &lt;em&gt;upsert&lt;/em&gt; on join:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// Joining never upserts: an existing membership is left exactly as it is, so&lt;/span&gt;
&lt;span class="c1"&gt;// a self-join cannot demote an owner or re-grant a role.&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;An upsert here would take the row for an existing owner and write &lt;code&gt;role = 'student'&lt;/code&gt; over it — not a takeover, but a self-inflicted demotion, and in a school that is just as broken. The database policy says what a &lt;em&gt;new&lt;/em&gt; row may contain; the client decides whether it is writing a new row at all.&lt;/p&gt;

&lt;p&gt;This is the general shape of RLS work: the policy constrains the row, and the client constrains the write. Both have to agree, or the stricter one is either bypassed or useless.&lt;/p&gt;

&lt;h2&gt;
  
  
  What the host sees
&lt;/h2&gt;

&lt;p&gt;The host-only panel lists each session newest-first with its duration, its attendance count, the number of unique people across the class's history, the total time taught, and per attendee the display name, their minutes in the room, and whether they were signed in or a guest:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;📊 Class history

  Sessions   Attendances   Unique people   Time taught
     3            47            31           6h 12m

  Mon, 27 Oct, 14:00
  42m · 3 attendees
    Amara Okonkwo            38m
    tunde_a                   41m
    g_k3f9x2ab   guest         12m
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Attendee rows are readable by anyone who can see the classroom, because the history is not private information — it is the class roster. Only the host can write to it, and only the host can correct a display name.&lt;/p&gt;

&lt;h2&gt;
  
  
  The takeaways
&lt;/h2&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;A unique index over a nullable column is not a uniqueness constraint.&lt;/strong&gt; NULL is not equal to NULL, so a composite unique over &lt;code&gt;(session_id, user_id, guest_id)&lt;/code&gt; permits unlimited duplicate rows for signed-in users. Use partial unique indexes, one per identity kind.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Derive, do not trust.&lt;/strong&gt; Duration and attendance count belong in triggers. A browser cannot be relied on to report how long a class lasted, and a derived number that lives only in client memory cannot be audited.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Read your own policies as an attacker would.&lt;/strong&gt; "You may insert a row where you are the subject" is a statement about &lt;em&gt;who&lt;/em&gt;, not about &lt;em&gt;what&lt;/em&gt;. If the row carries a role, the role has to be in the policy too.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;The strictest layer is only as good as the layer above it.&lt;/strong&gt; A policy that forbids self-promotion is defeated by a client that upserts. Write both, and check that they agree.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;The whole change is about a teacher being able to answer "who was actually there" without guessing. That answer is only worth anything if the database will not let it be faked, and the schema that stores it will not quietly duplicate a person's attendance every time they reconnect.&lt;/p&gt;

</description>
      <category>postgres</category>
      <category>security</category>
      <category>rls</category>
      <category>database</category>
    </item>
    <item>
      <title>One codebase, two install paths: shipping a PWA and an Android app from the same Next.js site</title>
      <dc:creator>Michael Banigo</dc:creator>
      <pubDate>Tue, 27 Oct 2026 00:54:51 +0000</pubDate>
      <link>https://dev.to/michael_banigo_6bea76d866/one-codebase-two-install-paths-shipping-a-pwa-and-an-android-app-from-the-same-nextjs-site-2nl7</link>
      <guid>https://dev.to/michael_banigo_6bea76d866/one-codebase-two-install-paths-shipping-a-pwa-and-an-android-app-from-the-same-nextjs-site-2nl7</guid>
      <description>&lt;p&gt;The Play build of ANYFREEBOOK is 1.2 MB. Almost none of that is the app. It is an Android shell around the website that already exists, and the interesting engineering is not in the shell — it is in the handshake that lets Android believe the shell owns your domain.&lt;/p&gt;

&lt;h2&gt;
  
  
  What a Trusted Web Activity actually is
&lt;/h2&gt;

&lt;p&gt;A TWA is an Android activity that loads a URL inside a WebView with the browser chrome stripped away. There is no duplicated application code, no second build of the product, nothing to keep in sync. The Play listing for ANYFREEBOOK is exactly that: package &lt;code&gt;com.anyfreebook.app&lt;/code&gt;, host &lt;code&gt;anyfreebook.com&lt;/code&gt;, full scope so every route stays inside the app.&lt;/p&gt;

&lt;p&gt;The package is built with Bubblewrap over the same Next.js site, and the numbers that matter are small: &lt;code&gt;minSdkVersion&lt;/code&gt; 24, &lt;code&gt;targetSdk&lt;/code&gt; 36, and a 1.2 MB app bundle. Compare that with shipping the same features natively — a second codebase, a second release train, and a product version that is always behind the website. The TWA gets you a Play listing, a launcher icon, and a native share sheet. Everything else is the website.&lt;/p&gt;

&lt;h2&gt;
  
  
  Digital Asset Links is the actual handshake
&lt;/h2&gt;

&lt;p&gt;Before Play will open your site in the app shell instead of a browser tab, something has to prove the domain owns the app. That proof is Digital Asset Links, and it has two halves that must agree:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;A statement served from your domain at &lt;code&gt;/.well-known/assetlinks.json&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;An equivalent statement embedded in the installed app.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;If either half is missing or the two disagree, the link degrades to a Custom Tab. The site still opens — inside a browser-chrome shell, which reads as "the app is broken" rather than "the app is being cautious".&lt;/p&gt;

&lt;p&gt;Here is what we publish:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight json"&gt;&lt;code&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="w"&gt;
    &lt;/span&gt;&lt;span class="nl"&gt;"relation"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="w"&gt;
      &lt;/span&gt;&lt;span class="s2"&gt;"delegate_permission/common.handle_all_urls"&lt;/span&gt;&lt;span class="w"&gt;
    &lt;/span&gt;&lt;span class="p"&gt;],&lt;/span&gt;&lt;span class="w"&gt;
    &lt;/span&gt;&lt;span class="nl"&gt;"target"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="w"&gt;
      &lt;/span&gt;&lt;span class="nl"&gt;"namespace"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"android_app"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
      &lt;/span&gt;&lt;span class="nl"&gt;"package_name"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"com.anyfreebook.app"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
      &lt;/span&gt;&lt;span class="nl"&gt;"sha256_cert_fingerprints"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="w"&gt;
        &lt;/span&gt;&lt;span class="s2"&gt;"A6:76:B1:D9:64:9E:4F:5A:34:4D:EB:06:9B:31:64:00:15:F4:6E:76:79:96:C6:FA:13:56:BE:FA:D6:F7:90:C2"&lt;/span&gt;&lt;span class="w"&gt;
      &lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="w"&gt;
    &lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="w"&gt;
&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="w"&gt;
&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The &lt;code&gt;relation&lt;/code&gt; is the part people skip. &lt;code&gt;delegate_permission/common.handle_all_urls&lt;/code&gt; says "this app may handle every URL on this host" — broad delegation, rather than a list of individual paths. Scope it narrowly and only the paths you listed open in the app shell, with everything else falling back to the browser.&lt;/p&gt;

&lt;h2&gt;
  
  
  The bug that cost me an afternoon: fingerprints are uppercase-only
&lt;/h2&gt;

&lt;p&gt;The fingerprint above is uppercase, and that is not a style choice.&lt;/p&gt;

&lt;p&gt;Google's Digital Asset Links validator parses certificate fingerprints with the same pattern Bubblewrap uses:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;/^([0-9A-F]{2}:){31}[0-9A-F]{2}$/
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Look at the character class: &lt;code&gt;[0-9A-F]&lt;/code&gt;. Uppercase only — there is no &lt;code&gt;a-f&lt;/code&gt; in the range. A lowercase fingerprint, the same 32 bytes and the same certificate, is rejected as &lt;code&gt;malformed cert fingerprint&lt;/code&gt;. The validator never gets as far as checking whether the fingerprint matches anything: it refuses to parse the shape.&lt;/p&gt;

&lt;p&gt;The fix is one call to &lt;code&gt;.toUpperCase()&lt;/code&gt;, but the reliable way to apply it is to make it impossible to forget. Our generator validates and normalises every fingerprint before writing the file:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// scripts/make-assetlinks.mjs&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;cleaned&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;fingerprints&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;map&lt;/span&gt;&lt;span class="p"&gt;((&lt;/span&gt;&lt;span class="nx"&gt;f&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="nx"&gt;f&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;trim&lt;/span&gt;&lt;span class="p"&gt;().&lt;/span&gt;&lt;span class="nf"&gt;replace&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="sr"&gt;/^SHA256&lt;/span&gt;&lt;span class="se"&gt;\s&lt;/span&gt;&lt;span class="sr"&gt;*/i&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="dl"&gt;''&lt;/span&gt;&lt;span class="p"&gt;).&lt;/span&gt;&lt;span class="nf"&gt;toUpperCase&lt;/span&gt;&lt;span class="p"&gt;());&lt;/span&gt;

&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;invalid&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;cleaned&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;filter&lt;/span&gt;&lt;span class="p"&gt;((&lt;/span&gt;&lt;span class="nx"&gt;f&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="sr"&gt;/^&lt;/span&gt;&lt;span class="se"&gt;([&lt;/span&gt;&lt;span class="sr"&gt;0-9A-F&lt;/span&gt;&lt;span class="se"&gt;]{2}&lt;/span&gt;&lt;span class="sr"&gt;:&lt;/span&gt;&lt;span class="se"&gt;){31}[&lt;/span&gt;&lt;span class="sr"&gt;0-9A-F&lt;/span&gt;&lt;span class="se"&gt;]{2}&lt;/span&gt;&lt;span class="sr"&gt;$/&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;test&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;f&lt;/span&gt;&lt;span class="p"&gt;));&lt;/span&gt;
&lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;invalid&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;length&lt;/span&gt; &lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nx"&gt;console&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;error&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;These do not look like SHA-256 fingerprints (expected 32 uppercase hex octets):&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="k"&gt;for &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;f&lt;/span&gt; &lt;span class="k"&gt;of&lt;/span&gt; &lt;span class="nx"&gt;invalid&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="nx"&gt;console&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;error&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;  &lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt; &lt;span class="o"&gt;+&lt;/span&gt; &lt;span class="nx"&gt;f&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="nx"&gt;process&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;exit&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The script accepts more than one fingerprint, and &lt;code&gt;replace(/^SHA256\s*/i, '')&lt;/code&gt; handles the &lt;code&gt;SHA256=...&lt;/code&gt; prefix some tools emit. Normalising at the point of writing, and failing loudly on a fingerprint that does not match the expected shape, turns a confusing validator error into a build-time message that says exactly what is wrong.&lt;/p&gt;

&lt;h2&gt;
  
  
  Play App Signing: the fingerprint that matters is not the one you signed with
&lt;/h2&gt;

&lt;p&gt;This is the part that costs people a release. You sign your upload bundle with your own upload key; Google Play then re-signs the app with its own Play App Signing key before delivering it. The device validates the certificate of the APK it actually installed — the Play app-signing certificate, not yours.&lt;/p&gt;

&lt;p&gt;So publishing only your upload-key fingerprint means the domain proves it owns a key the installed app does not use. The link opens in a Custom Tab: the app launches, the site loads, and the whole thing looks like a slightly broken browser rather than an app.&lt;/p&gt;

&lt;p&gt;The fix is to publish both fingerprints. The upload key's SHA-256 is what you already have locally; the Play app-signing key's SHA-256 lives in the Play Console under Test and release → Testing → App integrity → App signing key → SHA-256, and only exists after your first upload is processed.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;node scripts/make-assetlinks.mjs com.anyfreebook.app &amp;lt;upload-fp&amp;gt; &amp;lt;play-signing-fp&amp;gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Then verify, rather than guessing. The Digital Asset Links API will tell you whether the domain and the app actually match:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;https://digitalassetlinks.googleapis.com/v1/statements:list?source.web.site=https%3A%2F%2Fanyfreebook.com
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The site parameter is enough — the response lists every app the domain is associated with. (Adding an &lt;code&gt;source.android.app_id&lt;/code&gt; parameter to narrow it returns &lt;code&gt;400 Unknown name "source.android.app_id"&lt;/code&gt;, so leave it off.)&lt;/p&gt;

&lt;p&gt;A response containing a statement for &lt;code&gt;com.anyfreebook.app&lt;/code&gt; and no error means the handshake holds. Getting the JSON to parse is not enough — that only proves the file is syntactically valid. The &lt;code&gt;statements:list&lt;/code&gt; call proves the pairing.&lt;/p&gt;

&lt;p&gt;There is one more switch in the Play Console: Release → Setup → App integrity → Digital Asset Links verification. Until it is on, the verification is advisory.&lt;/p&gt;

&lt;h2&gt;
  
  
  The service worker is the same in both installs
&lt;/h2&gt;

&lt;p&gt;The TWA does not have its own offline story. It loads your site, and your site's service worker does the work — the same &lt;code&gt;public/sw.js&lt;/code&gt; that serves the PWA install.&lt;/p&gt;

&lt;p&gt;That worker precaches a small set of shell assets, serves pages network-first with the cached copy as fallback, serves hashed static assets cache-first, and falls back to &lt;code&gt;/offline.html&lt;/code&gt; when the network is gone:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// public/sw.js&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;CACHE_NAME&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;anyfreebook-v3&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;OFFLINE_FALLBACK&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;/offline.html&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;PRECACHE&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;/&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;OFFLINE_FALLBACK&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;/manifest.json&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;/favicon.ico&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="cm"&gt;/* ... */&lt;/span&gt;&lt;span class="p"&gt;];&lt;/span&gt;

&lt;span class="nb"&gt;self&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;addEventListener&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;install&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;event&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nx"&gt;event&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;waitUntil&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
    &lt;span class="nx"&gt;caches&lt;/span&gt;
      &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;open&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;CACHE_NAME&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
      &lt;span class="c1"&gt;// allSettled: one unreachable file must not abort the whole install.&lt;/span&gt;
      &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;then&lt;/span&gt;&lt;span class="p"&gt;((&lt;/span&gt;&lt;span class="nx"&gt;cache&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="nb"&gt;Promise&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;allSettled&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;PRECACHE&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;map&lt;/span&gt;&lt;span class="p"&gt;((&lt;/span&gt;&lt;span class="nx"&gt;url&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="nx"&gt;cache&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;add&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;url&lt;/span&gt;&lt;span class="p"&gt;))))&lt;/span&gt;
      &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;then&lt;/span&gt;&lt;span class="p"&gt;(()&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="nb"&gt;self&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;skipWaiting&lt;/span&gt;&lt;span class="p"&gt;())&lt;/span&gt;
  &lt;span class="p"&gt;);&lt;/span&gt;
&lt;span class="p"&gt;});&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Two details there are about living in an app shell rather than a browser tab. The worker returns error statuses untouched, so a genuine 404 stays a genuine 404 rather than being masked by a cached shell. And when an asset is unreachable offline, it returns a 1×1 transparent PNG with a 200 status instead of a failed request — a failed subresource inside a TWA looks like a broken app in a way it never does in a tab.&lt;/p&gt;

&lt;h2&gt;
  
  
  The Bubblewrap manifest, in essentials
&lt;/h2&gt;

&lt;p&gt;The whole Android project is generated from one JSON file. The parts worth understanding:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight json"&gt;&lt;code&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="nl"&gt;"packageId"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"com.anyfreebook.app"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="nl"&gt;"host"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"anyfreebook.com"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="nl"&gt;"name"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"ANYFREEBOOK"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="nl"&gt;"display"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"standalone"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="nl"&gt;"startUrl"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"/"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="nl"&gt;"fullScopeUrl"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"https://anyfreebook.com/"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="nl"&gt;"minSdkVersion"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="mi"&gt;24&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="nl"&gt;"appVersion"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"1"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="nl"&gt;"appVersionCode"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="nl"&gt;"fingerprints"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="w"&gt;
    &lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="w"&gt;
      &lt;/span&gt;&lt;span class="nl"&gt;"name"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"upload"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
      &lt;/span&gt;&lt;span class="nl"&gt;"value"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"A6:76:B1:D9:64:9E:4F:5A:34:4D:EB:06:9B:31:64:00:15:F4:6E:76:79:96:C6:FA:13:56:BE:FA:D6:F7:90:C2"&lt;/span&gt;&lt;span class="w"&gt;
    &lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="w"&gt;
&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="w"&gt;
&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;packageId&lt;/code&gt; and &lt;code&gt;host&lt;/code&gt; are the identity of the app and the domain it claims. &lt;code&gt;fullScopeUrl&lt;/code&gt; is what makes it a full-scope TWA rather than a partial one — every route under that origin stays inside the shell. &lt;code&gt;minSdkVersion&lt;/code&gt; 24 and &lt;code&gt;targetSdk&lt;/code&gt; 36 set the platform floor and the API level the app targets. Changing anything here means re-running &lt;code&gt;npx bubblewrap update --manifest twa-manifest.json&lt;/code&gt;, which regenerates the project and bumps &lt;code&gt;appVersionCode&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;Note that the &lt;code&gt;fingerprints&lt;/code&gt; array here carries the upload key. That is correct for Bubblewrap's signing step, and it is &lt;em&gt;not&lt;/em&gt; sufficient for Digital Asset Links — the file the domain serves needs the Play app-signing fingerprint too.&lt;/p&gt;

&lt;h2&gt;
  
  
  The practical takeaway
&lt;/h2&gt;

&lt;p&gt;A TWA is not an excuse to skip the PWA, because the PWA is what the TWA loads. The manifest, the service worker, the offline page and the icons all have to be right before the app shell has anything to show. If the service worker's cache-first rules are wrong, the wrong version of a page is what the app shows, offline and online alike.&lt;/p&gt;

&lt;p&gt;Get the order right and the work is small: build the bundle, upload it, read the Play app-signing fingerprint out of the Play Console, publish it alongside the upload fingerprint in uppercase, verify with the &lt;code&gt;statements:list&lt;/code&gt; endpoint, and turn on Digital Asset Links verification. Then the Play icon opens your website instead of a browser tab, and the app you maintain is still the one you already ship.&lt;/p&gt;

</description>
      <category>android</category>
      <category>pwa</category>
      <category>twa</category>
      <category>nextjs</category>
    </item>
    <item>
      <title>Your "free" book API might not be free</title>
      <dc:creator>Michael Banigo</dc:creator>
      <pubDate>Tue, 27 Oct 2026 00:37:34 +0000</pubDate>
      <link>https://dev.to/michael_banigo_6bea76d866/your-free-book-api-might-not-be-free-2jnb</link>
      <guid>https://dev.to/michael_banigo_6bea76d866/your-free-book-api-might-not-be-free-2jnb</guid>
      <description>&lt;p&gt;A book-search API hands you a URL, and usually the word "free" printed next to it. That URL is a black box. Behind it there can be a public-domain full text, a borrow-only lending copy, or a catalogue record for a book still in copyright. If your client calls it free, it is making a claim about the law it cannot support — on your users' behalf.&lt;/p&gt;

&lt;h2&gt;
  
  
  Three tiers, and what each one actually means
&lt;/h2&gt;

&lt;p&gt;ANYFREEBOOK returns a tier with every result. The three tiers are deliberately narrow:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;&lt;code&gt;download&lt;/code&gt;&lt;/strong&gt; — a free, legally readable copy of this exact title, resolved from the source's own metadata. This is the only tier that permits the words "free download" anywhere in the product.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;&lt;code&gt;borrow&lt;/code&gt;&lt;/strong&gt; — a real Internet Archive copy that the Archive's own metadata says is loan-only. Controlled Digital Lending: a free Internet Archive account plus a loan. There is no file to fetch.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;&lt;code&gt;unverified&lt;/code&gt;&lt;/strong&gt; — a catalogue record, or a search-results page for this title. We could not confirm a free, legally readable copy of &lt;em&gt;this exact title&lt;/em&gt;.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;The tier is not a guess or a heuristic. It is resolved from the source's own metadata.&lt;/p&gt;

&lt;h2&gt;
  
  
  The evidence has to come from the source
&lt;/h2&gt;

&lt;p&gt;For the Internet Archive, the item's own record answers both questions at once: is this copy open, and which files can be downloaded. &lt;code&gt;src/lib/api/publicRecords.ts&lt;/code&gt; reads the lending fields directly:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;restricted&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt;
  &lt;span class="nx"&gt;metadata&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;access-restricted-item&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;true&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt; &lt;span class="o"&gt;||&lt;/span&gt;
  &lt;span class="o"&gt;!!&lt;/span&gt;&lt;span class="nx"&gt;metadata&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;lending_identifier&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt; &lt;span class="o"&gt;||&lt;/span&gt;
  &lt;span class="o"&gt;!!&lt;/span&gt;&lt;span class="nx"&gt;metadata&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;lendinginfo&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;];&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;If the metadata call fails, the resolver falls back to &lt;code&gt;unverified&lt;/code&gt; rather than assuming the best. A record we could not read is never promoted to &lt;code&gt;download&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;For Project Gutenberg, the title and the author both have to match. &lt;code&gt;src/lib/api/resolveSource.ts&lt;/code&gt; checks the author, because a title alone is not enough — a book by one Austen must never resolve to a different book that shares the surname:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;authorMatches&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;author&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kr"&gt;string&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;authors&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nl"&gt;name&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kr"&gt;string&lt;/span&gt; &lt;span class="p"&gt;}[]&lt;/span&gt; &lt;span class="o"&gt;|&lt;/span&gt; &lt;span class="kc"&gt;undefined&lt;/span&gt;&lt;span class="p"&gt;):&lt;/span&gt; &lt;span class="nx"&gt;boolean&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="nx"&gt;authors&lt;/span&gt; &lt;span class="o"&gt;||&lt;/span&gt; &lt;span class="nx"&gt;authors&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;length&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="kc"&gt;false&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;tokens&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;author&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;toLowerCase&lt;/span&gt;&lt;span class="p"&gt;().&lt;/span&gt;&lt;span class="nf"&gt;split&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="sr"&gt;/&lt;/span&gt;&lt;span class="se"&gt;[\s&lt;/span&gt;&lt;span class="sr"&gt;,&amp;amp;&lt;/span&gt;&lt;span class="se"&gt;]&lt;/span&gt;&lt;span class="sr"&gt;+/&lt;/span&gt;&lt;span class="p"&gt;).&lt;/span&gt;&lt;span class="nf"&gt;filter&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;t&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="nx"&gt;t&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;length&lt;/span&gt; &lt;span class="o"&gt;&amp;gt;=&lt;/span&gt; &lt;span class="mi"&gt;3&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;combined&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;authors&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;map&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;a&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="nx"&gt;a&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;name&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;toLowerCase&lt;/span&gt;&lt;span class="p"&gt;()).&lt;/span&gt;&lt;span class="nf"&gt;join&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt; | &lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nx"&gt;tokens&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;some&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;t&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="nx"&gt;combined&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;includes&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;t&lt;/span&gt;&lt;span class="p"&gt;));&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Only when a match survives both checks does the resolver claim a tier:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;match&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;data&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;results&lt;/span&gt;&lt;span class="p"&gt;?.&lt;/span&gt;&lt;span class="nf"&gt;find&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
  &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;r&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nl"&gt;title&lt;/span&gt;&lt;span class="p"&gt;?:&lt;/span&gt; &lt;span class="kr"&gt;string&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="nl"&gt;authors&lt;/span&gt;&lt;span class="p"&gt;?:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;name&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kr"&gt;string&lt;/span&gt; &lt;span class="p"&gt;}[]&lt;/span&gt; &lt;span class="p"&gt;})&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt;
    &lt;span class="nf"&gt;titleMatches&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;title&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;r&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;title&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt; &lt;span class="nf"&gt;authorMatches&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;author&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;r&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;authors&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="p"&gt;);&lt;/span&gt;
&lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;match&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;readUrl&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt;
    &lt;span class="nx"&gt;match&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;formats&lt;/span&gt;&lt;span class="p"&gt;?.[&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;text/html&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt; &lt;span class="o"&gt;||&lt;/span&gt;
    &lt;span class="nx"&gt;match&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;formats&lt;/span&gt;&lt;span class="p"&gt;?.[&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;application/epub+zip&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt; &lt;span class="o"&gt;||&lt;/span&gt;
    &lt;span class="s2"&gt;`https://www.gutenberg.org/ebooks/&lt;/span&gt;&lt;span class="p"&gt;${&lt;/span&gt;&lt;span class="nx"&gt;match&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;id&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="s2"&gt;`&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="na"&gt;sourceUrl&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;`https://www.gutenberg.org/ebooks/&lt;/span&gt;&lt;span class="p"&gt;${&lt;/span&gt;&lt;span class="nx"&gt;match&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;id&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="s2"&gt;`&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="na"&gt;sourceType&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;gutenberg&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="na"&gt;downloadLinks&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[{&lt;/span&gt; &lt;span class="na"&gt;label&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;Read on Project Gutenberg&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="na"&gt;url&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;readUrl&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="na"&gt;source&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;Project Gutenberg&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt; &lt;span class="p"&gt;}],&lt;/span&gt;
    &lt;span class="na"&gt;tier&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;download&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="p"&gt;};&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;And the rule that matters most: &lt;strong&gt;a catalogue record is not a copy.&lt;/strong&gt; Open Library holding an entry for a book tells you the book exists and where it can be bought. It says nothing about whether the text is free to read today. Treating "we found the title" as "the title is free" is the single most common bug in this category of API, and the one that ends up in front of a rights holder.&lt;/p&gt;

&lt;p&gt;The title has to be checked too, and this is a bug we hit ourselves. Gutendex and Open Library both rank by relevance, so taking the top hit returns whatever scored highest. Our resolver asked Open Library for one result and checked the author; a request for &lt;em&gt;Fairy Circles&lt;/em&gt; by William James Hudson came back with a downloadable copy of &lt;em&gt;Alice's Adventures in Wonderland&lt;/em&gt;, labelled &lt;code&gt;tier: download&lt;/code&gt;. The fix is to fetch several candidates, ask for their title and author fields, and accept the first that is actually the title requested:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;doc&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;docs&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;find&lt;/span&gt;&lt;span class="p"&gt;((&lt;/span&gt;&lt;span class="nx"&gt;d&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="nf"&gt;titleMatches&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;title&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;d&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;title&lt;/span&gt;&lt;span class="p"&gt;))&lt;/span&gt; &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="kc"&gt;false&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="nx"&gt;author&lt;/span&gt; &lt;span class="o"&gt;||&lt;/span&gt; &lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="nx"&gt;d&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;author_name&lt;/span&gt; &lt;span class="o"&gt;||&lt;/span&gt; &lt;span class="nx"&gt;d&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;author_name&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;length&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nf"&gt;authorMatches&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;author&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;d&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;author_name&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;map&lt;/span&gt;&lt;span class="p"&gt;((&lt;/span&gt;&lt;span class="nx"&gt;name&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;({&lt;/span&gt; &lt;span class="nx"&gt;name&lt;/span&gt; &lt;span class="p"&gt;})));&lt;/span&gt;
&lt;span class="p"&gt;});&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;titleMatches&lt;/code&gt; allows a subtitle ("Fairy Circles: Tales and Legends of …") but not a different book that merely starts with the same words. When nothing matches, the resolver returns &lt;code&gt;unverified&lt;/code&gt; with links to real search pages — the honest answer: we cannot confirm a free copy of &lt;em&gt;that&lt;/em&gt; book.&lt;/p&gt;

&lt;h2&gt;
  
  
  Borrow is not download
&lt;/h2&gt;

&lt;p&gt;Controlled Digital Lending is easy to misdescribe. The Internet Archive holds a real copy of the book. The reader gets a real copy of the book. But it is only accessible through the Archive's lending interface: you need a free account, you need to take out a loan, and the loan is time-limited and renewed through a queue.&lt;/p&gt;

&lt;p&gt;None of that is a file. A link to a borrow-only item is not something a downloader can fetch; it is a page that requires an account before it gives you anything. If your API says "free download" and links to a borrow-only item, you have shipped a button that leads to a login wall and called it a download.&lt;/p&gt;

&lt;p&gt;That is why the tiers are separate values rather than a boolean &lt;code&gt;isFree&lt;/code&gt;. &lt;code&gt;borrow&lt;/code&gt; is a real answer — this copy is free to read, under conditions — but it differs from "you may fetch this file now".&lt;/p&gt;

&lt;h2&gt;
  
  
  The rule: never claim a download you cannot point at
&lt;/h2&gt;

&lt;p&gt;Our resolver never returns &lt;code&gt;download&lt;/code&gt; for a search-results page. Where the source exposes a file, the API's &lt;code&gt;files[]&lt;/code&gt; array carries it. This is a real response, captured from the live API:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight json"&gt;&lt;code&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="nl"&gt;"title"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"Fairy Circles"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="nl"&gt;"author"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"Villamaria"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="nl"&gt;"tier"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"download"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="nl"&gt;"tierReason"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"Open-access copy on the Internet Archive."&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="nl"&gt;"sourceType"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"archive"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="nl"&gt;"sourceUrl"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"https://archive.org/details/fairycirclestale00villiala"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="nl"&gt;"license"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"Public domain"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="nl"&gt;"files"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="w"&gt;
    &lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nl"&gt;"format"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"epub"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nl"&gt;"url"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"https://archive.org/download/fairycirclestale00villiala/fairycirclestale00villiala.epub"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nl"&gt;"bytes"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="mi"&gt;15512987&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nl"&gt;"label"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"fairycirclestale00villiala.epub"&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="p"&gt;},&lt;/span&gt;&lt;span class="w"&gt;
    &lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nl"&gt;"format"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"pdf"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nl"&gt;"url"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"https://archive.org/download/fairycirclestale00villiala/fairycirclestale00villiala.pdf"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nl"&gt;"bytes"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="mi"&gt;13373257&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nl"&gt;"label"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"fairycirclestale00villiala.pdf"&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="p"&gt;},&lt;/span&gt;&lt;span class="w"&gt;
    &lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nl"&gt;"format"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"txt"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nl"&gt;"url"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"https://archive.org/download/fairycirclestale00villiala/fairycirclestale00villiala_djvu.txt"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nl"&gt;"bytes"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="mi"&gt;514307&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nl"&gt;"label"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"fairycirclestale00villiala_djvu.txt"&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="p"&gt;},&lt;/span&gt;&lt;span class="w"&gt;
    &lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nl"&gt;"format"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"html"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nl"&gt;"url"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"https://archive.org/download/fairycirclestale00villiala/fairycirclestale00villiala_hocr.html"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nl"&gt;"bytes"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="mi"&gt;11537829&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nl"&gt;"label"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"fairycirclestale00villiala_hocr.html"&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="p"&gt;],&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="nl"&gt;"links"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="w"&gt;
    &lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nl"&gt;"label"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"Read on Internet Archive"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nl"&gt;"url"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"https://archive.org/details/fairycirclestale00villiala"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nl"&gt;"source"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"Internet Archive"&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="p"&gt;},&lt;/span&gt;&lt;span class="w"&gt;
    &lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nl"&gt;"label"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"View on Open Library"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nl"&gt;"url"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"https://openlibrary.org/works/OL7903107W"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nl"&gt;"source"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"Open Library"&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="p"&gt;],&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="nl"&gt;"meta"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nl"&gt;"apiVersion"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"v1"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nl"&gt;"generatedAt"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"2026-10-24T12:53:48.857Z"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nl"&gt;"caller"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"anonymous"&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="w"&gt;
&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="w"&gt;
&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;For Project Gutenberg the same shape comes back with Gutenberg's canonical URLs instead — &lt;code&gt;/ebooks/1342.epub3.images&lt;/code&gt;, &lt;code&gt;.txt.utf-8&lt;/code&gt; and &lt;code&gt;.html.images&lt;/code&gt; — because those three exist for every ebook. Gutenberg serves no PDF for every title, so none is listed unless the source reported one.&lt;/p&gt;

&lt;p&gt;There is one case where &lt;code&gt;download&lt;/code&gt; comes back with an empty &lt;code&gt;files[]&lt;/code&gt;: the copy is genuinely free to read, but the source exposes no file you can fetch in one request. A DOAJ article or a PubMed Central paper is free full text at the publisher's page; a LibriVox recording is free as chapter files; an Internet Archive item whose only derivatives are DRM-encrypted has no fetchable file. Those records carry &lt;code&gt;links[]&lt;/code&gt; instead.&lt;/p&gt;

&lt;p&gt;So a machine client should check two things. &lt;code&gt;tier === 'download'&lt;/code&gt; says the copy is free without payment or an account. &lt;code&gt;files.length &amp;gt; 0&lt;/code&gt; says you can fetch it right now. A downloader that only checks the tier sometimes finds nothing to download; one that only checks &lt;code&gt;files[]&lt;/code&gt; misses the cases where the tier matters.&lt;/p&gt;

&lt;p&gt;For &lt;code&gt;borrow&lt;/code&gt; and &lt;code&gt;unverified&lt;/code&gt;, &lt;code&gt;files[]&lt;/code&gt; is empty and &lt;code&gt;links[]&lt;/code&gt; points at the real source. That is not an oversight in the payload — it is the payload making the distinction impossible to miss.&lt;/p&gt;

&lt;p&gt;When &lt;code&gt;/resolve&lt;/code&gt; cannot find a copy it can confirm, the tier is &lt;code&gt;unverified&lt;/code&gt; and the links are search URLs for the exact title and author. We would rather send a reader to a real search page than pretend it is a download.&lt;/p&gt;

&lt;p&gt;One more wrinkle: the file list contains things that look like documents and are not. Labels are matched exactly against a small allowlist of real formats, and the file name is checked too, because "OCR Search Text" is a gzipped search index and "Single Page Original JP2 Tar" is a several-hundred-megabyte dump of page images. Matching labels loosely is how a downloader ends up fetching a 700 MB tarball thinking it fetched a book.&lt;/p&gt;

&lt;h2&gt;
  
  
  What a client does with the tier
&lt;/h2&gt;

&lt;p&gt;Here is the client-side consequence, the part most implementations skip. A consumer that downloads each book should check the tier and refuse out loud:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// An example client consuming GET /api/v1/resolve&lt;/span&gt;
&lt;span class="kd"&gt;type&lt;/span&gt; &lt;span class="nx"&gt;Tier&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;download&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt; &lt;span class="o"&gt;|&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;borrow&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt; &lt;span class="o"&gt;|&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;unverified&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="kr"&gt;interface&lt;/span&gt; &lt;span class="nx"&gt;Resolved&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nl"&gt;tier&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;Tier&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="nl"&gt;tierReason&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kr"&gt;string&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="nl"&gt;files&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;format&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kr"&gt;string&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="nl"&gt;url&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kr"&gt;string&lt;/span&gt; &lt;span class="p"&gt;}[];&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;download&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;title&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kr"&gt;string&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;res&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;fetch&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
    &lt;span class="s2"&gt;`https://anyfreebook.com/api/v1/resolve?title=&lt;/span&gt;&lt;span class="p"&gt;${&lt;/span&gt;&lt;span class="nf"&gt;encodeURIComponent&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;title&lt;/span&gt;&lt;span class="p"&gt;)}&lt;/span&gt;&lt;span class="s2"&gt;`&lt;/span&gt;
  &lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;body&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nx"&gt;res&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;json&lt;/span&gt;&lt;span class="p"&gt;())&lt;/span&gt; &lt;span class="kd"&gt;as &lt;/span&gt;&lt;span class="nx"&gt;Resolved&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

  &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;body&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;tier&lt;/span&gt; &lt;span class="o"&gt;!==&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;download&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt; &lt;span class="o"&gt;||&lt;/span&gt; &lt;span class="nx"&gt;body&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;files&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;length&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="c1"&gt;// Refuse out loud. Skipping the title silently would look, to the user&lt;/span&gt;
    &lt;span class="c1"&gt;// watching the output, exactly like the download succeeded.&lt;/span&gt;
    &lt;span class="k"&gt;throw&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;Error&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;`Cannot download "&lt;/span&gt;&lt;span class="p"&gt;${&lt;/span&gt;&lt;span class="nx"&gt;title&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="s2"&gt;" (&lt;/span&gt;&lt;span class="p"&gt;${&lt;/span&gt;&lt;span class="nx"&gt;body&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;tier&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="s2"&gt;): &lt;/span&gt;&lt;span class="p"&gt;${&lt;/span&gt;&lt;span class="nx"&gt;body&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;tierReason&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="s2"&gt;`&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;

  &lt;span class="k"&gt;for &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;file&lt;/span&gt; &lt;span class="k"&gt;of&lt;/span&gt; &lt;span class="nx"&gt;body&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;files&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="c1"&gt;// fetch file.url&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The difference between throwing and skipping is the whole point. A silent skip produces a run that looks successful and quietly contains fewer books than it should. A refusal with the tier attached tells the user something true: this title is borrow-only, or it is a catalogue record.&lt;/p&gt;

&lt;h2&gt;
  
  
  The tier is the single source of truth
&lt;/h2&gt;

&lt;p&gt;Inside our own codebase the discipline is enforced by having exactly one decision point. &lt;code&gt;src/lib/api/resolveSource.ts&lt;/code&gt; exports the &lt;code&gt;SourceTier&lt;/code&gt; type, and the book page's badge, its &lt;code&gt;&amp;lt;title&amp;gt;&lt;/code&gt;, its meta description and its schema.org offer all read from that one value. The green "100% legal, open-access" badge appears only when the tier is &lt;code&gt;download&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;When the tier is anything other than &lt;code&gt;download&lt;/code&gt;, the page does something better than apologising. It offers a genuinely free alternative — a real open resource for that subject, from OpenStax, MIT OpenCourseWare, Project Gutenberg and Cornell LII, with per-title matches taking priority over per-category ones.&lt;/p&gt;

&lt;h2&gt;
  
  
  If your API returns "free" URLs, you are making a legal claim
&lt;/h2&gt;

&lt;p&gt;That is the broader point. A "free" URL in an API response is not a convenience field. It is a representation to your users, and indirectly to their employers and their schools, that the thing behind the link costs nothing and can be taken away.&lt;/p&gt;

&lt;p&gt;Resolve it properly or don't claim it. The tier is the mechanism: three values, each backed by the source's own metadata, each with a &lt;code&gt;tierReason&lt;/code&gt; that a human can read and argue with.&lt;/p&gt;

&lt;p&gt;The failure this avoids is concrete. It is shipping a "free download" button that leads to a login wall, which is embarrassing. It is also shipping that same button where a downstream site has filled the gap with a pirated copy, which is not. Between the two, the boring tier system is the cheapest insurance there is.&lt;/p&gt;

</description>
      <category>api</category>
      <category>legal</category>
      <category>licensing</category>
      <category>typescript</category>
    </item>
    <item>
      <title>Fanning out a search across twelve APIs, and telling the user when one of them fails</title>
      <dc:creator>Michael Banigo</dc:creator>
      <pubDate>Tue, 27 Oct 2026 00:33:32 +0000</pubDate>
      <link>https://dev.to/michael_banigo_6bea76d866/fanning-out-a-search-across-twelve-apis-and-telling-the-user-when-one-of-them-fails-2a25</link>
      <guid>https://dev.to/michael_banigo_6bea76d866/fanning-out-a-search-across-twelve-apis-and-telling-the-user-when-one-of-them-fails-2a25</guid>
      <description>&lt;p&gt;ANYFREEBOOK searches Project Gutenberg, Open Library, the Internet Archive, Google Books, PubMed Central, DOAJ, LibriVox, OpenAlex, Wikisource, Europeana, Zenodo and the Open Textbook Library at the same time. (The public API fans out to all twelve. The website's own search page leaves LibriVox out, because an audiobook is usually not what someone typing a book title is after — that source has its own page.) The parallelism is the easy part. The part that took real thought was deciding what to do when one of the twelve does not answer — because the default behaviour of most multi-source search code is to quietly return a shorter list, and a shorter list is indistinguishable from "that is everything there is".&lt;/p&gt;

&lt;h2&gt;
  
  
  There is no search index
&lt;/h2&gt;

&lt;p&gt;Start with the constraint, because it dictates everything else. ANYFREEBOOK does not maintain a search index. We keep a curated catalogue of 258 books across 241 categories in &lt;code&gt;src/lib/data.ts&lt;/code&gt;, and that catalogue powers the category pages and the per-title detail pages. But a search query is not answered out of that catalogue. It is fanned out, live, to twelve separate upstream APIs — each with its own index, its own rate limits, its own idea of what a result is, and its own bad days.&lt;/p&gt;

&lt;p&gt;There is no replica of those indexes in our database and we do not crawl and re-store. Every search is a fan-out of live upstream calls, and the answer is the union of whatever they returned.&lt;/p&gt;

&lt;p&gt;That fan-out is bigger than it looks. Twelve sources, but nineteen outbound HTTP requests, because three of them need more than one call to answer: Wikisource is a separate wiki per language and we ask six of them, PubMed Central is a search followed by a summary of the ids it returns, and the Open Textbook Library serves ten books per page so a page of twenty is two requests. Here is the measured breakdown of one search, counting the requests that actually leave the server:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;   6  en.wikisource.org, zh, ja, ar, he, fr   (six Wikisource editions)
   2  eutils.ncbi.nlm.nih.gov                  (esearch, then esummary)
   2  open.umn.edu                             (Open Textbook Library, two pages)
   1  openlibrary.org
   1  gutendex.com
   1  archive.org
   1  doaj.org
   1  api.openalex.org
   1  api.europeana.eu
   1  zenodo.org
   1  librivox.org
   1  www.googleapis.com                       (Google Books)
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;That number is worth knowing before the rest of this, because it is the reason the rate limiter in this system is not optional. Nineteen requests to twelve different services, on somebody else's infrastructure, for one user query.&lt;/p&gt;

&lt;p&gt;The design is cheap to start and awkward to operate, because the failure modes of twelve separate services are now our failure modes.&lt;/p&gt;

&lt;h2&gt;
  
  
  One source failing must not cost you the other six
&lt;/h2&gt;

&lt;p&gt;The obvious version looks like this:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="nx"&gt;gutenberg&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;openLibrary&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;googleBooks&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;archive&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;pubmed&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;doaj&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;librivox&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;openAlex&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt;
  &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nb"&gt;Promise&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;all&lt;/span&gt;&lt;span class="p"&gt;([&lt;/span&gt;
    &lt;span class="nf"&gt;searchGutenberg&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;query&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;page&lt;/span&gt;&lt;span class="p"&gt;),&lt;/span&gt;
    &lt;span class="nf"&gt;searchOpenLibrary&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;query&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;20&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;page&lt;/span&gt;&lt;span class="p"&gt;),&lt;/span&gt;
    &lt;span class="c1"&gt;// ...and so on&lt;/span&gt;
  &lt;span class="p"&gt;]);&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;Promise.all&lt;/code&gt; short-circuits. The first promise that rejects rejects the whole thing, and you throw away eleven responses that already arrived, or would have arrived had the fan-out waited. On a good day nobody notices; when one upstream times out, the search errors out for a query eleven sources could answer perfectly well.&lt;/p&gt;

&lt;p&gt;&lt;code&gt;Promise.allSettled&lt;/code&gt; waits for every promise to reach a terminal state and hands you each outcome separately. One rejected shelf costs you that shelf, never the page.&lt;/p&gt;

&lt;h2&gt;
  
  
  How the fan-out actually looks
&lt;/h2&gt;

&lt;p&gt;In &lt;code&gt;src/lib/api/searchAll.ts&lt;/code&gt; each source gets its own block, and each block catches its own error:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="kr"&gt;interface&lt;/span&gt; &lt;span class="nx"&gt;SearchOutcome&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nl"&gt;books&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;Book&lt;/span&gt;&lt;span class="p"&gt;[];&lt;/span&gt;
  &lt;span class="nl"&gt;total&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kr"&gt;number&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="nl"&gt;sources&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nb"&gt;Record&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="kr"&gt;string&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="kr"&gt;number&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="nl"&gt;failedSources&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kr"&gt;string&lt;/span&gt;&lt;span class="p"&gt;[];&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;searchAllSources&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
  &lt;span class="nx"&gt;query&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kr"&gt;string&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nx"&gt;page&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kr"&gt;number&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nx"&gt;source&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;SearchSource&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nx"&gt;options&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nl"&gt;includeLibrivox&lt;/span&gt;&lt;span class="p"&gt;?:&lt;/span&gt; &lt;span class="nx"&gt;boolean&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;{}&lt;/span&gt;
&lt;span class="p"&gt;):&lt;/span&gt; &lt;span class="nb"&gt;Promise&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nx"&gt;SearchOutcome&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="na"&gt;results&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;SearchOutcome&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;books&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[],&lt;/span&gt; &lt;span class="na"&gt;total&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="na"&gt;sources&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{},&lt;/span&gt; &lt;span class="na"&gt;failedSources&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[]&lt;/span&gt; &lt;span class="p"&gt;};&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="na"&gt;fetches&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nb"&gt;Promise&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="k"&gt;void&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;&lt;span class="p"&gt;[]&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;[];&lt;/span&gt;

  &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;source&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;all&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt; &lt;span class="o"&gt;||&lt;/span&gt; &lt;span class="nx"&gt;source&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;openlibrary&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="nx"&gt;fetches&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;push&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
      &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;async &lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="k"&gt;try&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
          &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;ol&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;searchOpenLibrary&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;query&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;20&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;page&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
          &lt;span class="nx"&gt;results&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;books&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;push&lt;/span&gt;&lt;span class="p"&gt;(...&lt;/span&gt;&lt;span class="nx"&gt;ol&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;books&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
          &lt;span class="nx"&gt;results&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;sources&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;Open Library&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;ol&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;total&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
          &lt;span class="nx"&gt;results&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;total&lt;/span&gt; &lt;span class="o"&gt;+=&lt;/span&gt; &lt;span class="nx"&gt;ol&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;total&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
        &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;catch&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
          &lt;span class="nx"&gt;results&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;failedSources&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;push&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;Open Library&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
        &lt;span class="p"&gt;}&lt;/span&gt;
      &lt;span class="p"&gt;})()&lt;/span&gt;
    &lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;

  &lt;span class="c1"&gt;// ...the same block for Gutenberg, Google Books, the Internet Archive,&lt;/span&gt;
  &lt;span class="c1"&gt;// PubMed Central, DOAJ and LibriVox...&lt;/span&gt;

  &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nb"&gt;Promise&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;all&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;fetches&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nx"&gt;results&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;A note on why this uses &lt;code&gt;Promise.all&lt;/code&gt; rather than &lt;code&gt;Promise.allSettled&lt;/code&gt;: because every block swallows its own error, none of these promises ever rejects. &lt;code&gt;Promise.all&lt;/code&gt; here is safe by construction — it is &lt;code&gt;allSettled&lt;/code&gt; semantics, with the outcome recorded in &lt;code&gt;failedSources&lt;/code&gt; instead of in a result object.&lt;/p&gt;

&lt;p&gt;Where the shape of the data allows it, we write the intent more directly. The category pages do exactly that:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// src/app/category/[slug]/page.tsx&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="nx"&gt;ol&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;archive&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;gb&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nb"&gt;Promise&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;allSettled&lt;/span&gt;&lt;span class="p"&gt;([&lt;/span&gt;
  &lt;span class="nf"&gt;searchOpenLibrary&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;query&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;30&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;),&lt;/span&gt;
  &lt;span class="nf"&gt;searchArchive&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;query&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;24&lt;/span&gt;&lt;span class="p"&gt;),&lt;/span&gt;
  &lt;span class="nf"&gt;searchGoogleBooks&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;query&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;20&lt;/span&gt;&lt;span class="p"&gt;),&lt;/span&gt;
&lt;span class="p"&gt;]);&lt;/span&gt;

&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;olTotal&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;ol&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;status&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;fulfilled&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt; &lt;span class="p"&gt;?&lt;/span&gt; &lt;span class="nx"&gt;ol&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;value&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;total&lt;/span&gt; &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;archiveTotal&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;archive&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;status&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;fulfilled&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt; &lt;span class="p"&gt;?&lt;/span&gt; &lt;span class="nx"&gt;archive&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;value&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;total&lt;/span&gt; &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;gbTotal&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;gb&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;status&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;fulfilled&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt; &lt;span class="p"&gt;?&lt;/span&gt; &lt;span class="nx"&gt;gb&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;value&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;total&lt;/span&gt; &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Both patterns are fine. What matters is that a rejected source produces a smaller list — never an exception, and never a silently truncated list presented as complete.&lt;/p&gt;

&lt;p&gt;The other half of the story is timeouts. An upstream that never responds is worse than one that errors, because it holds the request open. Every call to a third-party book API goes through one shared abort signal with a 10-second ceiling (&lt;code&gt;src/lib/api/http.ts&lt;/code&gt;), so a hung source costs that one shelf instead of the request.&lt;/p&gt;

&lt;h2&gt;
  
  
  The contract: failedSources and partial
&lt;/h2&gt;

&lt;p&gt;A failure record is only useful if it reaches the client. The public API (&lt;code&gt;https://anyfreebook.com/api/v1/search&lt;/code&gt;) returns it. Here is a real response, captured from the live API:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight json"&gt;&lt;code&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="nl"&gt;"query"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"python"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="nl"&gt;"page"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="nl"&gt;"limit"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="mi"&gt;2&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="nl"&gt;"total"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="mi"&gt;25204850&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="nl"&gt;"count"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="mi"&gt;2&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="nl"&gt;"sources"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="w"&gt;
    &lt;/span&gt;&lt;span class="nl"&gt;"ANYFREEBOOK"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="mi"&gt;3&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
    &lt;/span&gt;&lt;span class="nl"&gt;"Internet Archive"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="mi"&gt;23532873&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
    &lt;/span&gt;&lt;span class="nl"&gt;"Open Library"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="mi"&gt;6589&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
    &lt;/span&gt;&lt;span class="nl"&gt;"Google Books"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="mi"&gt;190&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
    &lt;/span&gt;&lt;span class="nl"&gt;"DOAJ"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="mi"&gt;17471&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
    &lt;/span&gt;&lt;span class="nl"&gt;"Europeana"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="mi"&gt;409&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
    &lt;/span&gt;&lt;span class="nl"&gt;"Wikisource"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
    &lt;/span&gt;&lt;span class="nl"&gt;"OpenAlex"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="mi"&gt;1253080&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
    &lt;/span&gt;&lt;span class="nl"&gt;"Zenodo"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="mi"&gt;71644&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
    &lt;/span&gt;&lt;span class="nl"&gt;"PubMed Central"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="mi"&gt;300019&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
    &lt;/span&gt;&lt;span class="nl"&gt;"Open Textbook Library"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="mi"&gt;38&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
    &lt;/span&gt;&lt;span class="nl"&gt;"Project Gutenberg"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="mi"&gt;22537&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
    &lt;/span&gt;&lt;span class="nl"&gt;"LibriVox"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="p"&gt;},&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="nl"&gt;"failedSources"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="p"&gt;[],&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="nl"&gt;"partial"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="kc"&gt;false&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="nl"&gt;"results"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"..."&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="w"&gt;
&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="w"&gt;
&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;All twelve sources answered, so &lt;code&gt;failedSources&lt;/code&gt; is empty and &lt;code&gt;partial&lt;/code&gt; is false. Two of those counts are zero — Wikisource and LibriVox — and both are real answers: LibriVox has no audiobook whose title starts with "python", and the Wikisource editions we ask have no page titled exactly "python". Zero is a legitimate answer, and it is different from not answering at all.&lt;/p&gt;

&lt;p&gt;Here is the same endpoint on a query where three sources genuinely did fail. The query is the word &lt;code&gt;AND&lt;/code&gt;, which is a Solr/Lucene operator, so it is a malformed search for the three upstreams that speak that syntax:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight json"&gt;&lt;code&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="nl"&gt;"query"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"AND"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="nl"&gt;"page"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="nl"&gt;"limit"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="mi"&gt;2&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="nl"&gt;"total"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="mi"&gt;20031433&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="nl"&gt;"count"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="mi"&gt;2&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="nl"&gt;"sources"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="w"&gt;
    &lt;/span&gt;&lt;span class="nl"&gt;"ANYFREEBOOK"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="mi"&gt;39&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
    &lt;/span&gt;&lt;span class="nl"&gt;"OpenAlex"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
    &lt;/span&gt;&lt;span class="nl"&gt;"Google Books"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="mi"&gt;101&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
    &lt;/span&gt;&lt;span class="nl"&gt;"LibriVox"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="mi"&gt;20&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
    &lt;/span&gt;&lt;span class="nl"&gt;"Europeana"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="mi"&gt;7151166&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
    &lt;/span&gt;&lt;span class="nl"&gt;"Wikisource"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
    &lt;/span&gt;&lt;span class="nl"&gt;"Zenodo"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="mi"&gt;4541111&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
    &lt;/span&gt;&lt;span class="nl"&gt;"PubMed Central"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="mi"&gt;8337033&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
    &lt;/span&gt;&lt;span class="nl"&gt;"Open Textbook Library"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="mi"&gt;2002&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
    &lt;/span&gt;&lt;span class="nl"&gt;"Project Gutenberg"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="p"&gt;},&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="nl"&gt;"failedSources"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"Internet Archive"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"DOAJ"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"Open Library"&lt;/span&gt;&lt;span class="p"&gt;],&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="nl"&gt;"partial"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="nl"&gt;"results"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"..."&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="w"&gt;
&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="w"&gt;
&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;This is the interesting case. Ten sources answered and three did not, and the response says which three. Note that &lt;code&gt;Internet Archive&lt;/code&gt; and &lt;code&gt;Open Library&lt;/code&gt; are simply absent from &lt;code&gt;sources&lt;/code&gt; — they are not present with a count of zero, because a zero would be a claim that they answered and found nothing.&lt;/p&gt;

&lt;p&gt;Without the flag the same payload would read as a confident "20,031,433 results", and a reader would have no way to know that a slice of the answer was missing. With it, the client can say "here is what we found, and here is what we could not ask". A shorter list is not a wrong list, but an undeclared short list is a misleading one.&lt;/p&gt;

&lt;p&gt;Getting there took one more thing that is easy to get wrong: the difference between "no matches" and "did not answer" has to be decided by the adapter, not by the caller. If an upstream returns 503 and the adapter returns an empty list, then the source reports a count of zero — and "Google Books has zero matching books" is a factual claim the code is making without checking anything.&lt;/p&gt;

&lt;p&gt;So the adapters throw on failure and return zero only when the upstream genuinely says there is nothing:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// src/lib/api/http.ts&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;data&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nx"&gt;fetchUpstreamJson&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nx"&gt;GoogleBooksResponse&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
  &lt;span class="nx"&gt;url&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;next&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;revalidate&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;3600&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="p"&gt;},&lt;/span&gt;
  &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;source&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;Google Books&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="na"&gt;emptyOnStatus&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="mi"&gt;404&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;);&lt;/span&gt;
&lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="nx"&gt;data&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;books&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[],&lt;/span&gt; &lt;span class="na"&gt;total&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt; &lt;span class="p"&gt;};&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;emptyOnStatus&lt;/code&gt; is per upstream, because "no match" is not a universal status code. LibriVox answers a title search that matches nothing with a 404 and a body of &lt;code&gt;{"error":"Audiobooks could not be found"}&lt;/code&gt; — that is a real answer, so for LibriVox a 404 is zero matches and not a failure. Every other source here answers no-match with a 200 and an empty list, so for them any error status is a failure.&lt;/p&gt;

&lt;p&gt;Transient statuses get retried before the source is written off, because a 503 from a busy API usually clears:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;isTransient&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;status&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kr"&gt;number&lt;/span&gt;&lt;span class="p"&gt;):&lt;/span&gt; &lt;span class="nx"&gt;boolean&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nx"&gt;status&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="mi"&gt;429&lt;/span&gt; &lt;span class="o"&gt;||&lt;/span&gt; &lt;span class="nx"&gt;status&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="mi"&gt;500&lt;/span&gt; &lt;span class="o"&gt;||&lt;/span&gt; &lt;span class="nx"&gt;status&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="mi"&gt;502&lt;/span&gt; &lt;span class="o"&gt;||&lt;/span&gt; &lt;span class="nx"&gt;status&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="mi"&gt;503&lt;/span&gt; &lt;span class="o"&gt;||&lt;/span&gt; &lt;span class="nx"&gt;status&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="mi"&gt;504&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Two retries, one shared deadline, so a single slow source cannot hold the request open indefinitely. This matters more than it sounds: Next.js caches a fetch only when the response status is 200, so a 503 is never cached and every retry reaches the real upstream rather than a stored failure.&lt;/p&gt;

&lt;p&gt;&lt;code&gt;partial&lt;/code&gt; is derived on every request, never stored:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// src/app/api/v1/search/route.ts&lt;/span&gt;
&lt;span class="nx"&gt;failedSources&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;outcome&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;failedSources&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="nx"&gt;partial&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;outcome&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;failedSources&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;length&lt;/span&gt; &lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;This is the part I care about most. If a UI renders &lt;code&gt;results&lt;/code&gt; without looking at &lt;code&gt;partial&lt;/code&gt;, then every time an upstream has a bad afternoon the site presents a truncated list as though it were the complete answer, and the reader concludes there are only a handful of books about Python. That is not a rendering bug — it is a factual claim, and the code is making it.&lt;/p&gt;

&lt;p&gt;So the UI has to say something. On our own search page a partial result set gets an explicit banner naming the sources that did not answer, rather than a smaller grid with no explanation. The same contract is documented for API consumers on &lt;code&gt;/developers/api&lt;/code&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  Nineteen upstream calls per request forces a real rate limit
&lt;/h2&gt;

&lt;p&gt;The cost model is unforgiving: one API request from us is nineteen requests to somebody else's server. Expose a public API on top of that without a quota and you have turned yourself into a load generator aimed at twelve services you do not control.&lt;/p&gt;

&lt;p&gt;The first version of the limiter was a &lt;code&gt;Map&lt;/code&gt; of timestamp arrays in process memory (&lt;code&gt;src/lib/rateLimit.ts&lt;/code&gt;):&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;buckets&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nb"&gt;Map&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="kr"&gt;string&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="kr"&gt;number&lt;/span&gt;&lt;span class="p"&gt;[]&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;It works fine on a single long-lived Node process. On serverless it is decoration. Every cold start gets a fresh empty map, and traffic spread across several instances gives every instance its own private bucket. A caller who exceeds the limit on instance A simply lands on instance B and starts again. You cannot cap a public API with process-local state.&lt;/p&gt;

&lt;p&gt;The fix is to keep the counters in Postgres, where every instance sees the same row. One round trip does the counting and the check together:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight sql"&gt;&lt;code&gt;&lt;span class="c1"&gt;-- supabase/migrations/012_public_api.sql&lt;/span&gt;
&lt;span class="k"&gt;insert&lt;/span&gt; &lt;span class="k"&gt;into&lt;/span&gt; &lt;span class="k"&gt;public&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;api_rate_limit&lt;/span&gt; &lt;span class="k"&gt;as&lt;/span&gt; &lt;span class="n"&gt;r&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;bucket&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;window_started_at&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;hits&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="k"&gt;values&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;p_bucket&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;v_now&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="k"&gt;on&lt;/span&gt; &lt;span class="n"&gt;conflict&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;bucket&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;do&lt;/span&gt; &lt;span class="k"&gt;update&lt;/span&gt;
  &lt;span class="k"&gt;set&lt;/span&gt; &lt;span class="n"&gt;hits&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;case&lt;/span&gt;
               &lt;span class="k"&gt;when&lt;/span&gt; &lt;span class="n"&gt;r&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;window_started_at&lt;/span&gt; &lt;span class="o"&gt;&amp;lt;&lt;/span&gt; &lt;span class="n"&gt;v_window&lt;/span&gt; &lt;span class="k"&gt;then&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt;
               &lt;span class="k"&gt;else&lt;/span&gt; &lt;span class="n"&gt;r&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;hits&lt;/span&gt; &lt;span class="o"&gt;+&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt;
             &lt;span class="k"&gt;end&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="n"&gt;window_started_at&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;case&lt;/span&gt;
               &lt;span class="k"&gt;when&lt;/span&gt; &lt;span class="n"&gt;r&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;window_started_at&lt;/span&gt; &lt;span class="o"&gt;&amp;lt;&lt;/span&gt; &lt;span class="n"&gt;v_window&lt;/span&gt; &lt;span class="k"&gt;then&lt;/span&gt; &lt;span class="n"&gt;v_now&lt;/span&gt;
               &lt;span class="k"&gt;else&lt;/span&gt; &lt;span class="n"&gt;r&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;window_started_at&lt;/span&gt;
             &lt;span class="k"&gt;end&lt;/span&gt;
&lt;span class="n"&gt;returning&lt;/span&gt; &lt;span class="n"&gt;r&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;hits&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;r&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;window_started_at&lt;/span&gt; &lt;span class="k"&gt;into&lt;/span&gt; &lt;span class="n"&gt;v_hits&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;v_started&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The &lt;code&gt;on conflict ... do update&lt;/code&gt; is the load-bearing part. It takes a row lock on the bucket for the duration of the statement, so two concurrent requests cannot both read the old count and both conclude they are under the limit. The naive version — select the count, compare, then update — has a read-modify-write race exactly when it matters most.&lt;/p&gt;

&lt;p&gt;Two details around it are easy to get wrong. First, the function is &lt;code&gt;security definer&lt;/code&gt;, and Postgres functions are executable by &lt;code&gt;PUBLIC&lt;/code&gt; by default; without an explicit revoke, anyone holding the anon key could call it with a limit of a billion and reset everyone's counters. We revoke execute from &lt;code&gt;public&lt;/code&gt;, &lt;code&gt;anon&lt;/code&gt; and &lt;code&gt;authenticated&lt;/code&gt;, granting it to &lt;code&gt;service_role&lt;/code&gt; only. Second, it is created with &lt;code&gt;set search_path = public&lt;/code&gt;, so a caller who can create objects in a schema they control cannot hijack name resolution inside it.&lt;/p&gt;

&lt;p&gt;We apply the per-minute and per-day windows in parallel, so the two counters cost one round trip of latency, and report the window the caller actually has to wait out — the minute window when that is the one that was exceeded, the day window when that is. And if the migration has not been applied yet, the RPC errors; rather than breaking the API outright we fall back to the per-instance limiter and report which scope answered, so the degradation is visible instead of silent.&lt;/p&gt;

&lt;h2&gt;
  
  
  The part I keep coming back to
&lt;/h2&gt;

&lt;p&gt;A partial result set and a complete result set are different things, and they should look different at every layer above the fan-out: the function signature, the JSON response, the rendered page, and the documentation for anyone consuming the API.&lt;/p&gt;

&lt;p&gt;An API that hides partial failure is lying, and the user cannot tell — which is exactly why the failure record has to travel all the way out to the screen instead of stopping at the function boundary.&lt;/p&gt;

</description>
      <category>webdev</category>
      <category>api</category>
      <category>typescript</category>
      <category>nextjs</category>
    </item>
  </channel>
</rss>
