agent-bober 0.17.1 → 0.19.0

package/dist/seo/parser.d.ts

@@ -0,0 +1,46 @@
+/**
+ * SeoPlaybookParser — pure, TOTAL markdown parser for bober.seo-* skill files
+ * (spec-20260715-ultimate-seo-suite, Sprint 2; mirrors
+ * `SecuritySignatureParser`, src/orchestrator/security-knowledge/parser.ts:137-156).
+ *
+ * Block format (mirrored in skills/bober.seo-generic/SKILL.md's "## Signature
+ * Block Format" section — the two are one executable spec):
+ *
+ *   ### <playbookId>
+ *   - **Title:** <human-readable title>
+ *   - **Workflows:** comma, separated, SeoWorkflow, members
+ *   - **Tactic:** <the recommended action>
+ *   - **Invariant:** <the evidence-backed claim this signature encodes>
+ *   - **PrimarySourceUrl:** <REQUIRED citation URL>
+ *   - **PolicyClass:** auto-safe|human-approve|never-encode
+ *   - **EvidenceGrade:** verified|primary-unverified|single-source
+ *   - **LiveWeightStatus:** live-corroborated|documented-only|unknown (soft field, defaults to unknown)
+ *   - **Keywords:** comma, separated, keywords
+ *
+ * A block is split on a `### ` heading (heading text, trimmed, is the
+ * playbookId). Two DROP rules beyond the security template (architecture
+ * Data Model comments; research §5/§6):
+ *   1. `PrimarySourceUrl` missing/empty -> DROP (no-uncited-claim — the
+ *      whole point of this format).
+ *   2. `PolicyClass` === "never-encode" -> DROP (parasite SEO, expired-domain
+ *      plays, paid links, mass AI pages, AI-recommendation poisoning).
+ * Plus the standard: empty playbookId, missing Title, or an invalid
+ * PolicyClass value all drop the block. Never throws. No code fences here —
+ * SEO signatures carry `tactic`, not unsafe/safe examples, so there is no
+ * `extractFencedExample` machinery to port.
+ */
+import type { SeoSignature } from "./types.js";
+export declare const SeoPlaybookParser: {
+    /**
+     * Pure and total: parses `markdown` (no fs access), never throws, and
+     * returns ONLY the surviving signatures — dropped blocks (uncited or
+     * never-encode) are absent from the output entirely.
+     */
+    parse(markdown: string, skillRelPath: string): SeoSignature[];
+    /** Same as `parse`, plus a dropped-block count for report-diagnostics auditability. */
+    parseWithDiagnostics(markdown: string, skillRelPath: string): {
+        signatures: SeoSignature[];
+        dropped: number;
+    };
+};
+//# sourceMappingURL=parser.d.ts.map

package/dist/seo/parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../../src/seo/parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,OAAO,KAAK,EAAE,YAAY,EAAe,MAAM,YAAY,CAAC;AA8H5D,eAAO,MAAM,iBAAiB;IAC5B;;;;OAIG;oBACa,MAAM,gBAAgB,MAAM,GAAG,YAAY,EAAE;IAI7D,uFAAuF;mCACxD,MAAM,gBAAgB,MAAM,GAAG;QAAE,UAAU,EAAE,YAAY,EAAE,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE;CAc9G,CAAC"}

package/dist/seo/parser.js

@@ -0,0 +1,113 @@
+import { parseFrontmatter } from "../vault/frontmatter.js";
+// ── Type guards ──────────────────────────────────────────────────────
+const SEO_WORKFLOWS = [
+    "technical-audit",
+    "rank-track",
+    "content-decay",
+    "topical-map",
+    "ai-visibility",
+    "parasite-watch",
+    "internal-linking",
+    "schema-audit",
+];
+function isSeoWorkflow(value) {
+    return SEO_WORKFLOWS.includes(value);
+}
+const POLICY_CLASSES = ["auto-safe", "human-approve"];
+function isPolicyClass(value) {
+    return POLICY_CLASSES.includes(value);
+}
+const EVIDENCE_GRADES = ["verified", "primary-unverified", "single-source"];
+function isEvidenceGrade(value) {
+    return EVIDENCE_GRADES.includes(value);
+}
+const LIVE_WEIGHT_STATUSES = ["live-corroborated", "documented-only", "unknown"];
+function isLiveWeightStatus(value) {
+    return LIVE_WEIGHT_STATUSES.includes(value);
+}
+const LABEL_RE = /^-\s+\*\*(Title|Workflows|Tactic|Invariant|PrimarySourceUrl|PolicyClass|EvidenceGrade|LiveWeightStatus|Keywords):\*\*\s*(.*)$/;
+function extractLabelledFields(block) {
+    const fields = {};
+    for (const rawLine of block.split("\n")) {
+        const match = LABEL_RE.exec(rawLine.trim());
+        if (match)
+            fields[match[1]] = match[2].trim();
+    }
+    return fields;
+}
+// ── Block parsing ───────────────────────────────────────────────────
+/**
+ * Parse one "### <playbookId>" block. Returns null when the block is
+ * DROPPED: empty playbookId, missing Title, missing/empty PrimarySourceUrl
+ * (no-uncited-claim), PolicyClass === "never-encode", or an otherwise
+ * invalid PolicyClass value.
+ */
+function parseBlock(block, skillRelPath) {
+    const newlineIdx = block.indexOf("\n");
+    const playbookId = (newlineIdx === -1 ? block : block.slice(0, newlineIdx)).trim();
+    if (playbookId === "")
+        return null;
+    const fields = extractLabelledFields(block);
+    const title = fields.Title;
+    if (!title)
+        return null;
+    const primarySourceUrl = fields.PrimarySourceUrl;
+    if (!primarySourceUrl)
+        return null; // no-uncited-claim: HARD drop, no default
+    const policyClassRaw = fields.PolicyClass;
+    if (policyClassRaw === "never-encode")
+        return null; // never-encode: HARD drop
+    if (!policyClassRaw || !isPolicyClass(policyClassRaw))
+        return null;
+    const workflows = fields.Workflows
+        ? fields.Workflows.split(",")
+            .map((w) => w.trim())
+            .filter(isSeoWorkflow)
+        : [];
+    const evidenceGrade = fields.EvidenceGrade && isEvidenceGrade(fields.EvidenceGrade) ? fields.EvidenceGrade : "single-source";
+    const liveWeightStatus = fields.LiveWeightStatus && isLiveWeightStatus(fields.LiveWeightStatus) ? fields.LiveWeightStatus : "unknown";
+    const keywords = fields.Keywords
+        ? fields.Keywords.split(",")
+            .map((k) => k.trim())
+            .filter((k) => k.length > 0)
+        : [];
+    return {
+        playbookId,
+        workflows,
+        title,
+        tactic: fields.Tactic ?? "",
+        invariant: fields.Invariant ?? "",
+        primarySourceUrl,
+        policyClass: policyClassRaw,
+        evidenceGrade,
+        liveWeightStatus,
+        keywords,
+        skillRef: skillRelPath,
+    };
+}
+// ── Public parser ───────────────────────────────────────────────────
+export const SeoPlaybookParser = {
+    /**
+     * Pure and total: parses `markdown` (no fs access), never throws, and
+     * returns ONLY the surviving signatures — dropped blocks (uncited or
+     * never-encode) are absent from the output entirely.
+     */
+    parse(markdown, skillRelPath) {
+        return SeoPlaybookParser.parseWithDiagnostics(markdown, skillRelPath).signatures;
+    },
+    /** Same as `parse`, plus a dropped-block count for report-diagnostics auditability. */
+    parseWithDiagnostics(markdown, skillRelPath) {
+        if (typeof markdown !== "string")
+            return { signatures: [], dropped: 0 };
+        const { body } = parseFrontmatter(markdown);
+        const blocks = body.split(/^### /m).slice(1);
+        const signatures = [];
+        for (const block of blocks) {
+            const signature = parseBlock(block, skillRelPath);
+            if (signature)
+                signatures.push(signature);
+        }
+        return { signatures, dropped: blocks.length - signatures.length };
+    },
+};
+//# sourceMappingURL=parser.js.map

package/dist/seo/parser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.js","sourceRoot":"","sources":["../../src/seo/parser.ts"],"names":[],"mappings":"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"}

package/dist/seo/playbook-index.d.ts

@@ -0,0 +1,19 @@
+import type { SeoSignature } from "./types.js";
+export declare class SeoPlaybookIndex {
+    private readonly skillsRoot;
+    private cache;
+    constructor(skillsRoot?: string);
+    /**
+     * Parses every `skills/bober.seo-*` skill's `SKILL.md` file once and
+     * memoises the flat signature list. Idempotent — a second call returns the SAME array
+     * instance without re-reading the filesystem. Never throws: a missing
+     * skills directory, or any individual unreadable/unparseable SKILL.md,
+     * degrades to [] for that source rather than rejecting.
+     */
+    load(): Promise<SeoSignature[]>;
+    /** The full memoised list, or [] before load() has been called. Never throws. */
+    all(): SeoSignature[];
+    /** Every signature authored in the generic skill — the retriever's always-included floor. */
+    generic(): SeoSignature[];
+}
+//# sourceMappingURL=playbook-index.d.ts.map

package/dist/seo/playbook-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"playbook-index.d.ts","sourceRoot":"","sources":["../../src/seo/playbook-index.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAa/C,qBAAa,gBAAgB;IAGf,OAAO,CAAC,QAAQ,CAAC,UAAU;IAFvC,OAAO,CAAC,KAAK,CAA+B;gBAEf,UAAU,GAAE,MAA4B;IAErE;;;;;;OAMG;IACG,IAAI,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC;IA0BrC,iFAAiF;IACjF,GAAG,IAAI,YAAY,EAAE;IAIrB,6FAA6F;IAC7F,OAAO,IAAI,YAAY,EAAE;CAG1B"}

package/dist/seo/playbook-index.js

@@ -0,0 +1,74 @@
+/**
+ * SeoPlaybookIndex — per-process memoised catalog of every bober.seo-*
+ * skill's parsed SeoSignature[] (spec-20260715-ultimate-seo-suite, Sprint 2;
+ * mirrors `SecurityKnowledgeIndex`, src/orchestrator/security-knowledge/index.ts:35-70).
+ *
+ * Unlike the security index (fixed per-stack registry, `forStack` map), this
+ * index is a FLAT list: it `readdir`s the skills directory for every
+ * `bober.seo-*` entry (auto-discovering the per-workflow skills sprints 3-5
+ * add later — a non-playbook or empty skill parses to `[]`, harmlessly) and
+ * concatenates their parsed signatures. `load()` RETURNS the memoised list
+ * (the security template's `load()` returns void).
+ */
+import { readFile, readdir } from "node:fs/promises";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { SeoPlaybookParser } from "./parser.js";
+/**
+ * `src/seo/` sits ONE level below `src/` (unlike
+ * `src/orchestrator/security-knowledge/`, which sits two levels below
+ * `src/`), so the default skills root needs TWO `..`, not three:
+ * src/seo/ -> package root is ../.. ; skills live at <packageRoot>/skills.
+ */
+function defaultSkillsRoot() {
+    const currentDir = dirname(fileURLToPath(import.meta.url));
+    return join(currentDir, "..", "..", "skills");
+}
+export class SeoPlaybookIndex {
+    skillsRoot;
+    cache = null;
+    constructor(skillsRoot = defaultSkillsRoot()) {
+        this.skillsRoot = skillsRoot;
+    }
+    /**
+     * Parses every `skills/bober.seo-*` skill's `SKILL.md` file once and
+     * memoises the flat signature list. Idempotent — a second call returns the SAME array
+     * instance without re-reading the filesystem. Never throws: a missing
+     * skills directory, or any individual unreadable/unparseable SKILL.md,
+     * degrades to [] for that source rather than rejecting.
+     */
+    async load() {
+        if (this.cache)
+            return this.cache;
+        const out = [];
+        let entries;
+        try {
+            entries = await readdir(this.skillsRoot);
+        }
+        catch {
+            this.cache = [];
+            return this.cache;
+        }
+        for (const name of entries.filter((n) => n.startsWith("bober.seo-"))) {
+            const rel = join(name, "SKILL.md");
+            try {
+                const markdown = await readFile(join(this.skillsRoot, rel), "utf-8");
+                out.push(...SeoPlaybookParser.parse(markdown, rel));
+            }
+            catch {
+                // Missing/unreadable SKILL.md -> skip, never throw.
+            }
+        }
+        this.cache = out;
+        return this.cache;
+    }
+    /** The full memoised list, or [] before load() has been called. Never throws. */
+    all() {
+        return this.cache ?? [];
+    }
+    /** Every signature authored in the generic skill — the retriever's always-included floor. */
+    generic() {
+        return this.all().filter((s) => s.skillRef.includes("bober.seo-generic"));
+    }
+}
+//# sourceMappingURL=playbook-index.js.map

package/dist/seo/playbook-index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"playbook-index.js","sourceRoot":"","sources":["../../src/seo/playbook-index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAGhD;;;;;GAKG;AACH,SAAS,iBAAiB;IACxB,MAAM,UAAU,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IAC3D,OAAO,IAAI,CAAC,UAAU,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;AAChD,CAAC;AAED,MAAM,OAAO,gBAAgB;IAGE;IAFrB,KAAK,GAA0B,IAAI,CAAC;IAE5C,YAA6B,aAAqB,iBAAiB,EAAE;QAAxC,eAAU,GAAV,UAAU,CAA8B;IAAG,CAAC;IAEzE;;;;;;OAMG;IACH,KAAK,CAAC,IAAI;QACR,IAAI,IAAI,CAAC,KAAK;YAAE,OAAO,IAAI,CAAC,KAAK,CAAC;QAElC,MAAM,GAAG,GAAmB,EAAE,CAAC;QAC/B,IAAI,OAAiB,CAAC;QACtB,IAAI,CAAC;YACH,OAAO,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QAC3C,CAAC;QAAC,MAAM,CAAC;YACP,IAAI,CAAC,KAAK,GAAG,EAAE,CAAC;YAChB,OAAO,IAAI,CAAC,KAAK,CAAC;QACpB,CAAC;QAED,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC,EAAE,CAAC;YACrE,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;YACnC,IAAI,CAAC;gBACH,MAAM,QAAQ,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,GAAG,CAAC,EAAE,OAAO,CAAC,CAAC;gBACrE,GAAG,CAAC,IAAI,CAAC,GAAG,iBAAiB,CAAC,KAAK,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,CAAC;YACtD,CAAC;YAAC,MAAM,CAAC;gBACP,oDAAoD;YACtD,CAAC;QACH,CAAC;QAED,IAAI,CAAC,KAAK,GAAG,GAAG,CAAC;QACjB,OAAO,IAAI,CAAC,KAAK,CAAC;IACpB,CAAC;IAED,iFAAiF;IACjF,GAAG;QACD,OAAO,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC;IAC1B,CAAC;IAED,6FAA6F;IAC7F,OAAO;QACL,OAAO,IAAI,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,mBAAmB,CAAC,CAAC,CAAC;IAC5E,CAAC;CACF"}

package/dist/seo/quota-governor.d.ts

@@ -0,0 +1,100 @@
+/**
+ * SeoQuotaGovernor — the cost/quota safety layer gating the live GSC and
+ * DataForSEO adapters (spec-20260715-ultimate-seo-suite, Sprint 7; wired
+ * into adapters in sprints 8-9, NOT this sprint).
+ *
+ * `admit(req)` is SYNCHRONOUS, NEVER throws, and has NO side effect on
+ * either outcome (refuse or admit) — only `record()`, called by the caller
+ * AFTER a real successful API round-trip, advances any counter (in-memory
+ * rate-window timestamps or the persisted ledger). This mirrors the
+ * `SeoEgressGuard` guard-class shape (`src/seo/egress.ts:19-57`).
+ *
+ * Two kinds of state:
+ *  - In-memory rolling QPM windows (per-instance, ephemeral, NOT persisted;
+ *    reset on process restart — acceptable because the hard daily/USD
+ *    ceilings below are what must survive across processes).
+ *  - The persisted `.bober/seo/quota-ledger.json` (daily rows / URL
+ *    inspections / USD spend), read via `quota-ledger.ts` and shared by
+ *    every `SeoQuotaGovernor` instance pointed at the same path through the
+ *    module-scoped per-path mutex in `withLedgerLock` — this is what makes
+ *    `record()` never lose a concurrent update (sc-7-3).
+ *
+ * Fail-closed: an unreadable/corrupt ledger is treated as at-ceiling for
+ * every persisted counter (rows/URL-inspections/spend read back as
+ * `Infinity`), so any COSTED request touching that counter is refused
+ * (sc-7-4). A MISSING ledger (first run / offline) is a fresh `{}` — allow.
+ *
+ * Pinned caps (research §4, exact numbers — DO NOT approximate):
+ *  - GSC Search Analytics: 1,200 QPM per-site AND 1,200 QPM per-user
+ *    (two independent rolling windows), 50,000 rows/day per search type.
+ *  - GSC URL Inspection: 2,000 queries/day/property, 600 QPM.
+ *  - DataForSEO: caller-supplied `estCostUsd`/actual cost booked against
+ *    `config.seo.budget.maxUsd` (`null`/absent = uncapped, mirrors
+ *    `src/orchestrator/workflow/budget.ts:99-104,148-150`).
+ */
+import type { BoberConfig } from "../config/schema.js";
+import type { SeoCapability } from "./data-source.js";
+/** One gated request. `capability` defaults to `"search-analytics"` for `source: "gsc"` when omitted. */
+export type QuotaRequest = {
+    source: "gsc" | "dataforseo" | "ai-visibility";
+    /** GSC caps are modeled per-site AND per-user separately (research §4) — supply what you have. */
+    scope: {
+        siteUrl?: string;
+        userId?: string;
+    };
+    /** Which GSC/DataForSEO capability this call exercises; required to pick daily-rows vs url-inspection-cap. */
+    capability?: SeoCapability;
+    /** Rows this call will consume against the daily row / URL-inspection ceiling. 0 for calls that consume none. */
+    estRows: number;
+    /** Estimated USD cost, booked against `config.seo.budget.maxUsd` in `admit()`. 0 for free (GSC) calls. */
+    estCostUsd: number;
+};
+export type QuotaRefusalReason = "rate-window" | "daily-rows" | "url-inspection-cap" | "budget-exceeded";
+export type QuotaDecision = {
+    admit: true;
+} | {
+    admit: false;
+    reason: QuotaRefusalReason;
+};
+/**
+ * bober: in-memory rolling-window arrays keyed by site/user string; fine at
+ *        the QPM scale this governs (a handful of timestamps per key per
+ *        minute) — swap for a proper token-bucket structure if the number
+ *        of distinct sites/users governed by one process ever gets large.
+ */
+export declare class SeoQuotaGovernor {
+    private readonly ledgerPath;
+    private readonly maxUsd;
+    private ledger;
+    /** In-memory-only; NOT persisted. Populated exclusively by `record()`. */
+    private readonly searchAnalyticsSiteWindows;
+    private readonly searchAnalyticsUserWindows;
+    private readonly urlInspectionSiteWindows;
+    private constructor();
+    /** Load a governor bound to `ledgerPath`, reading its current state and `config.seo.budget.maxUsd`. */
+    static load(ledgerPath: string, config: BoberConfig): Promise<SeoQuotaGovernor>;
+    /**
+     * Decide whether `req` may proceed. SYNCHRONOUS, NEVER throws, and has
+     * NO side effect on either branch — callers must call `record()`
+     * themselves after a real successful API round-trip.
+     */
+    admit(req: QuotaRequest): QuotaDecision;
+    /**
+     * Persist a completed call. Only ever called AFTER `admit()` returned
+     * `{ admit: true }` and the real API call succeeded. Advances the
+     * in-memory rate window for this instance and the shared persisted
+     * ledger via the atomic, mutex-serialized read-modify-write in
+     * `quota-ledger.ts` — concurrent `record()` calls across governor
+     * instances sharing `ledgerPath` never lose an update (sc-7-3).
+     */
+    record(req: QuotaRequest, actualCostUsd: number): Promise<void>;
+    /** Cumulative persisted USD spend across all recorded days. `+Infinity` when the ledger is corrupt (at-ceiling). */
+    spentUsd(): number;
+    private rowsToday;
+    private urlInspectionsToday;
+    /** True when admitting one more call at `key` keeps the trailing `WINDOW_MS` count within `cap`. Read-only — no mutation. */
+    private hasWindowHeadroom;
+    /** Advance the window for `key`: prune stale entries and append `now`. Only called from `record()`. */
+    private pushTimestamp;
+}
+//# sourceMappingURL=quota-governor.d.ts.map

package/dist/seo/quota-governor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"quota-governor.d.ts","sourceRoot":"","sources":["../../src/seo/quota-governor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AActD,yGAAyG;AACzG,MAAM,MAAM,YAAY,GAAG;IAKzB,MAAM,EAAE,KAAK,GAAG,YAAY,GAAG,eAAe,CAAC;IAC/C,kGAAkG;IAClG,KAAK,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC7C,8GAA8G;IAC9G,UAAU,CAAC,EAAE,aAAa,CAAC;IAC3B,iHAAiH;IACjH,OAAO,EAAE,MAAM,CAAC;IAChB,0GAA0G;IAC1G,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG,aAAa,GAAG,YAAY,GAAG,oBAAoB,GAAG,iBAAiB,CAAC;AAEzG,MAAM,MAAM,aAAa,GAAG;IAAE,KAAK,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,kBAAkB,CAAA;CAAE,CAAC;AAI3F;;;;;GAKG;AACH,qBAAa,gBAAgB;IAOzB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,MAAM;IARhB,0EAA0E;IAC1E,OAAO,CAAC,QAAQ,CAAC,0BAA0B,CAA+B;IAC1E,OAAO,CAAC,QAAQ,CAAC,0BAA0B,CAA+B;IAC1E,OAAO,CAAC,QAAQ,CAAC,wBAAwB,CAA+B;IAExE,OAAO;IAMP,uGAAuG;WAC1F,IAAI,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAMrF;;;;OAIG;IACH,KAAK,CAAC,GAAG,EAAE,YAAY,GAAG,aAAa;IA8CvC;;;;;;;OAOG;IACG,MAAM,CAAC,GAAG,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAsCrE,oHAAoH;IACpH,QAAQ,IAAI,MAAM;IAOlB,OAAO,CAAC,SAAS;IAKjB,OAAO,CAAC,mBAAmB;IAO3B,6HAA6H;IAC7H,OAAO,CAAC,iBAAiB;IAOzB,uGAAuG;IACvG,OAAO,CAAC,aAAa;CAKtB"}

package/dist/seo/quota-governor.js

@@ -0,0 +1,199 @@
+/**
+ * SeoQuotaGovernor — the cost/quota safety layer gating the live GSC and
+ * DataForSEO adapters (spec-20260715-ultimate-seo-suite, Sprint 7; wired
+ * into adapters in sprints 8-9, NOT this sprint).
+ *
+ * `admit(req)` is SYNCHRONOUS, NEVER throws, and has NO side effect on
+ * either outcome (refuse or admit) — only `record()`, called by the caller
+ * AFTER a real successful API round-trip, advances any counter (in-memory
+ * rate-window timestamps or the persisted ledger). This mirrors the
+ * `SeoEgressGuard` guard-class shape (`src/seo/egress.ts:19-57`).
+ *
+ * Two kinds of state:
+ *  - In-memory rolling QPM windows (per-instance, ephemeral, NOT persisted;
+ *    reset on process restart — acceptable because the hard daily/USD
+ *    ceilings below are what must survive across processes).
+ *  - The persisted `.bober/seo/quota-ledger.json` (daily rows / URL
+ *    inspections / USD spend), read via `quota-ledger.ts` and shared by
+ *    every `SeoQuotaGovernor` instance pointed at the same path through the
+ *    module-scoped per-path mutex in `withLedgerLock` — this is what makes
+ *    `record()` never lose a concurrent update (sc-7-3).
+ *
+ * Fail-closed: an unreadable/corrupt ledger is treated as at-ceiling for
+ * every persisted counter (rows/URL-inspections/spend read back as
+ * `Infinity`), so any COSTED request touching that counter is refused
+ * (sc-7-4). A MISSING ledger (first run / offline) is a fresh `{}` — allow.
+ *
+ * Pinned caps (research §4, exact numbers — DO NOT approximate):
+ *  - GSC Search Analytics: 1,200 QPM per-site AND 1,200 QPM per-user
+ *    (two independent rolling windows), 50,000 rows/day per search type.
+ *  - GSC URL Inspection: 2,000 queries/day/property, 600 QPM.
+ *  - DataForSEO: caller-supplied `estCostUsd`/actual cost booked against
+ *    `config.seo.budget.maxUsd` (`null`/absent = uncapped, mirrors
+ *    `src/orchestrator/workflow/budget.ts:99-104,148-150`).
+ */
+import { dateKey, scopeKey, readLedger, writeLedgerAtomic, withLedgerLock } from "./quota-ledger.js";
+// -- Pinned caps (research §4) -------------------------------------------
+const GSC_QPM = 1_200; // Search Analytics: 1,200 QPM, per-site AND per-user (separate windows).
+const GSC_ROWS_PER_DAY = 50_000; // Search Analytics: 50,000 rows/day per search type.
+const GSC_URL_INSPECT_PER_DAY = 2_000; // URL Inspection: 2,000 queries/day/property.
+const GSC_URL_INSPECT_QPM = 600; // URL Inspection: 600 QPM.
+const WINDOW_MS = 60_000; // Rolling one-minute QPM window.
+// -- Governor ---------------------------------------------------------------
+/**
+ * bober: in-memory rolling-window arrays keyed by site/user string; fine at
+ *        the QPM scale this governs (a handful of timestamps per key per
+ *        minute) — swap for a proper token-bucket structure if the number
+ *        of distinct sites/users governed by one process ever gets large.
+ */
+export class SeoQuotaGovernor {
+    ledgerPath;
+    maxUsd;
+    ledger;
+    /** In-memory-only; NOT persisted. Populated exclusively by `record()`. */
+    searchAnalyticsSiteWindows = new Map();
+    searchAnalyticsUserWindows = new Map();
+    urlInspectionSiteWindows = new Map();
+    constructor(ledgerPath, maxUsd, ledger) {
+        this.ledgerPath = ledgerPath;
+        this.maxUsd = maxUsd;
+        this.ledger = ledger;
+    }
+    /** Load a governor bound to `ledgerPath`, reading its current state and `config.seo.budget.maxUsd`. */
+    static async load(ledgerPath, config) {
+        const maxUsd = config.seo?.budget?.maxUsd ?? null; // null/absent = uncapped
+        const ledger = await readLedger(ledgerPath); // "corrupt" sentinel propagates fail-closed
+        return new SeoQuotaGovernor(ledgerPath, maxUsd, ledger);
+    }
+    /**
+     * Decide whether `req` may proceed. SYNCHRONOUS, NEVER throws, and has
+     * NO side effect on either branch — callers must call `record()`
+     * themselves after a real successful API round-trip.
+     */
+    admit(req) {
+        try {
+            const capability = effectiveCapability(req);
+            // 1. Rolling QPM window(s) — in-memory, ephemeral, advanced only by record().
+            if (req.source === "gsc") {
+                if (capability === "url-inspection") {
+                    if (!this.hasWindowHeadroom(this.urlInspectionSiteWindows, req.scope.siteUrl ?? "", GSC_URL_INSPECT_QPM)) {
+                        return { admit: false, reason: "rate-window" };
+                    }
+                }
+                else {
+                    if (!this.hasWindowHeadroom(this.searchAnalyticsSiteWindows, req.scope.siteUrl ?? "", GSC_QPM)) {
+                        return { admit: false, reason: "rate-window" };
+                    }
+                    if (!this.hasWindowHeadroom(this.searchAnalyticsUserWindows, req.scope.userId ?? "", GSC_QPM)) {
+                        return { admit: false, reason: "rate-window" };
+                    }
+                }
+            }
+            // 2. Persisted daily caps — fail-closed to Infinity when the ledger is corrupt.
+            if (req.source === "gsc") {
+                const sk = scopeKey(req.scope);
+                if (capability === "url-inspection") {
+                    if (this.urlInspectionsToday(sk) + req.estRows > GSC_URL_INSPECT_PER_DAY) {
+                        return { admit: false, reason: "url-inspection-cap" };
+                    }
+                }
+                else {
+                    if (this.rowsToday(sk) + req.estRows > GSC_ROWS_PER_DAY) {
+                        return { admit: false, reason: "daily-rows" };
+                    }
+                }
+            }
+            // 3. USD budget — skipped entirely when uncapped (maxUsd === null).
+            if (this.maxUsd !== null && this.spentUsd() + req.estCostUsd > this.maxUsd) {
+                return { admit: false, reason: "budget-exceeded" };
+            }
+            return { admit: true };
+        }
+        catch {
+            // Defensive: admit() must never throw. Any unexpected failure fails closed.
+            return { admit: false, reason: "budget-exceeded" };
+        }
+    }
+    /**
+     * Persist a completed call. Only ever called AFTER `admit()` returned
+     * `{ admit: true }` and the real API call succeeded. Advances the
+     * in-memory rate window for this instance and the shared persisted
+     * ledger via the atomic, mutex-serialized read-modify-write in
+     * `quota-ledger.ts` — concurrent `record()` calls across governor
+     * instances sharing `ledgerPath` never lose an update (sc-7-3).
+     */
+    async record(req, actualCostUsd) {
+        const capability = effectiveCapability(req);
+        const now = Date.now();
+        if (req.source === "gsc") {
+            if (capability === "url-inspection") {
+                this.pushTimestamp(this.urlInspectionSiteWindows, req.scope.siteUrl ?? "", now);
+            }
+            else {
+                this.pushTimestamp(this.searchAnalyticsSiteWindows, req.scope.siteUrl ?? "", now);
+                this.pushTimestamp(this.searchAnalyticsUserWindows, req.scope.userId ?? "", now);
+            }
+        }
+        await withLedgerLock(this.ledgerPath, async () => {
+            const fresh = await readLedger(this.ledgerPath); // read fresh from disk INSIDE the lock
+            const ledger = fresh === "corrupt" ? {} : fresh; // record() heals; corruption blocks admit, not record
+            const dk = dateKey(new Date());
+            const sk = scopeKey(req.scope);
+            const day = (ledger[dk] ??= { spentUsd: 0, scopes: {} });
+            const scope = (day.scopes[sk] ??= { rowsToday: 0, urlInspectionsToday: 0 });
+            // Guard NaN/negative cost (mirrors budget.ts:65-68) — never corrupt spentUsd.
+            if (Number.isFinite(actualCostUsd) && actualCostUsd > 0) {
+                day.spentUsd += actualCostUsd;
+            }
+            if (req.source === "gsc" && Number.isFinite(req.estRows) && req.estRows > 0) {
+                if (capability === "url-inspection") {
+                    scope.urlInspectionsToday += req.estRows;
+                }
+                else {
+                    scope.rowsToday += req.estRows;
+                }
+            }
+            await writeLedgerAtomic(this.ledgerPath, ledger);
+            this.ledger = ledger; // refresh this instance's in-memory snapshot
+        });
+    }
+    /** Cumulative persisted USD spend across all recorded days. `+Infinity` when the ledger is corrupt (at-ceiling). */
+    spentUsd() {
+        if (this.ledger === "corrupt")
+            return Number.POSITIVE_INFINITY;
+        return Object.values(this.ledger).reduce((sum, day) => sum + day.spentUsd, 0);
+    }
+    // -- Ledger read helpers (fail-closed to Infinity when corrupt) --------
+    rowsToday(sk) {
+        if (this.ledger === "corrupt")
+            return Number.POSITIVE_INFINITY;
+        return this.ledger[dateKey(new Date())]?.scopes[sk]?.rowsToday ?? 0;
+    }
+    urlInspectionsToday(sk) {
+        if (this.ledger === "corrupt")
+            return Number.POSITIVE_INFINITY;
+        return this.ledger[dateKey(new Date())]?.scopes[sk]?.urlInspectionsToday ?? 0;
+    }
+    // -- In-memory rolling-window helpers ------------------------------------
+    /** True when admitting one more call at `key` keeps the trailing `WINDOW_MS` count within `cap`. Read-only — no mutation. */
+    hasWindowHeadroom(windows, key, cap) {
+        const now = Date.now();
+        const timestamps = windows.get(key) ?? [];
+        const active = timestamps.filter((t) => now - t < WINDOW_MS);
+        return active.length + 1 <= cap;
+    }
+    /** Advance the window for `key`: prune stale entries and append `now`. Only called from `record()`. */
+    pushTimestamp(windows, key, now) {
+        const active = (windows.get(key) ?? []).filter((t) => now - t < WINDOW_MS);
+        active.push(now);
+        windows.set(key, active);
+    }
+}
+// -- Internal --------------------------------------------------------------
+/** GSC requests default to `"search-analytics"` when `capability` is omitted; DataForSEO requests have no GSC-specific default. */
+function effectiveCapability(req) {
+    if (req.capability)
+        return req.capability;
+    return req.source === "gsc" ? "search-analytics" : undefined;
+}
+//# sourceMappingURL=quota-governor.js.map

package/dist/seo/quota-governor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"quota-governor.js","sourceRoot":"","sources":["../../src/seo/quota-governor.ts"],"names":[],"mappings":"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"}

package/dist/seo/quota-ledger.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Persisted quota ledger — pure persistence + keying helpers, no quota
+ * decision logic (that lives in `quota-governor.ts`).
+ *
+ * Layout: `.bober/seo/quota-ledger.json`.
+ *
+ * Every write is atomic via temp-file + rename (mirrors
+ * `src/incident/timeline.ts:86-92` atomicWriteJson / `src/state/run-state.ts:41-52`).
+ *
+ * Concurrent read-modify-write calls to the SAME resolved path are serialized
+ * via a module-scoped per-path promise-chain mutex (mirrors
+ * `src/telemetry/emit.ts:57,85-86`) so two `SeoQuotaGovernor` instances
+ * sharing a ledger path never lose an update.
+ *
+ * Fail-closed discrimination: a MISSING ledger (ENOENT) is a fresh, empty
+ * ledger (offline / first-run => allow). An EXISTING-but-unparseable or
+ * unreadable ledger is the `"corrupt"` sentinel (fail-closed => at-ceiling).
+ * This is deliberately NOT the blanket catch used by `readRunState`
+ * (`src/state/run-state.ts:61-68`), which collapses both cases to `null`.
+ *
+ * Sprint 7 — spec-20260715-ultimate-seo-suite.
+ */
+import type { SeoQuotaLedger } from "./types.js";
+/** `YYYY-MM-DD` date key; daily counters reset on this boundary. */
+export declare function dateKey(now: Date): string;
+/** Composite per-site/per-user scope key (`${siteUrl}|${userId}`). */
+export declare function scopeKey(scope: {
+    siteUrl?: string;
+    userId?: string;
+}): string;
+/**
+ * Read the ledger from disk.
+ *
+ * - Missing file (ENOENT) => fresh empty ledger `{}` (offline/first-run, NOT corrupt).
+ * - Existing-but-unreadable (permissions, etc.) or unparseable JSON => `"corrupt"`
+ *   sentinel so the caller can fail closed (treat spend as at-ceiling).
+ */
+export declare function readLedger(path: string): Promise<SeoQuotaLedger | "corrupt">;
+/**
+ * Atomically overwrite the ledger: write a unique temp file, then rename
+ * (POSIX-atomic) so a crash mid-write can never leave a torn/corrupt file.
+ */
+export declare function writeLedgerAtomic(path: string, ledger: SeoQuotaLedger): Promise<void>;
+/**
+ * Run `fn` exclusively with respect to any other `withLedgerLock` call on
+ * the same resolved path. Chains onto the previous run regardless of
+ * whether it resolved or rejected, so one failure never wedges the chain.
+ */
+export declare function withLedgerLock<T>(path: string, fn: () => Promise<T>): Promise<T>;
+//# sourceMappingURL=quota-ledger.d.ts.map

package/dist/seo/quota-ledger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"quota-ledger.d.ts","sourceRoot":"","sources":["../../src/seo/quota-ledger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAOH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAIjD,oEAAoE;AACpE,wBAAgB,OAAO,CAAC,GAAG,EAAE,IAAI,GAAG,MAAM,CAEzC;AAED,sEAAsE;AACtE,wBAAgB,QAAQ,CAAC,KAAK,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAE7E;AAID;;;;;;GAMG;AACH,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC,CAalF;AAID;;;GAGG;AACH,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAQ3F;AAYD;;;;GAIG;AACH,wBAAsB,cAAc,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAYtF"}