@indigoai-us/hq-cloud 6.18.44-alpha.9 → 6.18.44

package/dist/usage-company-fallback.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Company fallback for usage events whose `cwd` maps to no company folder.
+ *
+ * `./company-resolver.ts` attributes an event by where it ran: inside a
+ * company's repo checkout or inside the company's own HQ folder. A session
+ * started from the HQ root matches neither, so its usage was uploaded with no
+ * company. This module supplies the next two sources, in order, and only when
+ * the existing resolver found nothing:
+ *
+ *   1. The session's own saved company: the session's meta.yaml under the HQ
+ *      root's session workspace (`company_slug`, when its `company_source` is
+ *      `session`), or the work-context session state file (when its company
+ *      is verified, the same test hq-cli applies).
+ *   2. The device default company (work-context `config.json`), only when the
+ *      person opted in to usage attribution for that same company
+ *      (`usageAttribution`, see usageAttributionOptIn). A session bind needs no
+ *      opt-in: the person chose that company for that session.
+ *
+ * Both apply ONLY when the event's cwd is a location inside the HQ root that
+ * belongs to no tenant: the root itself and the core, personal, and workspace
+ * folders (except workspace worktrees), and not inside any git work tree whose
+ * top level is below the HQ root (a repo clone or worktree has its own owner).
+ * Everything else is an unknown owner and gets nothing: a company's own
+ * folder, a declared company path, any repo checkout (a repo the manifest does
+ * not map may belong to a company that is not cloud-backed), any worktree (its
+ * HQ layout is another tenant boundary), and anything outside the HQ root
+ * (which may be personal work).
+ *
+ * The cwd is canonicalised first: `..` segments are resolved and symlinks are
+ * followed, so a path that merely spells itself inside HQ is not inside HQ. A
+ * cwd that no longer exists cannot be canonicalised and gets nothing.
+ *
+ * It fails closed. Attributing work to the wrong company is worse than leaving
+ * it unattributed, so every doubt resolves to "no company":
+ *
+ *   - Only a company the manifest marks cloud-backed AND the signed-in person
+ *     is an active member of is ever returned. Membership comes from data the
+ *     run already has (the sync runner's own membership listing) or from the
+ *     local snapshot hq-cli keeps, never from a new request.
+ *   - `company_source: parent` and `spawn` are inherited from an ancestor
+ *     session whose own source is not recorded, so a device-default guess
+ *     could have been carried down as a bind. Neither is trusted.
+ *   - A session that names a company which cannot be used (not cloud-backed,
+ *     not a member, `personal`) stays empty. It does not fall to the default.
+ *   - Two session sources that disagree stay empty.
+ *   - The default yields to any other company the session names.
+ *
+ * The server may refuse a company (the person left it, or it switched
+ * collection off). A refusal is remembered on disk for 24 hours so the next
+ * passes do not pay for it again, and every event uuid that was sent without
+ * its fallback company is remembered so a later pass can never send the same
+ * event with one. Both live in a small JSON file next to the cursor.
+ *
+ * Cost: the manifest, the device config, and the state file are read at most
+ * once per upload pass; each session's two files and each distinct cwd at most
+ * once per pass. Reads are size-bounded and refuse anything that is not a
+ * regular file. A missing, oversized, or corrupt file is the same as an absent
+ * one.
+ *
+ * Privacy: this module returns a `cmp_*` uid or undefined. It adds nothing else
+ * to an event.
+ */
+import { type RepoCompanyMap } from "./company-resolver.js";
+/** How long a company the server refused stays unstamped. */
+export declare const REJECTION_TTL_MS: number;
+export interface UsageCompanyFallbackOptions {
+    hqRoot: string;
+    /** The manifest map already built for this pass. */
+    map: RepoCompanyMap;
+    /** The work-context folder (or its override). */
+    workContextRoot: string;
+    /** Where refusals and sent-without-company uuids are remembered. */
+    statePath: string;
+    /**
+     * Companies the signed-in person is an active member of, as already known to
+     * the caller for this run. When omitted, the local membership snapshot in the
+     * device config is used if it is fresh; otherwise nothing is stamped.
+     */
+    memberCompanyUids?: Iterable<string>;
+    /**
+     * The `prs_*` person this upload is authenticated as. The device default is
+     * used only when the opt-in names this same person; without it, never.
+     */
+    personUid?: string;
+    now?: () => number;
+}
+export interface UsageCompanyFallback {
+    /**
+     * The company for an event the existing resolver left empty, or undefined.
+     * `uuid` is the event's own id; an event that was already sent without its
+     * fallback company is never stamped again.
+     */
+    resolve(cwd: string | undefined, sessionId: string | undefined, uuid: string | undefined): Promise<string | undefined>;
+    /** Stop stamping this company (the server refused it), for REJECTION_TTL_MS. */
+    reject(companyUid: string): void;
+    /** Whether the server refused this company, this pass or within the TTL. */
+    isRejected(companyUid: string): boolean;
+    /** Remember events that went out without their fallback company. */
+    markSentWithoutCompany(uuids: Iterable<string>): void;
+    /** Write the remembered refusals and uuids. Never throws. */
+    persist(): Promise<void>;
+}
+export declare function createUsageCompanyFallback(options: UsageCompanyFallbackOptions): UsageCompanyFallback;
+//# sourceMappingURL=usage-company-fallback.d.ts.map

package/dist/usage-company-fallback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage-company-fallback.d.ts","sourceRoot":"","sources":["../src/usage-company-fallback.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AAOH,OAAO,EAAiB,KAAK,cAAc,EAAE,MAAM,uBAAuB,CAAC;AA4B3E,6DAA6D;AAC7D,eAAO,MAAM,gBAAgB,QAAsB,CAAC;AAWpD,MAAM,WAAW,2BAA2B;IAC1C,MAAM,EAAE,MAAM,CAAC;IACf,oDAAoD;IACpD,GAAG,EAAE,cAAc,CAAC;IACpB,iDAAiD;IACjD,eAAe,EAAE,MAAM,CAAC;IACxB,oEAAoE;IACpE,SAAS,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IACrC;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,OAAO,CACL,GAAG,EAAE,MAAM,GAAG,SAAS,EACvB,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,IAAI,EAAE,MAAM,GAAG,SAAS,GACvB,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAC/B,gFAAgF;IAChF,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,4EAA4E;IAC5E,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC;IACxC,oEAAoE;IACpE,sBAAsB,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC;IACtD,6DAA6D;IAC7D,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AA6GD,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,2BAA2B,GACnC,oBAAoB,CAqatB"}