persisting-and-orchestrating

Documents SQLite schema, frontier state machine, and crawl orchestration for a newsletter crawler.

2|1|Updated Jun 29, 2026
One-click install
npx skills add https://github.com/frederico-kluser/newsletter-crawler --skill persisting-and-orchestrating-frederico-kluser
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: persisting-and-orchestrating
Source: https://github.com/frederico-kluser/newsletter-crawler/tree/main/.agents/skills/persisting-and-orchestrating
Command: npx skills add https://github.com/frederico-kluser/newsletter-crawler --skill persisting-and-orchestrating-frederico-kluser

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Editing the data layer or crawl orchestration of this Node.js newsletter crawler without knowing the schema, queue semantics, or dedup rules leads to subtle bugs like lost backlog, zombie jobs, or broken delta anchors. This Skill injects the verified internal knowledge needed to safely modify src/db.js, src/crawl.js, src/curate.js, src/events.js, and src/index.js. ## Core Features & Use Cases - Schema and statements reference: Covers all tables (sources, pages, articles, frontier, events, searches), the single stmts object with claimNext/enqueue/insertArticle, and idempotent ensureColumn migrations. - Frontier and orchestration rules: Documents the pending/in_progress/done/failed state machine, resume via resetInProgress, the work-phase job clock with real abort, batched event writes, and the concurrency loop with streaming verify. - Dedup, dates, and pagination: Explains canonical URL plus content_hash dedup, the --since date floor, per-source capture cursors, and deterministic known-url pagination stops. - Use Case: When fixing a bug where re-crawling re-downloads already-known articles, consult this Skill to find the isUrlKnown four-branch guard and the maxArticleRunId delta anchor before touching crawl.js. ## Quick Start Ask the AI to explain how the frontier queue resumes after a crash and which statements in src/db.js to modify for a new article column.

Frequently Asked Questions about persisting-and-orchestrating

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How does the crawl frontier queue resume after a crash?

The frontier uses a pending/in_progress/done/failed state machine in SQLite. On startup, resetInProgress flips stale in_progress rows back to pending, and claimNext atomically claims jobs with UPDATE...RETURNING ordered by retries and id.

How is duplicate article detection implemented in the crawler?

Dedup combines canonical URL normalization with a UNIQUE url constraint and a UNIQUE content_hash column. Curated items hash their title plus blurb, and isUrlKnown checks articles, pages, frontier, and issue_url before enqueueing.

Why does the delta search anchor use maxArticleRunId instead of MAX(runs.id)?

Search, verify, and web-search commands also open runs but never set articles.run_id. Anchoring the delta on MAX(runs.id) would zero out the new-items scope, so the anchor is MAX(articles.run_id) instead.

What happens when an article job exceeds its deadline?

The job clock counts only fetch/render/parse work phases and aborts an AbortSignal on expiry, stopping in-flight requests and freeing lanes. Timed-out enrich jobs stay done with needs_enrich=1 and are re-queued on the next crawl.

Can I add a new column to the articles table safely?

Yes, all migrations use idempotent ensureColumn helpers in src/db.js, so adding a column is safe to run repeatedly. Verify the change boots cleanly with npm run status, which creates the schema and runs the count queries.