@aligndottech/cli 0.48.0 → 0.50.0

package/dist/lib/sync/threads.d.ts

@@ -0,0 +1,48 @@
+/**
+ * L5: the thread side of a sync - which stored Slack threads to ask the SDK to re-read (a reply to
+ * an old thread never shows up in a date-ordered channel listing), and how a re-read that holds
+ * only the NEW messages is folded into the stored thread.
+ *
+ * Pure. The SDK marks such an item `partial: true`; Review addendum 3 binds this file: a partial
+ * item is merged into the stored row and never replaces it.
+ */
+/** A thread with a reply inside this many days is re-read by every run. */
+export declare const HOT_THREAD_DAYS = 30;
+/** Each re-read costs a vendor request, so a run reads at most this many; newest activity first. */
+export declare const HOT_THREAD_LIMIT = 100;
+/** The channel id and thread-root ts out of the URL connector-core writes for a thread. */
+export declare function parseSlackPermalink(url: string): {
+    channel: string;
+    ts: string;
+} | undefined;
+export interface HotSelection {
+    hot: Array<{
+        channel: string;
+        ts: string;
+    }>;
+    /** Threads held with no reply inside the window. The report names this limit once. */
+    quiet: number;
+    /** Threads that were hot but did not fit under the per-run limit. */
+    capped: number;
+}
+export declare function selectHotThreads(rows: ReadonlyArray<{
+    source_url: string;
+    last_activity: string | null;
+}>, now: Date, o?: {
+    limit?: number;
+}): HotSelection;
+/**
+ * The stored thread plus whatever the partial read holds that it does not. The SDK's text is the
+ * thread's messages joined by newlines with no timestamps, so "already there" can only be judged
+ * by comparing runs of lines:
+ * 1. the longest tail of the stored thread that the partial also holds contiguously: everything
+ *    after that run in the partial is new;
+ * 2. else the partial wholly inside the stored thread: nothing is new;
+ * 3. else drop the partial's leading lines that repeat the stored thread's opening (the root,
+ *    which Slack returns again) and append the rest.
+ * A message that repeats an earlier line word for word (an "ok") is the one thing this cannot
+ * tell from an overlap; the longest-run rule makes that need a run, not one line, to confuse it.
+ * The stored text is never altered, so a merge can only add.
+ */
+export declare function mergePartialThread(stored: string, partial: string): string;
+//# sourceMappingURL=threads.d.ts.map

package/dist/lib/sync/threads.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"threads.d.ts","sourceRoot":"","sources":["../../../src/lib/sync/threads.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,2EAA2E;AAC3E,eAAO,MAAM,eAAe,KAAK,CAAC;AAClC,oGAAoG;AACpG,eAAO,MAAM,gBAAgB,MAAM,CAAC;AAGpC,2FAA2F;AAC3F,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAG5F;AAED,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,KAAK,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC5C,sFAAsF;IACtF,KAAK,EAAE,MAAM,CAAC;IACd,qEAAqE;IACrE,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,aAAa,CAAC;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC,EACzE,GAAG,EAAE,IAAI,EACT,CAAC,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GACzB,YAAY,CAed;AAcD;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAY1E"}

package/dist/lib/sync/threads.js

@@ -0,0 +1,82 @@
+/**
+ * L5: the thread side of a sync - which stored Slack threads to ask the SDK to re-read (a reply to
+ * an old thread never shows up in a date-ordered channel listing), and how a re-read that holds
+ * only the NEW messages is folded into the stored thread.
+ *
+ * Pure. The SDK marks such an item `partial: true`; Review addendum 3 binds this file: a partial
+ * item is merged into the stored row and never replaces it.
+ */
+/** A thread with a reply inside this many days is re-read by every run. */
+export const HOT_THREAD_DAYS = 30;
+/** Each re-read costs a vendor request, so a run reads at most this many; newest activity first. */
+export const HOT_THREAD_LIMIT = 100;
+const DAY_MS = 86_400_000;
+/** The channel id and thread-root ts out of the URL connector-core writes for a thread. */
+export function parseSlackPermalink(url) {
+    const m = /^https:\/\/slack\.com\/archives\/([A-Z0-9]+)\/p(\d{10})(\d{6})$/.exec(url);
+    return m ? { channel: m[1], ts: `${m[2]}.${m[3]}` } : undefined;
+}
+export function selectHotThreads(rows, now, o = {}) {
+    const cutoff = now.getTime() - HOT_THREAD_DAYS * DAY_MS;
+    const hot = [];
+    let quiet = 0;
+    for (const row of rows) {
+        const thread = parseSlackPermalink(row.source_url);
+        if (thread === undefined)
+            continue;
+        const at = row.last_activity === null ? Number.NaN : Date.parse(row.last_activity);
+        // NaN (no activity recorded, or a stamp nobody can read) is quiet, not hot: a hot thread costs a request.
+        if (Number.isNaN(at) || at < cutoff)
+            quiet += 1;
+        else
+            hot.push({ ...thread, at });
+    }
+    hot.sort((a, b) => b.at - a.at);
+    const limit = o.limit ?? HOT_THREAD_LIMIT;
+    return { hot: hot.slice(0, limit).map(({ channel, ts }) => ({ channel, ts })), quiet, capped: Math.max(0, hot.length - limit) };
+}
+const HEADER = /^\[#[^\]\n]*\] Thread:$/;
+function bodyLines(text) {
+    const all = text.split('\n');
+    return HEADER.test(all[0] ?? '') ? { header: all[0], lines: all.slice(1) } : { header: undefined, lines: all };
+}
+function sameRun(a, aAt, b, bAt, n) {
+    for (let i = 0; i < n; i++)
+        if (a[aAt + i] !== b[bAt + i])
+            return false;
+    return true;
+}
+/**
+ * The stored thread plus whatever the partial read holds that it does not. The SDK's text is the
+ * thread's messages joined by newlines with no timestamps, so "already there" can only be judged
+ * by comparing runs of lines:
+ * 1. the longest tail of the stored thread that the partial also holds contiguously: everything
+ *    after that run in the partial is new;
+ * 2. else the partial wholly inside the stored thread: nothing is new;
+ * 3. else drop the partial's leading lines that repeat the stored thread's opening (the root,
+ *    which Slack returns again) and append the rest.
+ * A message that repeats an earlier line word for word (an "ok") is the one thing this cannot
+ * tell from an overlap; the longest-run rule makes that need a run, not one line, to confuse it.
+ * The stored text is never altered, so a merge can only add.
+ */
+export function mergePartialThread(stored, partial) {
+    const s = bodyLines(stored).lines;
+    const p = bodyLines(partial).lines;
+    for (let k = Math.min(s.length, p.length); k >= 1; k--) {
+        for (let j = 0; j + k <= p.length; j++) {
+            if (sameRun(s, s.length - k, p, j, k))
+                return append(stored, p.slice(j + k));
+        }
+    }
+    for (let at = 0; at + p.length <= s.length; at++)
+        if (p.length > 0 && sameRun(s, at, p, 0, p.length))
+            return stored;
+    let head = 0;
+    while (head < p.length && head < s.length && p[head] === s[head])
+        head++;
+    return append(stored, p.slice(head));
+}
+function append(stored, added) {
+    return added.length === 0 ? stored : `${stored}\n${added.join('\n')}`;
+}
+//# sourceMappingURL=threads.js.map

package/dist/lib/sync/threads.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"threads.js","sourceRoot":"","sources":["../../../src/lib/sync/threads.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,2EAA2E;AAC3E,MAAM,CAAC,MAAM,eAAe,GAAG,EAAE,CAAC;AAClC,oGAAoG;AACpG,MAAM,CAAC,MAAM,gBAAgB,GAAG,GAAG,CAAC;AACpC,MAAM,MAAM,GAAG,UAAU,CAAC;AAE1B,2FAA2F;AAC3F,MAAM,UAAU,mBAAmB,CAAC,GAAW;IAC7C,MAAM,CAAC,GAAG,iEAAiE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACtF,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,CAAE,EAAE,EAAE,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;AACnE,CAAC;AAUD,MAAM,UAAU,gBAAgB,CAC9B,IAAyE,EACzE,GAAS,EACT,IAAwB,EAAE;IAE1B,MAAM,MAAM,GAAG,GAAG,CAAC,OAAO,EAAE,GAAG,eAAe,GAAG,MAAM,CAAC;IACxD,MAAM,GAAG,GAAuD,EAAE,CAAC;IACnE,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,MAAM,MAAM,GAAG,mBAAmB,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;QACnD,IAAI,MAAM,KAAK,SAAS;YAAE,SAAS;QACnC,MAAM,EAAE,GAAG,GAAG,CAAC,aAAa,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;QACnF,0GAA0G;QAC1G,IAAI,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,GAAG,MAAM;YAAE,KAAK,IAAI,CAAC,CAAC;;YAC3C,GAAG,CAAC,IAAI,CAAC,EAAE,GAAG,MAAM,EAAE,EAAE,EAAE,CAAC,CAAC;IACnC,CAAC;IACD,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC;IAChC,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,IAAI,gBAAgB,CAAC;IAC1C,OAAO,EAAE,GAAG,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,CAAC,MAAM,GAAG,KAAK,CAAC,EAAE,CAAC;AAClI,CAAC;AAED,MAAM,MAAM,GAAG,yBAAyB,CAAC;AAEzC,SAAS,SAAS,CAAC,IAAY;IAC7B,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC7B,OAAO,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC;AACjH,CAAC;AAED,SAAS,OAAO,CAAC,CAAoB,EAAE,GAAW,EAAE,CAAoB,EAAE,GAAW,EAAE,CAAS;IAC9F,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE;QAAE,IAAI,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC;YAAE,OAAO,KAAK,CAAC;IACxE,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAAc,EAAE,OAAe;IAChE,MAAM,CAAC,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC;IAClC,MAAM,CAAC,GAAG,SAAS,CAAC,OAAO,CAAC,CAAC,KAAK,CAAC;IACnC,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QACvD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACvC,IAAI,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;gBAAE,OAAO,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QAC/E,CAAC;IACH,CAAC;IACD,KAAK,IAAI,EAAE,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,EAAE;QAAE,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,IAAI,OAAO,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,MAAM,CAAC;YAAE,OAAO,MAAM,CAAC;IACpH,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,OAAO,IAAI,GAAG,CAAC,CAAC,MAAM,IAAI,IAAI,GAAG,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC;QAAE,IAAI,EAAE,CAAC;IACzE,OAAO,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;AACvC,CAAC;AAED,SAAS,MAAM,CAAC,MAAc,EAAE,KAAwB;IACtD,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,MAAM,KAAK,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;AACxE,CAAC"}

package/dist/lib/sync/window.d.ts

@@ -0,0 +1,72 @@
+/** Each run reads from a day before the watermark, so an item edited between two runs while the
+ *  vendor was behind on its own indexing is not missed. */
+export declare const OVERLAP_DAYS = 1;
+/** A hole that ended this many consecutive runs the same way is called persistent. */
+export declare const PERSISTENT_HOLE_RUNS = 5;
+/** The slice of a `source_sync` row the next-window decision reads. */
+export interface WindowState {
+    /** Lower bound the user asked for. `null` on an EXISTING row means "all" (L3's record of `since: all`). */
+    window_since: string | null;
+    high_water: string | null;
+    pending_until: string | null;
+    /** Consecutive runs that ended on the same hole. While it is above zero the re-read is bounded (see nextWindow). */
+    hole_streak?: number;
+}
+/**
+ * The window a NEW scope row starts with: the one the person asked for on this source, which is the `yours` row's (L3 records
+ * `since: all` as NULL there, and "all" stays all). A source with no `yours` row yet starts at the default window.
+ * The one writer: the sync's first run on a scope and a scope change from `align connect` or `align_scope` both call it.
+ */
+export declare function inheritedWindowSince(rows: ReadonlyArray<{
+    scope_key: string;
+    window_since: string | null;
+}>, now: Date): string | null;
+export declare function minusDays(iso: string, days: number): string;
+/**
+ * What the next run asks the vendor for.
+ * - No row: the default window back from now (the first sync of a source).
+ * - A high_water: one overlap day before it. Otherwise the row's own window_since, untouched.
+ * - A pending_until: also an `until` there, so a run that a ceiling cut finishes the OLDER part.
+ * An unparseable stored stamp reads as absent, which can only widen the read.
+ */
+export declare function nextWindow(s: WindowState | undefined, now: Date): {
+    since?: string;
+    until?: string;
+};
+export interface RunFinish {
+    complete: boolean;
+    /**
+     * Incomplete BECAUSE the listing was cut in date order (a vendor ceiling, an item ceiling or a
+     * time budget on a newest-first listing): everything newer than `oldestReached` was read, so the
+     * next run can finish the older part with `until`. Any other incompleteness is a HOLE (a channel
+     * that would not open, a refused repo, a thread read that hit its page cap): no date line
+     * separates read from unread, so no `until` is set and the next run re-reads from the watermark.
+     */
+    cut?: boolean;
+    /** This hole has now come back often enough (see PERSISTENT_HOLE_RUNS) that the watermark stops waiting for it. */
+    persistent?: boolean;
+    highWater?: string;
+    oldestReached?: string;
+    /** The newest `updated_at` stored for this source across the whole cycle, for the final run of
+     *  a pending cycle: its own highWater is clamped to `until` and would pull the mark back. */
+    cycleNewest?: string;
+    /** When given, a stamp more than a day AFTER it is ignored: a watermark in the future would
+     *  hide every later change from every later run. */
+    now?: Date;
+}
+export declare function later(a: string | null | undefined, b: string | null | undefined): string | null;
+export declare function plausible(iso: string | undefined, now: Date | undefined): string | undefined;
+export declare function finishRun(prev: Pick<WindowState, 'high_water' | 'pending_until'>, r: RunFinish): {
+    high_water: string | null;
+    pending_until: string | null;
+    status: 'ok' | 'partial';
+};
+/** Oldest first. A kill after batch N then leaves every older item committed, so a watermark equal
+ *  to the newest committed stamp never sits above an unread one. Items with no stamp lead. */
+export declare function ascendingByUpdated<T extends {
+    updated_at?: string;
+}>(items: readonly T[]): T[];
+export declare function newestUpdated(items: ReadonlyArray<{
+    updated_at?: string;
+}>, now?: Date): string | undefined;
+//# sourceMappingURL=window.d.ts.map

package/dist/lib/sync/window.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"window.d.ts","sourceRoot":"","sources":["../../../src/lib/sync/window.ts"],"names":[],"mappings":"AAWA;2DAC2D;AAC3D,eAAO,MAAM,YAAY,IAAI,CAAC;AAC9B,sFAAsF;AACtF,eAAO,MAAM,oBAAoB,IAAI,CAAC;AAGtC,uEAAuE;AACvE,MAAM,WAAW,WAAW;IAC1B,2GAA2G;IAC3G,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,oHAAoH;IACpH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AASD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,aAAa,CAAC;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC,EAAE,GAAG,EAAE,IAAI,GAAG,MAAM,GAAG,IAAI,CAGtI;AAED,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAI3D;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,WAAW,GAAG,SAAS,EAAE,GAAG,EAAE,IAAI,GAAG;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAYpG;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,OAAO,CAAC;IAClB;;;;;;OAMG;IACH,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,mHAAmH;IACnH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;iGAC6F;IAC7F,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;wDACoD;IACpD,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ;AAED,wBAAgB,KAAK,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAM/F;AAUD,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,EAAE,GAAG,EAAE,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAI5F;AAED,wBAAgB,SAAS,CACvB,IAAI,EAAE,IAAI,CAAC,WAAW,EAAE,YAAY,GAAG,eAAe,CAAC,EACvD,CAAC,EAAE,SAAS,GACX;IAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,MAAM,EAAE,IAAI,GAAG,SAAS,CAAA;CAAE,CAWvF;AAED;8FAC8F;AAC9F,wBAAgB,kBAAkB,CAAC,CAAC,SAAS;IAAE,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,GAAG,CAAC,EAAE,CAK9F;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,aAAa,CAAC;IAAE,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,EAAE,GAAG,CAAC,EAAE,IAAI,GAAG,MAAM,GAAG,SAAS,CAI3G"}

package/dist/lib/sync/window.js

@@ -0,0 +1,112 @@
+/**
+ * L5: the pure decisions of an incremental sync - which window to read next and where the
+ * watermark stands after a run. No database, no clock of its own, no network.
+ *
+ * The watermark is the vendor's own `updated_at` (Decision 4), taken from the SDK's report, and
+ * it moves only on a COMPLETE read that carried one. Anything else leaves it where it was: a
+ * watermark that moved past data nobody read loses that data for good, while one that stays put
+ * costs a re-read the unchanged-skip makes cheap.
+ */
+import { SYNC_WINDOW_DEFAULT_DAYS } from '../import-defaults.js';
+/** Each run reads from a day before the watermark, so an item edited between two runs while the
+ *  vendor was behind on its own indexing is not missed. */
+export const OVERLAP_DAYS = 1;
+/** A hole that ended this many consecutive runs the same way is called persistent. */
+export const PERSISTENT_HOLE_RUNS = 5;
+const DAY_MS = 86_400_000;
+function parse(iso) {
+    if (iso === null || iso === undefined)
+        return undefined;
+    const ms = Date.parse(iso);
+    // NaN compares false with everything, in both directions (verification.md): refuse it here.
+    return Number.isNaN(ms) ? undefined : ms;
+}
+/**
+ * The window a NEW scope row starts with: the one the person asked for on this source, which is the `yours` row's (L3 records
+ * `since: all` as NULL there, and "all" stays all). A source with no `yours` row yet starts at the default window.
+ * The one writer: the sync's first run on a scope and a scope change from `align connect` or `align_scope` both call it.
+ */
+export function inheritedWindowSince(rows, now) {
+    const yours = rows.find((r) => r.scope_key === 'yours');
+    return yours ? yours.window_since : nextWindow(undefined, now).since;
+}
+export function minusDays(iso, days) {
+    const ms = parse(iso);
+    if (ms === undefined)
+        throw new Error(`Cannot read "${iso.slice(0, 40)}" as a date.`);
+    return new Date(ms - days * DAY_MS).toISOString();
+}
+/**
+ * What the next run asks the vendor for.
+ * - No row: the default window back from now (the first sync of a source).
+ * - A high_water: one overlap day before it. Otherwise the row's own window_since, untouched.
+ * - A pending_until: also an `until` there, so a run that a ceiling cut finishes the OLDER part.
+ * An unparseable stored stamp reads as absent, which can only widen the read.
+ */
+export function nextWindow(s, now) {
+    if (s === undefined)
+        return { since: new Date(now.getTime() - SYNC_WINDOW_DEFAULT_DAYS * DAY_MS).toISOString() };
+    // A stored watermark from the future (written by an older build, or by a clock that was wrong) is
+    // repaired by ignoring it: the read widens to the window, and the run's own result replaces it.
+    const hw = plausible(s.high_water ?? undefined, now) === undefined ? undefined : s.high_water;
+    const floor = hw !== undefined ? minusDays(hw, OVERLAP_DAYS) : parse(s.window_since) === undefined ? undefined : s.window_since;
+    const until = parse(s.pending_until) === undefined ? undefined : s.pending_until;
+    // A hole that keeps coming back keeps the watermark where it was, so the re-read would grow every day, and a source that
+    // reads more each time is more likely to hit its budget again. Bound it to the default window while a hole is open.
+    const bound = (s.hole_streak ?? 0) > 0 ? new Date(now.getTime() - SYNC_WINDOW_DEFAULT_DAYS * DAY_MS).toISOString() : undefined;
+    const since = bound !== undefined && (floor === undefined || Date.parse(floor) < Date.parse(bound)) ? bound : floor;
+    return { ...(since !== undefined ? { since } : {}), ...(until !== undefined ? { until } : {}) };
+}
+export function later(a, b) {
+    const pa = parse(a);
+    const pb = parse(b);
+    if (pa === undefined)
+        return pb === undefined ? null : b;
+    if (pb === undefined)
+        return a;
+    return pb > pa ? b : a;
+}
+function earlier(a, b) {
+    const pa = parse(a);
+    const pb = parse(b);
+    if (pa === undefined)
+        return pb === undefined ? null : b;
+    if (pb === undefined)
+        return a;
+    return pb < pa ? b : a;
+}
+export function plausible(iso, now) {
+    const t = parse(iso);
+    if (t === undefined)
+        return undefined;
+    return now !== undefined && t > now.getTime() + DAY_MS ? undefined : iso;
+}
+export function finishRun(prev, r) {
+    const prevHigh = plausible(prev.high_water ?? undefined, r.now) === undefined ? null : prev.high_water;
+    if (r.complete) {
+        return { high_water: later(later(prevHigh, plausible(r.highWater, r.now)), plausible(r.cycleNewest, r.now)), pending_until: null, status: 'ok' };
+    }
+    if (r.persistent === true) {
+        // The other streams are read and committed; only the hole is not. Say so in the status, and move on.
+        return { high_water: later(later(prevHigh, plausible(r.highWater, r.now)), plausible(r.cycleNewest, r.now)), pending_until: null, status: 'partial' };
+    }
+    if (r.cut === true)
+        return { high_water: prevHigh, pending_until: earlier(prev.pending_until, r.oldestReached), status: 'partial' };
+    return { high_water: prevHigh, pending_until: null, status: 'partial' };
+}
+/** Oldest first. A kill after batch N then leaves every older item committed, so a watermark equal
+ *  to the newest committed stamp never sits above an unread one. Items with no stamp lead. */
+export function ascendingByUpdated(items) {
+    const stamp = (i) => parse(i.updated_at) ?? Number.NEGATIVE_INFINITY;
+    return items.map((item, index) => ({ item, index }))
+        .sort((a, b) => (stamp(a.item) - stamp(b.item) || a.index - b.index) || 0)
+        .map((e) => e.item);
+}
+export function newestUpdated(items, now) {
+    let best;
+    for (const i of items)
+        if (plausible(i.updated_at, now) !== undefined)
+            best = later(best, i.updated_at) ?? best;
+    return best;
+}
+//# sourceMappingURL=window.js.map

package/dist/lib/sync/window.js.map

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

package/dist/lib/team-cta.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The one upgrade line the CLI prints, only at the share moment (a team action tried with no team
+ * login). One place for the booking link: the CLI links to a redirect Align owns, so routing the
+ * call to someone else later is a site change and needs no CLI release (plan 2026-10-09, Open
+ * Question 1). Flip TEAM_SIGNUP_OPEN when prod team signup opens.
+ */
+export declare const BOOK_CALL_URL = "https://align.tech/demo?ref=cli";
+export declare const TEAM_SIGNUP_URL = "https://app.align.tech/signup";
+export declare const TEAM_SIGNUP_OPEN = false;
+export declare function teamCtaLine(open?: boolean): string;
+//# sourceMappingURL=team-cta.d.ts.map

package/dist/lib/team-cta.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"team-cta.d.ts","sourceRoot":"","sources":["../../src/lib/team-cta.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAO,MAAM,aAAa,oCAAoC,CAAC;AAC/D,eAAO,MAAM,eAAe,kCAAkC,CAAC;AAC/D,eAAO,MAAM,gBAAgB,QAAQ,CAAC;AAEtC,wBAAgB,WAAW,CAAC,IAAI,GAAE,OAA0B,GAAG,MAAM,CAIpE"}

package/dist/lib/team-cta.js

@@ -0,0 +1,16 @@
+/**
+ * The one upgrade line the CLI prints, only at the share moment (a team action tried with no team
+ * login). One place for the booking link: the CLI links to a redirect Align owns, so routing the
+ * call to someone else later is a site change and needs no CLI release (plan 2026-10-09, Open
+ * Question 1). Flip TEAM_SIGNUP_OPEN when prod team signup opens.
+ */
+// Confirmed by Tom 2026-10-10: align.tech/demo?ref=cli redirects to the 30-minute booking page.
+export const BOOK_CALL_URL = 'https://align.tech/demo?ref=cli';
+export const TEAM_SIGNUP_URL = 'https://app.align.tech/signup';
+export const TEAM_SIGNUP_OPEN = false;
+export function teamCtaLine(open = TEAM_SIGNUP_OPEN) {
+    return open
+        ? `Start a team graph: ${TEAM_SIGNUP_URL}`
+        : `Bring this to your team. Book a 30-minute call: ${BOOK_CALL_URL}`;
+}
+//# sourceMappingURL=team-cta.js.map

package/dist/lib/team-cta.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"team-cta.js","sourceRoot":"","sources":["../../src/lib/team-cta.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,gGAAgG;AAChG,MAAM,CAAC,MAAM,aAAa,GAAG,iCAAiC,CAAC;AAC/D,MAAM,CAAC,MAAM,eAAe,GAAG,+BAA+B,CAAC;AAC/D,MAAM,CAAC,MAAM,gBAAgB,GAAG,KAAK,CAAC;AAEtC,MAAM,UAAU,WAAW,CAAC,OAAgB,gBAAgB;IAC1D,OAAO,IAAI;QACT,CAAC,CAAC,uBAAuB,eAAe,EAAE;QAC1C,CAAC,CAAC,mDAAmD,aAAa,EAAE,CAAC;AACzE,CAAC"}

package/dist/lib/telemetry-ci.d.ts

@@ -0,0 +1,2 @@
+export declare function inCi(env?: Record<string, string | undefined>): boolean;
+//# sourceMappingURL=telemetry-ci.d.ts.map

package/dist/lib/telemetry-ci.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry-ci.d.ts","sourceRoot":"","sources":["../../src/lib/telemetry-ci.ts"],"names":[],"mappings":"AAiCA,wBAAgB,IAAI,CAAC,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,GAAG,OAAO,CAInF"}

package/dist/lib/telemetry-ci.js

@@ -0,0 +1,21 @@
+import vendors from 'ci-info/vendors.json' with { type: 'json' };
+/** ci-info's generic flags, in its own order: any one of them set means CI. */
+const GENERIC = ['BUILD_ID', 'BUILD_NUMBER', 'CI', 'CI_APP_ID', 'CI_BUILD_ID', 'CI_BUILD_NUMBER', 'CI_NAME', 'CONTINUOUS_INTEGRATION', 'RUN_ID'];
+function matches(rule, env) {
+    if (typeof rule === 'string')
+        return Boolean(env[rule]);
+    if ('env' in rule && typeof rule.env === 'string' && 'includes' in rule) {
+        return Boolean(env[rule.env]?.includes(String(rule.includes)));
+    }
+    if ('any' in rule && Array.isArray(rule.any))
+        return rule.any.some((k) => Boolean(env[k]));
+    return Object.entries(rule).every(([k, v]) => env[k] === v);
+}
+export function inCi(env = process.env) {
+    if (env['CI'] === 'false')
+        return false;
+    if (GENERIC.some((k) => Boolean(env[k])))
+        return true;
+    return vendors.some((v) => (Array.isArray(v.env) ? v.env : [v.env]).every((r) => matches(r, env)));
+}
+//# sourceMappingURL=telemetry-ci.js.map

package/dist/lib/telemetry-ci.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry-ci.js","sourceRoot":"","sources":["../../src/lib/telemetry-ci.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,MAAM,sBAAsB,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAC;AAqBjE,+EAA+E;AAC/E,MAAM,OAAO,GAAG,CAAC,UAAU,EAAE,cAAc,EAAE,IAAI,EAAE,WAAW,EAAE,aAAa,EAAE,iBAAiB,EAAE,SAAS,EAAE,wBAAwB,EAAE,QAAQ,CAAC,CAAC;AAEjJ,SAAS,OAAO,CAAC,IAAa,EAAE,GAAuC;IACrE,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,OAAO,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;IACxD,IAAI,KAAK,IAAI,IAAI,IAAI,OAAO,IAAI,CAAC,GAAG,KAAK,QAAQ,IAAI,UAAU,IAAI,IAAI,EAAE,CAAC;QACxE,OAAO,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;IACjE,CAAC;IACD,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC3F,OAAO,MAAM,CAAC,OAAO,CAAC,IAA8B,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;AACxF,CAAC;AAED,MAAM,UAAU,IAAI,CAAC,MAA0C,OAAO,CAAC,GAAG;IACxE,IAAI,GAAG,CAAC,IAAI,CAAC,KAAK,OAAO;QAAE,OAAO,KAAK,CAAC;IACxC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IACtD,OAAQ,OAAoB,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC;AACnH,CAAC"}

package/dist/lib/telemetry-consent.d.ts

@@ -1,32 +1,53 @@
+import type { TelemetryConsent } from './config.js';
 /**
  * Narrow interface rather than the whole config store, so this module (and its tests) does not
  * carry every unrelated accessor `createConfigStore()` exposes.
  */
-export interface TelemetryConsentStore {
-    getTelemetryConsent(): 'granted' | 'declined' | 'off' | undefined;
-    setTelemetryConsent(value: 'granted' | 'declined' | 'off'): void;
+export interface TelemetryNoticeStore {
+    getTelemetryConsent(): TelemetryConsent | undefined;
+    getTelemetryNoticeShownAt(): string | undefined;
+    markTelemetryNoticeShown(): void;
 }
 /**
- * ALI-618 D3: the one-time local-mode consent prompt, shown from `runLocalSetup()`.
- *
- * Never asks twice - a decision already on disk (granted, declined, or `align telemetry off`)
- * is left alone. Never prompts without a TTY on both streams: a piped `setup --local` run
- * hangs on a prompt it cannot answer, and a closed stdin crashes clack's raw-mode init AFTER
- * the real setup work has already succeeded (the align-cli#118 lesson,
- * `setup-local-non-tty.test.ts`). A non-interactive run leaves consent UNSET rather than
- * implicitly declined - a scripted first run may be a CI smoke test, not a real user's choice,
- * and it can still be asked on a later interactive run.
- *
- * ALI-954: an env var that already turns everything off (`DO_NOT_TRACK=1`, `ALIGN_TELEMETRY=0`)
- * skips the question with a one-line note - asking would imply the answer matters - and
- * leaves the decision unset for the same reason as the non-interactive case.
- *
- * The question is about USAGE (which commands you run). The two anonymous counts the docs
- * describe (install, setup completed) are not what is being asked about here and send either
- * way; `align telemetry off` is what stops those (docs/telemetry.md).
+ * C6: the disclosure. Local-mode telemetry is opt-out, and this notice is what makes it so: it
+ * prints once, to stderr, before anything is sent, and nothing that depends on it sends until
+ * it has printed (usage-telemetry.ts's localTierAllows). The founder-approved wording - change
+ * it only with the privacy page (align.tech/privacy#cli) and docs/telemetry.md in the same PR.
+ */
+export declare const TELEMETRY_NOTICE: string;
+export interface NoticeContext {
+    /** The invocation's command path ("ask", "telemetry off", "align" for the bare command). */
+    command: string;
+    /** Running as an agent hook (`check --hook` / `--advisory`): nobody is reading stderr. */
+    hook: boolean;
+    /** A cloud login token is in hand: cloud mode has its own, authenticated events. */
+    cloudSignedIn: boolean;
+}
+/**
+ * Shows the notice and marks it shown, or does neither. Skipped, and NOT marked, wherever
+ * nobody is reading it or it would be moot: no terminal on stdin and stderr, CI, an agent hook, `align mcp` (an agent's stdio
+ * server), a run inside a launched agent (ALIGN_WRAPPED), `align telemetry ...` (the off switch
+ * must not be raced by what it switches off), an env switch that already turns everything off,
+ * and any stored decision (granted, declined or off - that user was already asked or chose).
+ * Because it is not marked, nothing that waits on it sends from those runs either.
  *
- * Default is No: anything other than an explicit yes - the default answer, or Ctrl-C - leaves
- * telemetry off (D3).
+ * Returns whether it printed. Never throws: a broken config store costs the notice, which means
+ * nothing sends - the safe direction.
+ */
+export declare function maybeShowTelemetryNotice(config: TelemetryNoticeStore, ctx: NoticeContext, write?: (text: string) => void): boolean;
+/** The slice of the config store a sticky env opt-out needs. */
+export interface EnvOptOutStore {
+    getTelemetryConsent(): TelemetryConsent | undefined;
+    setTelemetryOffByEnv(via: string): void;
+}
+/**
+ * An explicit env opt-out (DO_NOT_TRACK, ALIGN_TELEMETRY) is made STICKY: stored as 'off' with
+ * its reason, so a process that does not inherit the variable still honours it. An MCP server
+ * started by an agent gets a trimmed environment, and the detached sync child inherits from that
+ * server, so the variable alone never reached them. Bare CI is not a user choice and is never
+ * stored (it is checked per process). A stored 'off' or 'declined' is left as it is. Called
+ * before anything in this process can send, and not subject to the terminal or hook rules above:
+ * a hook run that sees the variable stores it too. Never throws.
  */
-export declare function maybeRequestTelemetryConsent(config: TelemetryConsentStore, interactive: boolean): Promise<void>;
+export declare function storeEnvOptOut(config: EnvOptOutStore): boolean;
 //# sourceMappingURL=telemetry-consent.d.ts.map

package/dist/lib/telemetry-consent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"telemetry-consent.d.ts","sourceRoot":"","sources":["../../src/lib/telemetry-consent.ts"],"names":[],"mappings":"AAGA;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,mBAAmB,IAAI,SAAS,GAAG,UAAU,GAAG,KAAK,GAAG,SAAS,CAAC;IAClE,mBAAmB,CAAC,KAAK,EAAE,SAAS,GAAG,UAAU,GAAG,KAAK,GAAG,IAAI,CAAC;CAClE;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,4BAA4B,CAChD,MAAM,EAAE,qBAAqB,EAC7B,WAAW,EAAE,OAAO,GACnB,OAAO,CAAC,IAAI,CAAC,CAkBf"}
+{"version":3,"file":"telemetry-consent.d.ts","sourceRoot":"","sources":["../../src/lib/telemetry-consent.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEpD;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC,mBAAmB,IAAI,gBAAgB,GAAG,SAAS,CAAC;IACpD,yBAAyB,IAAI,MAAM,GAAG,SAAS,CAAC;IAChD,wBAAwB,IAAI,IAAI,CAAC;CAClC;AAED;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,QAI4D,CAAC;AAE1F,MAAM,WAAW,aAAa;IAC5B,4FAA4F;IAC5F,OAAO,EAAE,MAAM,CAAC;IAChB,0FAA0F;IAC1F,IAAI,EAAE,OAAO,CAAC;IACd,oFAAoF;IACpF,aAAa,EAAE,OAAO,CAAC;CACxB;AAID;;;;;;;;;;GAUG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,oBAAoB,EAC5B,GAAG,EAAE,aAAa,EAClB,KAAK,GAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAExB,GACA,OAAO,CAqBT;AAED,gEAAgE;AAChE,MAAM,WAAW,cAAc;IAC7B,mBAAmB,IAAI,gBAAgB,GAAG,SAAS,CAAC;IACpD,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;CACzC;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAW9D"}