@indigoai-us/hq-cli 5.220.0 → 5.222.0

package/dist/lib/checkpoint-ontology/multi-writer.js

@@ -0,0 +1,391 @@
+/**
+ * Several checkpoint writers in one company vault (design section 20).
+ *
+ * Gated by `checkpoint.ontology.multi-writer`. Three parts:
+ *
+ * - The outbox records the exact bytes this machine's checkpoint wrote to
+ *   each entity file. Sync pushes an entity file only when it still matches
+ *   its outbox entry, so an old pulled copy is never uploaded (C1, C2).
+ * - Merge-back re-applies the monotone part of an entity version that sync
+ *   set aside after losing a push race (C3, C4). A version whose entity was
+ *   deleted stays aside (C6); one that differs in keys the checkpoint does
+ *   not own is merged for the owned keys and also stays aside (C8).
+ * - The duplicate scan reports entities of one type whose names collide, with
+ *   a proposed survivor. Nothing is deleted (C5, C7).
+ */
+import { createHash } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { isDeepStrictEqual } from "node:util";
+import { entityKey, freshAliases, ownNames } from "./aliases.js";
+import { entitiesRoot, safeWriteFile } from "./company.js";
+import { appendBackRefs, OWNED_KEYS, parseEntityFile, patchEntityFile, validateEntityFrontmatter, } from "./entity-file.js";
+import { isWritableEntityType, squash } from "./identity.js";
+import { buildEntityIndex, indexAlias } from "./tree.js";
+export const OUTBOX_SCHEMA = "hq-ontology-outbox.v1";
+export const OUTBOX_DIR = ".hq/ontology-outbox";
+export const OUTBOX_RETENTION_MS = 30 * 24 * 60 * 60 * 1000;
+/** Where sync parks a losing local body (hq-cloud `CONFLICT_BACKUPS_DIR`). */
+export const CONFLICT_BACKUPS_DIR = ".hq/conflict-backups";
+export const MERGED_BACKUPS_DIR = ".hq/conflict-backups/ontology-merged";
+export const STALE_BACKUP_MS = 7 * 24 * 60 * 60 * 1000;
+export const DUPLICATE_REPORT_LIMIT = 20;
+/**
+ * Keys that differ between two versions of a new entity for reasons that say
+ * nothing about its content. The vault's value stands and the difference is
+ * not reported.
+ */
+const IGNORED_ON_MERGE = new Set(["first_seen"]);
+/** hq-cloud `buildConflictBackupPath`: `<file>.md.<YYYY-MM-DDTHH-MM-SSZ>-<machine>.md`. */
+const BACKUP_NAME_RE = /^(.+\.md)\.(\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}Z)-([a-f0-9]+|unknown)\.md$/;
+const TYPE_DIR_RE = /^[a-z][a-z0-9-]*$/;
+/** One back-reference line, as `appendBackRefs` and the gardener write it. */
+const BACKREF_LINE_RE = /^- Referenced in \[([A-Za-z_]+): (.*)\]\(([^)\s]+)\)\s*$/;
+function sha256(content) {
+    return createHash("sha256").update(content, "utf8").digest("hex");
+}
+export function outboxPath(hqRoot, company) {
+    return path.join(hqRoot, ...OUTBOX_DIR.split("/"), `${company.slug}.json`);
+}
+/** The company's outbox. A missing file is an empty outbox; an unreadable one throws. */
+export function readOutbox(hqRoot, company) {
+    const empty = { schema: OUTBOX_SCHEMA, company: company.slug, entries: {} };
+    let raw;
+    try {
+        raw = fs.readFileSync(outboxPath(hqRoot, company), "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return empty;
+        throw error;
+    }
+    const doc = JSON.parse(raw);
+    if (doc.schema !== OUTBOX_SCHEMA || doc.company !== company.slug || !doc.entries || typeof doc.entries !== "object") {
+        throw new Error("outbox has an unexpected shape");
+    }
+    return { schema: OUTBOX_SCHEMA, company: company.slug, entries: doc.entries };
+}
+/**
+ * Record entity bytes this checkpoint wrote, and drop entries older than the
+ * retention window. An unreadable outbox is replaced: a lost entry only makes
+ * sync hold that file back, which is the safe direction.
+ */
+export function recordOutbox(hqRoot, company, writes, now) {
+    let outbox;
+    let reset = false;
+    try {
+        outbox = readOutbox(hqRoot, company);
+    }
+    catch {
+        outbox = { schema: OUTBOX_SCHEMA, company: company.slug, entries: {} };
+        reset = true;
+    }
+    const cutoff = now.getTime() - OUTBOX_RETENTION_MS;
+    const entries = {};
+    for (const [rel, entry] of Object.entries(outbox.entries)) {
+        const at = Date.parse(entry?.written_at ?? "");
+        if (typeof entry?.sha256 === "string" && Number.isFinite(at) && at >= cutoff)
+            entries[rel] = entry;
+    }
+    for (const write of writes)
+        entries[write.rel] = { sha256: sha256(write.content), written_at: now.toISOString() };
+    const sorted = Object.fromEntries(Object.entries(entries).sort(([a], [b]) => a.localeCompare(b)));
+    const doc = { schema: OUTBOX_SCHEMA, company: company.slug, entries: sorted };
+    safeWriteFile(hqRoot, [path.join(hqRoot, ...OUTBOX_DIR.split("/"))], outboxPath(hqRoot, company), `${JSON.stringify(doc, null, 2)}\n`);
+    return { reset };
+}
+/** A directory that exists and is not a symlink. */
+function isRealDir(dir) {
+    try {
+        return fs.lstatSync(dir).isDirectory();
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+}
+/** Set-aside entity versions of this company, oldest first per entity. */
+function listEntityBackups(hqRoot, company) {
+    const segments = [...CONFLICT_BACKUPS_DIR.split("/"), "companies", company.slug, "ontology", "entities"];
+    for (let i = 1; i <= segments.length; i += 1) {
+        if (!isRealDir(path.join(hqRoot, ...segments.slice(0, i))))
+            return [];
+    }
+    const root = path.join(hqRoot, ...segments);
+    const out = [];
+    for (const typeDir of fs.readdirSync(root, { withFileTypes: true })) {
+        // Other entity types (contacts, deals) belong to other writers.
+        if (!typeDir.isDirectory() || !TYPE_DIR_RE.test(typeDir.name) || !isWritableEntityType(typeDir.name))
+            continue;
+        for (const file of fs.readdirSync(path.join(root, typeDir.name), { withFileTypes: true })) {
+            const match = file.isFile() ? BACKUP_NAME_RE.exec(file.name) : null;
+            if (!match)
+                continue;
+            out.push({
+                full: path.join(root, typeDir.name, file.name),
+                hqRel: [...segments, typeDir.name, file.name].join("/"),
+                target: `ontology/entities/${typeDir.name}/${match[1]}`,
+                stampedAt: match[2],
+            });
+        }
+    }
+    return out.sort((a, b) => a.target.localeCompare(b.target) || a.stampedAt.localeCompare(b.stampedAt) || a.hqRel.localeCompare(b.hqRel));
+}
+/** The later of two ISO timestamps; an unparseable one loses. */
+function later(a, b) {
+    const ta = Date.parse(a);
+    const tb = Date.parse(b);
+    if (!Number.isFinite(ta))
+        return b;
+    if (!Number.isFinite(tb))
+        return a;
+    return tb > ta ? b : a;
+}
+/** Back-reference lines in a body, as refs `appendBackRefs` can re-add. */
+export function readBackRefs(body) {
+    const out = [];
+    for (const line of body.split(/\r?\n/)) {
+        const match = BACKREF_LINE_RE.exec(line);
+        if (match)
+            out.push({ signalType: match[1], preview: match[2], href: match[3] });
+    }
+    return out;
+}
+/** The body with back-reference lines and blank lines removed, for comparing prose. */
+function proseOf(body) {
+    return body
+        .split(/\r?\n/)
+        .filter((line) => !BACKREF_LINE_RE.test(line) && !/^##\s+Relationships\s*$/.test(line))
+        .map((line) => line.trimEnd())
+        .filter((line) => line !== "")
+        .join("\n");
+}
+/** Keys the checkpoint does not own whose values differ, plus `body` for prose. */
+function unownedDifferences(backup, current) {
+    const keys = [...new Set([...Object.keys(backup.frontmatter), ...Object.keys(current.frontmatter)])].sort();
+    const out = keys.filter((key) => !OWNED_KEYS.has(key) && !IGNORED_ON_MERGE.has(key) && !isDeepStrictEqual(backup.frontmatter[key], current.frontmatter[key]));
+    if (proseOf(backup.body) !== proseOf(current.body))
+        out.push("body");
+    return out;
+}
+/**
+ * Re-apply set-aside entity versions of this company to the current files
+ * (design 20.4). Never deletes an entity file and never re-creates one.
+ */
+export function mergeBackConflicts(hqRoot, company, now) {
+    const run = { outcomes: [], writes: [] };
+    const backups = listEntityBackups(hqRoot, company);
+    if (backups.length === 0)
+        return run;
+    const index = buildEntityIndex(company.dir);
+    const entityRoot = entitiesRoot(company);
+    for (const backup of backups) {
+        const outcome = (result, detail) => run.outcomes.push({ backup: backup.hqRel, target: backup.target, result, ...(detail ? { detail } : {}) });
+        const saved = parseEntityFile(fs.readFileSync(backup.full, "utf8"));
+        const savedFields = saved ? validateEntityFrontmatter(saved.frontmatter) : "unparseable";
+        if (!saved || typeof savedFields === "string") {
+            outcome("invalid", `backup:${savedFields}`);
+            continue;
+        }
+        const savedUpdated = String(saved.frontmatter.last_updated);
+        const savedAt = Date.parse(savedUpdated);
+        if (!Number.isFinite(savedAt)) {
+            outcome("invalid", "backup:last_updated");
+            continue;
+        }
+        if (now.getTime() - savedAt > STALE_BACKUP_MS) {
+            outcome("stale");
+            continue;
+        }
+        const targetFull = path.join(company.dir, backup.target);
+        let targetStat;
+        try {
+            targetStat = fs.lstatSync(targetFull);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+            outcome("deleted");
+            continue;
+        }
+        if (!targetStat.isFile()) {
+            outcome("invalid", "current:not_a_file");
+            continue;
+        }
+        const currentContent = fs.readFileSync(targetFull, "utf8");
+        const current = parseEntityFile(currentContent);
+        const currentFields = current ? validateEntityFrontmatter(current.frontmatter) : "unparseable";
+        if (!current || typeof currentFields === "string") {
+            outcome("invalid", `current:${currentFields}`);
+            continue;
+        }
+        if (savedFields.id !== currentFields.id || savedFields.type !== currentFields.type) {
+            outcome("identity_conflict");
+            continue;
+        }
+        if (!isWritableEntityType(currentFields.type)) {
+            outcome("invalid", "current:type_not_checkpoint_owned");
+            continue;
+        }
+        const differences = unownedDifferences(saved, current);
+        const type = currentFields.type;
+        const aliases = index.byRel.has(backup.target)
+            ? freshAliases(index, type, backup.target, ownNames(index, backup.target, []), savedFields.aliases)
+            : [];
+        const withRefs = appendBackRefs(currentContent, readBackRefs(saved.body));
+        const currentUpdated = String(current.frontmatter.last_updated);
+        const lastUpdated = later(currentUpdated, savedUpdated);
+        const patched = patchEntityFile(withRefs.content, {
+            addAliases: aliases,
+            signalCount: savedFields.signal_count,
+            lastUpdated,
+            // A later timestamp alone is a change too; otherwise the merge result
+            // would depend on which version this machine holds.
+            bodyChanged: withRefs.added > 0 || lastUpdated !== currentUpdated,
+        });
+        if (!patched.ok) {
+            outcome("write_error", patched.reason);
+            continue;
+        }
+        if (patched.changed) {
+            // Outbox first: a file sync may push must never lack its entry, and a
+            // failed outbox write leaves the file and the backup for the next run.
+            try {
+                if (recordOutbox(hqRoot, company, [{ rel: backup.target, content: patched.content }], now).reset)
+                    run.outbox_reset = true;
+            }
+            catch (error) {
+                outcome("write_error", `outbox:${error.name}`);
+                continue;
+            }
+            try {
+                safeWriteFile(hqRoot, [entityRoot], targetFull, patched.content);
+            }
+            catch (error) {
+                outcome("write_error", error.name);
+                continue;
+            }
+            run.writes = run.writes.filter((write) => write.rel !== backup.target);
+            run.writes.push({ rel: backup.target, content: patched.content });
+            for (const alias of aliases)
+                indexAlias(index, type, backup.target, alias);
+            const entity = index.byRel.get(backup.target);
+            if (entity)
+                entity.aliases = [...entity.aliases, ...aliases];
+        }
+        if (differences.length > 0) {
+            outcome("kept_both", differences.join(","));
+            continue;
+        }
+        const mergedFull = path.join(hqRoot, ...MERGED_BACKUPS_DIR.split("/"), ...backup.hqRel.split("/").slice(CONFLICT_BACKUPS_DIR.split("/").length));
+        fs.mkdirSync(path.dirname(mergedFull), { recursive: true });
+        fs.renameSync(backup.full, mergedFull);
+        outcome("merged");
+    }
+    return run;
+}
+/** Groups of writable entities of one type whose names collide. Read-only. */
+export function findDuplicateGroups(index) {
+    const parent = new Map();
+    const find = (rel) => {
+        let root = rel;
+        while (parent.get(root) !== root)
+            root = parent.get(root);
+        parent.set(rel, root);
+        return root;
+    };
+    const union = (rels) => {
+        const list = [...rels].filter((rel) => isWritableEntityType(index.byRel.get(rel)?.type));
+        for (const rel of list)
+            if (!parent.has(rel))
+                parent.set(rel, rel);
+        for (const rel of list.slice(1)) {
+            const a = find(list[0]);
+            const b = find(rel);
+            if (a !== b)
+                parent.set(b, a);
+        }
+    };
+    // Only the matches `resolveCandidate` treats as one entity link files: equal
+    // canonical names, or a canonical name that is exactly one other file's
+    // alias. An alias several files share (a Slack id, "hq") is ambiguous, not
+    // a duplicate, and following it chains unrelated entities together.
+    const exactPairs = new Set();
+    const sameName = (rels) => {
+        if (rels.length < 2)
+            return;
+        union(rels);
+        for (const rel of rels)
+            exactPairs.add(rel);
+    };
+    const squashed = new Map();
+    for (const [name, rels] of index.canonical) {
+        const holders = index.alias.get(name);
+        const aliasHolder = holders && holders.size === 1 ? [...holders] : [];
+        sameName([...new Set([...rels, ...aliasHolder])]);
+        const [type, normalized] = name.split("\0");
+        const squashKey = entityKey(type, squash(normalized));
+        squashed.set(squashKey, [...(squashed.get(squashKey) ?? []), ...rels]);
+    }
+    // Canonical names that match once spaces and punctuation are removed.
+    for (const rels of squashed.values())
+        if (rels.length > 1)
+            union(rels);
+    const groups = new Map();
+    for (const rel of parent.keys()) {
+        const root = find(rel);
+        groups.set(root, [...(groups.get(root) ?? []), rel]);
+    }
+    const out = [];
+    for (const members of groups.values()) {
+        if (members.length < 2)
+            continue;
+        const paths = members.sort();
+        const ranked = [...paths].sort((a, b) => {
+            const ea = index.byRel.get(a);
+            const eb = index.byRel.get(b);
+            const fa = Date.parse(ea.first_seen ?? "");
+            const fb = Date.parse(eb.first_seen ?? "");
+            return (eb.signal_count - ea.signal_count ||
+                (Number.isFinite(fa) ? fa : Infinity) - (Number.isFinite(fb) ? fb : Infinity) ||
+                a.localeCompare(b));
+        });
+        out.push({
+            type: index.byRel.get(paths[0]).type,
+            reason: paths.filter((rel) => exactPairs.has(rel)).length >= 2 ? "same_name" : "similar_name",
+            paths,
+            survivor: ranked[0],
+        });
+    }
+    return out.sort((a, b) => b.paths.length - a.paths.length || a.paths[0].localeCompare(b.paths[0]));
+}
+/** The duplicate scan for a company, capped for the apply report. */
+export function scanDuplicates(company, limit = DUPLICATE_REPORT_LIMIT) {
+    const groups = findDuplicateGroups(buildEntityIndex(company.dir));
+    return { groups: groups.length, shown: groups.slice(0, limit) };
+}
+/**
+ * The start of a checkpoint run: merge back set-aside versions (each merged
+ * file is recorded in the outbox before it is written). Runs in `plan`, so a
+ * run with no changed inputs still merges. Errors are returned, not thrown,
+ * so the rest of the checkpoint goes on.
+ */
+export function startMultiWriterRun(hqRoot, company, now) {
+    let merged;
+    try {
+        merged = mergeBackConflicts(hqRoot, company, now);
+    }
+    catch (error) {
+        return { merge_back: [], error: `merge_back:${error.name}` };
+    }
+    return { merge_back: merged.outcomes, ...(merged.outbox_reset ? { outbox_reset: true } : {}) };
+}
+/** Count merge-back outcomes by result, for one-line summaries. */
+export function summarizeMergeBack(outcomes) {
+    const counts = new Map();
+    for (const outcome of outcomes)
+        counts.set(outcome.result, (counts.get(outcome.result) ?? 0) + 1);
+    return [...counts].sort(([a], [b]) => a.localeCompare(b)).map(([result, n]) => `${n} ${result.replaceAll("_", " ")}`).join(", ");
+}
+//# sourceMappingURL=multi-writer.js.map

package/dist/lib/checkpoint-ontology/plan.d.ts

@@ -9,6 +9,7 @@
  */
 import { type CompanyBriefResult } from "./company-brief.js";
 import { type OntologyCompany } from "./company.js";
+import { type MultiWriterStart } from "./multi-writer.js";
 export declare const ONTOLOGY_FLAG = "checkpoint.ontology";
 export declare const SHARED_INPUTS_FLAG = "checkpoint.ontology.shared-inputs";
 export declare const COMPANY_BRIEF_FLAG = "checkpoint.ontology.company-brief";
@@ -25,6 +26,12 @@ export declare const IGNORE_ANNOTATIONS_FLAG = "checkpoint.ontology.ignore-annot
  * state directory, so the foreground checkpoint makes no network call.
  */
 export declare const GROK_BACKEND_FLAG = "checkpoint.ontology.grok-backend";
+/**
+ * Several writers in one company vault (design section 20): record written
+ * entity bytes in the outbox, merge back set-aside versions, and report
+ * duplicate entities.
+ */
+export declare const MULTI_WRITER_FLAG = "checkpoint.ontology.multi-writer";
 export declare const PLAN_FILE = "ontology-plan.json";
 export declare const CANDIDATES_FILE = "ontology-candidates.json";
 export declare const REPORT_FILE = "ontology-report.json";
@@ -88,6 +95,8 @@ export interface OntologyPlan {
         status: CompanyBriefResult["status"];
         reason?: string;
     };
+    /** Present only when `checkpoint.ontology.multi-writer` was on for this plan. */
+    multi_writer?: MultiWriterStart;
     inputs: PlanInput[];
     /** The session's summary, decisions and learnings, for the `session` input. */
     session_text: string | null;
@@ -123,6 +132,7 @@ export type PlanOutcome = {
     status: "skipped";
     reason: string;
     companyBrief?: CompanyBriefResult;
+    multiWriter?: MultiWriterStart;
 } | {
     status: "planned";
     plan: OntologyPlan;

package/dist/lib/checkpoint-ontology/plan.js

@@ -12,6 +12,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { writeCompanyBrief } from "./company-brief.js";
 import { resolveOntologyCompany, safeWriteFile, stateRoot } from "./company.js";
+import { startMultiWriterRun } from "./multi-writer.js";
 import { buildEntityIndex, listKnowledgeFiles, listSignalFiles, readSignal } from "./tree.js";
 export const ONTOLOGY_FLAG = "checkpoint.ontology";
 export const SHARED_INPUTS_FLAG = "checkpoint.ontology.shared-inputs";
@@ -29,6 +30,12 @@ export const IGNORE_ANNOTATIONS_FLAG = "checkpoint.ontology.ignore-annotations";
  * state directory, so the foreground checkpoint makes no network call.
  */
 export const GROK_BACKEND_FLAG = "checkpoint.ontology.grok-backend";
+/**
+ * Several writers in one company vault (design section 20): record written
+ * entity bytes in the outbox, merge back set-aside versions, and report
+ * duplicate entities.
+ */
+export const MULTI_WRITER_FLAG = "checkpoint.ontology.multi-writer";
 export const PLAN_FILE = "ontology-plan.json";
 export const CANDIDATES_FILE = "ontology-candidates.json";
 export const REPORT_FILE = "ontology-report.json";
@@ -212,14 +219,19 @@ export async function planOntologyRun(options) {
         return { status: "skipped", reason: "flag off" };
     }
     const sharedInputs = await options.readFlag(SHARED_INPUTS_FLAG, company);
-    // Before the ledger, so a nothing-changed plan still records the brief.
-    const companyBrief = (await options.readFlag(COMPANY_BRIEF_FLAG, company))
-        ? writeCompanyBrief(hqRoot, company, options.now ?? new Date())
-        : undefined;
+    const briefOn = await options.readFlag(COMPANY_BRIEF_FLAG, company);
     const ignoreAnnotations = (await options.readFlag(IGNORE_ANNOTATIONS_FLAG, company)) && payload.backend === "grok";
     recordBackendPreference(hqRoot, company, await options.readFlag(GROK_BACKEND_FLAG, company));
+    const multiWriterOn = await options.readFlag(MULTI_WRITER_FLAG, company);
     const touched = sessionTouched(hqRoot, company, payload.files);
+    // A first run takes its boundary from the entity tree, so the ledger is
+    // refreshed before merge-back moves any `last_updated` forward.
     const { ledger, firstRun } = refreshLedger(company, readLedger(hqRoot, company), touched, sharedInputs);
+    // Merge-back and the brief come before the nothing-changed return, so such
+    // a plan still merges set-aside versions and records the brief; the brief
+    // follows merge-back so its counts include merged entities.
+    const multiWriter = multiWriterOn ? startMultiWriterRun(hqRoot, company, options.now ?? new Date()) : undefined;
+    const companyBrief = briefOn ? writeCompanyBrief(hqRoot, company, options.now ?? new Date()) : undefined;
     const pending = Object.entries(ledger.entries)
         .filter(([, entry]) => entry.state === "pending" && (sharedInputs || entry.reason === "session-touched"))
         .sort(([aRel, a], [bRel, b]) => reasonRank(a.reason) - reasonRank(b.reason) || a.mtime_ms - b.mtime_ms || aRel.localeCompare(bRel));
@@ -268,7 +280,12 @@ export async function planOntologyRun(options) {
     writeLedger(hqRoot, company, ledger);
     if (inputs.length === 0) {
         const reason = pending.length > 0 ? "over budget" : "nothing changed";
-        return companyBrief ? { status: "skipped", reason, companyBrief } : { status: "skipped", reason };
+        return {
+            status: "skipped",
+            reason,
+            ...(companyBrief ? { companyBrief } : {}),
+            ...(multiWriter ? { multiWriter } : {}),
+        };
     }
     // Session content is scoped to the session's user (design section 6, D2).
     // v1 records the existing entities it names as links in the report and
@@ -304,6 +321,7 @@ export async function planOntologyRun(options) {
                     : { status: companyBrief.status },
             }
             : {}),
+        ...(multiWriter ? { multi_writer: multiWriter } : {}),
         inputs,
         session_text: sessionText,
         pending_after_run: remaining,

package/dist/lib/checkpoint-ontology/tree.d.ts

@@ -9,6 +9,8 @@ export interface IndexedEntity extends EntityFields {
     rel: string;
     slug: string;
     last_updated: string | null;
+    /** Absent for an entity created in this run before it was re-read. */
+    first_seen?: string | null;
 }
 export interface EntityIndex {
     byRel: Map<string, IndexedEntity>;

package/dist/lib/checkpoint-ontology/tree.js

@@ -78,12 +78,13 @@ export function buildEntityIndex(companyDir) {
                 index.invalid.add(rel);
                 continue;
             }
-            const lastUpdated = parsed.frontmatter.last_updated;
+            const { last_updated: lastUpdated, first_seen: firstSeen } = parsed.frontmatter;
             indexEntity(index, {
                 ...fields,
                 rel,
                 slug: file.name.slice(0, -3),
                 last_updated: typeof lastUpdated === "string" ? lastUpdated : null,
+                first_seen: typeof firstSeen === "string" ? firstSeen : null,
             });
         }
     }

package/dist/lib/lanes/timestamp.d.ts

@@ -0,0 +1,3 @@
+/** Parse an extended ISO timestamp and return JavaScript's canonical UTC form. */
+export declare function normalizeIsoTimestamp(value: unknown): string | null;
+//# sourceMappingURL=timestamp.d.ts.map

package/dist/lib/lanes/timestamp.js

@@ -0,0 +1,26 @@
+/** Parse an extended ISO timestamp and return JavaScript's canonical UTC form. */
+export function normalizeIsoTimestamp(value) {
+    if (typeof value !== "string")
+        return null;
+    const match = /^(\d{4})-(\d\d)-(\d\d)T(\d\d):(\d\d):(\d\d)(?:\.(\d+))?(Z|([+-])(\d\d):(\d\d))$/.exec(value);
+    if (!match)
+        return null;
+    const year = Number(match[1]);
+    const month = Number(match[2]);
+    const day = Number(match[3]);
+    const hour = Number(match[4]);
+    const minute = Number(match[5]);
+    const second = Number(match[6]);
+    const offsetHour = match[9] === undefined ? 0 : Number(match[10]);
+    const offsetMinute = match[9] === undefined ? 0 : Number(match[11]);
+    const leapYear = year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0);
+    const daysInMonth = [31, leapYear ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31][month - 1];
+    if (month < 1 || month > 12 || day < 1 || daysInMonth === undefined || day > daysInMonth ||
+        hour > 23 || minute > 59 || second > 59 || offsetHour > 23 || offsetMinute > 59)
+        return null;
+    const parsed = Date.parse(value);
+    if (!Number.isFinite(parsed))
+        return null;
+    return new Date(parsed).toISOString();
+}
+//# sourceMappingURL=timestamp.js.map

package/dist/lib/lanes/tracker-report-state.d.ts

@@ -0,0 +1,10 @@
+export declare const FIRST_TRACKER_REPORT_SINCE = "1970-01-01T00:00:00.000Z";
+export interface TrackerReportState {
+    schema_version: "hq-lanes-report-state.v1";
+    company: string;
+    last_report_at: string;
+}
+export declare function trackerReportStatePath(root: string, company: string): string;
+export declare function readTrackerReportState(root: string, company: string): TrackerReportState | null;
+export declare function writeTrackerReportState(root: string, company: string, at: string): TrackerReportState;
+//# sourceMappingURL=tracker-report-state.d.ts.map