@indigoai-us/hq-cli 5.345.178 → 5.345.180

package/dist/lib/hot-channels/adapters/slack.js

@@ -0,0 +1,277 @@
+/**
+ * Slack hot channel (hot-signal-sync US-006).
+ *
+ * The live Slack events webhook in hq-pro-agents
+ * (`src/sources/inbound/slack-events.ts`) already lands one document per
+ * thread in the company vault under `sources/slack/`. From the local loop's
+ * side those threads are in the vault before the sync starts, so this adapter
+ * is a poll adapter over that folder, the same shape as meetings (US-008). It
+ * lists the thread documents ingested after the cursor that belong to the
+ * signed-in person, oldest first, and the cursor is the newest `ingested_at`.
+ *
+ * The hq-pro catalog entry for slack still says `transport: push`. run.ts
+ * plans by the registered adapter's transport, so this adapter runs once per
+ * usable Slack connection either way; the catalog correction is an hq-pro
+ * follow-up.
+ *
+ * Each landed document is a pointer. Its body is a short header (channel,
+ * time, owner, message count, audience) and `payload_ref` names the thread
+ * document. No message text is copied: the `.raw.json` sidecar holds only
+ * thread metadata.
+ *
+ * `audience_source` says how the audience was derived: `channel_members` (a
+ * `channel_members` or `audience` list on the thread document) or
+ * `person_uid` (only the person whose connection landed the thread). Today's
+ * writer records no channel membership, so the audience is the person until it
+ * does. The Slack user ids of the people in the thread are kept as
+ * `slack_participants`.
+ *
+ * Slack pauses event delivery to an app that exceeds its rate limit and sends
+ * `app_rate_limited`. A marker newer than the cursor (`_app_rate_limited.json`
+ * or a document with `type: app_rate_limited` in `sources/slack/`, without a
+ * `resolved_at`) fails the adapter with `SlackAppRateLimitedError`, whose
+ * message lands in the run ledger's `error`. The cursor does not move.
+ * Writing that marker from the webhook is an hq-pro-agents follow-up.
+ */
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import * as yaml from "js-yaml";
+import { MAX_CATCH_UP_WINDOW_MS } from "../contract.js";
+import { HOT_SIGNAL_ORIGIN } from "../landing.js";
+export const SLACK_ADAPTER_ID = "slack";
+export const SLACK_CHANNEL = "slack-events";
+export const SLACK_PROVIDER = "slack";
+export const SLACK_THREAD_EVENT = "slack.thread";
+export const SLACK_THREAD_DIR = "sources/slack";
+export const SLACK_RATE_LIMIT_MARKER = "_app_rate_limited.json";
+export const SLACK_APP_RATE_LIMITED = "app_rate_limited";
+const SUGGESTION_WINDOW_MS = 14 * 24 * 60 * 60 * 1000;
+const DEFAULT_PAGE_SIZE = 100;
+/** Slack paused event delivery, so threads after `pausedAt` may be missing. */
+export class SlackAppRateLimitedError extends Error {
+    pausedAt;
+    code = SLACK_APP_RATE_LIMITED;
+    constructor(pausedAt) {
+        super(`Slack paused event delivery (app_rate_limited) at ${pausedAt}: retry \`hq sources sync\` in a minute, or reconnect Slack if it persists: hq integrations connect slack`);
+        this.pausedAt = pausedAt;
+        this.name = "SlackAppRateLimitedError";
+    }
+}
+/** Thread metadata copied to the raw sidecar. Anything else on the document stays put. */
+const RAW_FIELDS = [
+    "person_uid",
+    "account_id",
+    "slack_team_id",
+    "channel_id",
+    "channel_name",
+    "thread_ts",
+    "source_channel_type",
+    "message_count",
+    "first_message_at",
+    "last_message_at",
+    "ingested_at",
+];
+function nonEmptyString(value) {
+    return typeof value === "string" && value.trim() !== "" ? value.trim() : undefined;
+}
+function idString(value) {
+    return typeof value === "number" && Number.isFinite(value) ? String(value) : nonEmptyString(value);
+}
+function stringList(value) {
+    if (!Array.isArray(value))
+        return [];
+    return [...new Set(value.map(nonEmptyString).filter((v) => v !== undefined))];
+}
+function parseTime(value) {
+    const stamp = nonEmptyString(value);
+    return stamp === undefined ? NaN : Date.parse(stamp);
+}
+/** Split `---\n{yaml}\n---\n{body}` and return the frontmatter. Unparseable or non-object is null. */
+function readFrontmatter(text) {
+    const match = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(text);
+    if (!match)
+        return null;
+    let parsed;
+    try {
+        parsed = yaml.load(match[1], { schema: yaml.CORE_SCHEMA });
+    }
+    catch {
+        return null;
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+        return null;
+    return parsed;
+}
+function toThread(file, fm) {
+    if (fm.origin === HOT_SIGNAL_ORIGIN)
+        return null;
+    const channelId = nonEmptyString(fm.channel_id);
+    const threadTs = idString(fm.thread_ts);
+    const owner = nonEmptyString(fm.person_uid);
+    const tsMs = parseTime(fm.ingested_at);
+    if (!channelId || !threadTs || !owner || Number.isNaN(tsMs))
+        return null;
+    const members = stringList(fm.channel_members).length > 0 ? stringList(fm.channel_members) : stringList(fm.audience);
+    return {
+        file,
+        tsMs,
+        channelId,
+        threadTs,
+        frontmatter: fm,
+        audience: members.length > 0 ? members : [owner],
+        audienceSource: members.length > 0 ? "channel_members" : "person_uid",
+    };
+}
+function toEvent(t) {
+    const fm = t.frontmatter;
+    const owner = nonEmptyString(fm.person_uid);
+    const channelName = nonEmptyString(fm.channel_name);
+    const where = channelName ? `#${channelName.replace(/^#/, "")}` : t.channelId;
+    const lastMs = parseTime(fm.last_message_at);
+    const when = new Date(Number.isNaN(lastMs) ? t.tsMs : lastMs).toISOString();
+    const count = typeof fm.message_count === "number" && fm.message_count >= 0 ? fm.message_count : null;
+    const participants = stringList(fm.participants);
+    const payloadRef = `${SLACK_THREAD_DIR}/${t.file}`;
+    const title = `Slack thread in ${where}`;
+    const body = [
+        `# ${title}`,
+        "",
+        `- When: ${when}`,
+        `- Who: ${owner}`,
+        `- Messages: ${count ?? "unknown"}`,
+        `- Audience: ${t.audience.join(", ")}`,
+        `- Where: ${where}`,
+        `- Thread: ${payloadRef}`,
+        "",
+    ].join("\n");
+    const raw = {};
+    for (const field of RAW_FIELDS)
+        if (fm[field] !== undefined)
+            raw[field] = fm[field];
+    return {
+        providerId: `${t.channelId}:${t.threadTs}`,
+        // A thread that gains replies is landed again: new message count or last message.
+        version: `${count ?? 0}.${Number.isNaN(lastMs) ? t.tsMs : lastMs}`,
+        who: owner,
+        what: SLACK_THREAD_EVENT,
+        where,
+        when,
+        audience: [...t.audience],
+        title,
+        body,
+        payloadRef,
+        frontmatter: {
+            audience_source: t.audienceSource,
+            slack_channel_id: t.channelId,
+            slack_thread_ts: t.threadTs,
+            ...(participants.length > 0 ? { slack_participants: participants.join(",") } : {}),
+        },
+        raw: { thread: payloadRef, ...raw, participants, audience: [...t.audience], audience_source: t.audienceSource },
+    };
+}
+function byTimeThenName(a, b) {
+    return a.tsMs - b.tsMs || (a.file < b.file ? -1 : a.file > b.file ? 1 : 0);
+}
+/** When an unresolved `app_rate_limited` marker is set, the time it was set. */
+function rateLimitedAt(record) {
+    if (record.type !== SLACK_APP_RATE_LIMITED && record.error !== SLACK_APP_RATE_LIMITED)
+        return NaN;
+    if (nonEmptyString(record.resolved_at) !== undefined)
+        return NaN;
+    const at = parseTime(record.at);
+    return Number.isNaN(at) ? parseTime(record.ingested_at) : at;
+}
+async function readMarker(file) {
+    try {
+        const parsed = JSON.parse(await fs.readFile(file, "utf8"));
+        return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+            ? rateLimitedAt(parsed)
+            : NaN;
+    }
+    catch {
+        return NaN;
+    }
+}
+export function createSlackAdapter(options) {
+    const dir = path.join(options.vaultRoot, SLACK_THREAD_DIR);
+    const pageSize = options.pageSize ?? DEFAULT_PAGE_SIZE;
+    if (!Number.isInteger(pageSize) || pageSize < 1)
+        throw new Error("slack pageSize must be a positive integer");
+    async function fetch(cursor, ctx) {
+        let names;
+        try {
+            names = await fs.readdir(dir);
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                return { events: [], cursor, hasMore: false };
+            throw err;
+        }
+        const me = new Set([ctx.personUid, ...(options.identities ?? []), ...(options.accountIds ?? []), ctx.gateway?.connectionId]
+            .filter((id) => typeof id === "string" && id !== "")
+            .map((id) => id.toLowerCase()));
+        const sinceMs = Date.parse(ctx.since);
+        const cursorMs = cursor === null ? NaN : Date.parse(cursor);
+        const floorMs = Number.isNaN(cursorMs) ? sinceMs : cursorMs;
+        let pausedMs = names.includes(SLACK_RATE_LIMIT_MARKER) ? await readMarker(path.join(dir, SLACK_RATE_LIMIT_MARKER)) : NaN;
+        const candidates = [];
+        for (const file of names.filter((n) => n.endsWith(".md")).sort()) {
+            let text;
+            try {
+                text = await fs.readFile(path.join(dir, file), "utf8");
+            }
+            catch {
+                continue;
+            }
+            const fm = readFrontmatter(text);
+            if (!fm)
+                continue;
+            const marker = rateLimitedAt(fm);
+            if (!Number.isNaN(marker)) {
+                if (Number.isNaN(pausedMs) || marker > pausedMs)
+                    pausedMs = marker;
+                continue;
+            }
+            const t = toThread(file, fm);
+            if (!t || t.tsMs < sinceMs)
+                continue;
+            const owners = [nonEmptyString(fm.person_uid), nonEmptyString(fm.account_id)];
+            if (!owners.some((id) => id !== undefined && me.has(id.toLowerCase())))
+                continue;
+            candidates.push(t);
+        }
+        if (!Number.isNaN(pausedMs) && pausedMs > floorMs) {
+            throw new SlackAppRateLimitedError(new Date(pausedMs).toISOString());
+        }
+        candidates.sort(byTimeThenName);
+        // Threads at the cursor time are re-read every page: a thread that lands
+        // later with the same ingest time is not lost, and duplicates are dropped
+        // by landing. A page never splits one timestamp.
+        const atCursor = candidates.filter((t) => t.tsMs === cursorMs);
+        const newer = Number.isNaN(cursorMs) ? candidates : candidates.filter((t) => t.tsMs > cursorMs);
+        let end = Math.min(pageSize, newer.length);
+        while (end > 0 && end < newer.length && newer[end].tsMs === newer[end - 1].tsMs)
+            end += 1;
+        const page = newer.slice(0, end);
+        const last = page[page.length - 1];
+        return {
+            events: [...atCursor, ...page].map(toEvent),
+            cursor: last ? new Date(last.tsMs).toISOString() : cursor,
+            hasMore: end < newer.length,
+        };
+    }
+    return {
+        id: SLACK_ADAPTER_ID,
+        channel: SLACK_CHANNEL,
+        transport: "poll",
+        hotEventTypes: [SLACK_THREAD_EVENT],
+        catchUpWindow: { maxLookbackMs: MAX_CATCH_UP_WINDOW_MS },
+        tokenScope: { provider: SLACK_PROVIDER, scopes: [] },
+        // Channels with a thread in the last 14 days. The evaluator (US-014)
+        // orders suggested channels by message count, highest first: each landed
+        // event carries the thread's `message_count` in its raw sidecar.
+        suggestionRule: { kind: "recent-activity", withinMs: SUGGESTION_WINDOW_MS, minEvents: 1 },
+        fetch,
+    };
+}
+//# sourceMappingURL=slack.js.map

package/dist/lib/hot-channels/alert.d.ts

@@ -0,0 +1,78 @@
+/**
+ * The signals-failure alert (US-012).
+ *
+ * The owner's health rule, verbatim: "sync and build feels wrong. we should be
+ * logging sources and signals generated." A sync that lands sources but
+ * generates no signals is a failure, whatever the ledger line's status says.
+ * After each run the ledger lines are checked for that shape and the owner is
+ * told: first by a direct message (the primary alert, sent even when the job
+ * is quiet), then by a Slack post to the company channel when the company set
+ * `signals_alert_channel` in `settings/signals/preferences.yaml`.
+ *
+ * Alerts are deduped per adapter and connection for an hour. The dedupe state
+ * sits next to the ledger in the vault (`sources/_runs/@{personKey}/_alerts.json`)
+ * so the scheduled job and `hq sources sync` share it across machines.
+ */
+import type { RunLedgerEntry } from "./ledger.js";
+import type { OnDemandSyncDeps } from "./run.js";
+export declare const SIGNALS_HEALTH_RULE: string;
+/** One alert per adapter and connection per hour. */
+export declare const SIGNALS_ALERT_DEDUPE_MS: number;
+export declare const SIGNALS_ALERT_STATE_FILE = "_alerts.json";
+/** The company setting that names the Slack channel for signals alerts. */
+export declare const SIGNALS_ALERT_CHANNEL_FIELD = "signals_alert_channel";
+/** The gateway's Slack post tool. */
+export declare const SLACK_POST_TOOL = "slack.messages.post";
+/** Ledger lines that landed sources and generated no signals, whatever their status. */
+export declare function findSignalsFailures(entries: readonly RunLedgerEntry[]): RunLedgerEntry[];
+/** The dedupe key: one adapter on one connection. */
+export declare function signalsAlertKey(entry: Pick<RunLedgerEntry, "adapter" | "connectionId">): string;
+export declare function formatSignalsFailureAlert(entry: RunLedgerEntry, options?: {
+    personName?: string;
+}): string;
+/** `{vaultRoot}/sources/_runs/@{personKey}/_alerts.json` */
+export declare function signalsAlertStatePath(vaultRoot: string, personKey: string): string;
+export interface RaiseSignalsFailureAlertsInput {
+    vaultRoot: string;
+    personKey: string;
+    entries: readonly RunLedgerEntry[];
+    now: () => Date;
+    personName?: string;
+    /** The primary alert: a direct message to the owner. Throws when it was not delivered. */
+    sendOwnerDm: (text: string) => Promise<void>;
+    /** The optional company-channel post; unset when no channel is configured. */
+    postCompanyChannel?: (text: string) => Promise<void>;
+    log?: (message: string) => void;
+}
+export interface RaiseSignalsFailureAlertsResult {
+    /** Dedupe keys alerted this run. */
+    sent: string[];
+    /** Dedupe keys skipped because an alert went out within the hour. */
+    suppressed: string[];
+    /** Dedupe keys whose owner DM failed; not recorded, so the next run tries again. */
+    failed: string[];
+}
+/**
+ * Alert the owner for each signals failure in this run's ledger lines. Never
+ * throws: a failed send is logged and left unrecorded so the next run retries.
+ */
+export declare function raiseSignalsFailureAlerts(input: RaiseSignalsFailureAlertsInput): Promise<RaiseSignalsFailureAlertsResult>;
+/** `{hqRoot}/companies/{company}/settings/signals/preferences.yaml` */
+export declare function signalsPreferencesPath(hqRoot: string, company: string): string;
+/**
+ * The Slack channel id for signals alerts, from the company's
+ * `settings/signals/preferences.yaml` (`signals_alert_channel: C0123`), or
+ * undefined when the file or the field is missing.
+ */
+export declare function readSignalsAlertChannel(hqRoot: string, company: string): string | undefined;
+/**
+ * The company-channel poster for signals alerts: posts through the person's
+ * usable Slack connection on the HQ integrations gateway. Undefined when no
+ * channel is configured.
+ */
+export declare function createSignalsAlertChannelPoster(input: {
+    hqRoot: string;
+    company: string;
+    deps: Pick<OnDemandSyncDeps, "fetchUsableApps" | "callTool">;
+}): ((text: string) => Promise<void>) | undefined;
+//# sourceMappingURL=alert.d.ts.map

package/dist/lib/hot-channels/alert.js

@@ -0,0 +1,179 @@
+/**
+ * The signals-failure alert (US-012).
+ *
+ * The owner's health rule, verbatim: "sync and build feels wrong. we should be
+ * logging sources and signals generated." A sync that lands sources but
+ * generates no signals is a failure, whatever the ledger line's status says.
+ * After each run the ledger lines are checked for that shape and the owner is
+ * told: first by a direct message (the primary alert, sent even when the job
+ * is quiet), then by a Slack post to the company channel when the company set
+ * `signals_alert_channel` in `settings/signals/preferences.yaml`.
+ *
+ * Alerts are deduped per adapter and connection for an hour. The dedupe state
+ * sits next to the ledger in the vault (`sources/_runs/@{personKey}/_alerts.json`)
+ * so the scheduled job and `hq sources sync` share it across machines.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { assertNotIntegrationSecretsPath, personDirName } from "./cursors.js";
+import { writeFileAtomic } from "./landing.js";
+export const SIGNALS_HEALTH_RULE = 'Owner rule: "sync and build feels wrong. we should be logging sources and signals generated." ' +
+    "A run that lands sources and generates no signals is a failure.";
+/** One alert per adapter and connection per hour. */
+export const SIGNALS_ALERT_DEDUPE_MS = 60 * 60 * 1000;
+export const SIGNALS_ALERT_STATE_FILE = "_alerts.json";
+/** The company setting that names the Slack channel for signals alerts. */
+export const SIGNALS_ALERT_CHANNEL_FIELD = "signals_alert_channel";
+/** The gateway's Slack post tool. */
+export const SLACK_POST_TOOL = "slack.messages.post";
+/** Ledger lines that landed sources and generated no signals, whatever their status. */
+export function findSignalsFailures(entries) {
+    return entries.filter((e) => e.sourcesLanded > 0 && e.signalsGenerated === 0);
+}
+/** The dedupe key: one adapter on one connection. */
+export function signalsAlertKey(entry) {
+    return `${entry.adapter}:${entry.connectionId ?? "-"}`;
+}
+export function formatSignalsFailureAlert(entry, options = {}) {
+    const who = options.personName ?? entry.personUid;
+    const lines = [
+        `Signals failure for ${who}: ${entry.adapter}${entry.connectionId ? ` (${entry.connectionId})` : ""} ` +
+            `landed ${entry.sourcesLanded} source${entry.sourcesLanded === 1 ? "" : "s"} and generated 0 signals.`,
+        `Run ${entry.runId} (${entry.trigger}, status ${entry.status}) finished ${entry.finishedAt}.`,
+    ];
+    if (entry.error)
+        lines.push(`Error: ${entry.error}`);
+    lines.push(SIGNALS_HEALTH_RULE);
+    return lines.join("\n");
+}
+/** `{vaultRoot}/sources/_runs/@{personKey}/_alerts.json` */
+export function signalsAlertStatePath(vaultRoot, personKey) {
+    const file = path.join(vaultRoot, "sources", "_runs", personDirName(personKey), SIGNALS_ALERT_STATE_FILE);
+    assertNotIntegrationSecretsPath(file);
+    return file;
+}
+async function readAlertState(file) {
+    try {
+        const parsed = JSON.parse(await fs.promises.readFile(file, "utf8"));
+        if (parsed && parsed.v === 1 && parsed.lastAlertAt && typeof parsed.lastAlertAt === "object") {
+            return { v: 1, lastAlertAt: { ...parsed.lastAlertAt } };
+        }
+    }
+    catch {
+        // Missing or unreadable: no alert sent yet.
+    }
+    return { v: 1, lastAlertAt: {} };
+}
+/**
+ * Alert the owner for each signals failure in this run's ledger lines. Never
+ * throws: a failed send is logged and left unrecorded so the next run retries.
+ */
+export async function raiseSignalsFailureAlerts(input) {
+    const result = { sent: [], suppressed: [], failed: [] };
+    const failures = findSignalsFailures(input.entries);
+    if (failures.length === 0)
+        return result;
+    const log = input.log ?? (() => { });
+    let file;
+    try {
+        file = signalsAlertStatePath(input.vaultRoot, input.personKey);
+    }
+    catch (err) {
+        log(`signals alert skipped: ${err instanceof Error ? err.message : String(err)}`);
+        return result;
+    }
+    const state = await readAlertState(file);
+    const seen = new Set();
+    let changed = false;
+    for (const entry of failures) {
+        const key = signalsAlertKey(entry);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        const at = input.now();
+        const last = state.lastAlertAt[key] ? Date.parse(state.lastAlertAt[key]) : Number.NaN;
+        if (!Number.isNaN(last) && at.getTime() - last < SIGNALS_ALERT_DEDUPE_MS) {
+            result.suppressed.push(key);
+            continue;
+        }
+        const text = formatSignalsFailureAlert(entry, input.personName ? { personName: input.personName } : {});
+        try {
+            await input.sendOwnerDm(text);
+        }
+        catch (err) {
+            log(`signals alert for ${key} was not delivered: ${err instanceof Error ? err.message : String(err)}`);
+            result.failed.push(key);
+            continue;
+        }
+        state.lastAlertAt[key] = at.toISOString();
+        changed = true;
+        result.sent.push(key);
+        if (input.postCompanyChannel) {
+            try {
+                await input.postCompanyChannel(text);
+            }
+            catch (err) {
+                log(`signals alert for ${key} was not posted to the company channel: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+    }
+    if (changed) {
+        try {
+            await writeFileAtomic(file, `${JSON.stringify(state, null, 2)}\n`);
+        }
+        catch (err) {
+            log(`signals alert state was not saved: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    return result;
+}
+/** `{hqRoot}/companies/{company}/settings/signals/preferences.yaml` */
+export function signalsPreferencesPath(hqRoot, company) {
+    return path.join(hqRoot, "companies", company, "settings", "signals", "preferences.yaml");
+}
+/**
+ * The Slack channel id for signals alerts, from the company's
+ * `settings/signals/preferences.yaml` (`signals_alert_channel: C0123`), or
+ * undefined when the file or the field is missing.
+ */
+export function readSignalsAlertChannel(hqRoot, company) {
+    let body;
+    try {
+        body = fs.readFileSync(signalsPreferencesPath(hqRoot, company), "utf8");
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === "ENOENT" || code === "ENOTDIR" || code === "EACCES" || code === "ELOOP")
+            return undefined;
+        throw error;
+    }
+    const field = SIGNALS_ALERT_CHANNEL_FIELD;
+    for (const line of body.split(/\n/)) {
+        if (!line.startsWith(`${field}:`))
+            continue;
+        let value = line.slice(field.length + 1).replace(/^\s+/, "");
+        value = value.replace(/\s+#.*$/, "");
+        value = value.replace(/^["']|["']$/g, "").trim();
+        if (value.length > 0)
+            return value;
+    }
+    return undefined;
+}
+/**
+ * The company-channel poster for signals alerts: posts through the person's
+ * usable Slack connection on the HQ integrations gateway. Undefined when no
+ * channel is configured.
+ */
+export function createSignalsAlertChannelPoster(input) {
+    const channelId = readSignalsAlertChannel(input.hqRoot, input.company);
+    if (!channelId)
+        return undefined;
+    return async (text) => {
+        const apps = await input.deps.fetchUsableApps();
+        const slack = apps.find((app) => app.provider === "slack");
+        if (!slack)
+            throw new Error("no usable Slack connection for the signals alert channel");
+        await input.deps.callTool(slack, SLACK_POST_TOOL, { channelId, text });
+    };
+}
+//# sourceMappingURL=alert.js.map

package/dist/lib/hot-channels/audience.d.ts

@@ -0,0 +1,15 @@
+/** Audience key for content visible to the whole company. */
+export declare const COMPANY_AUDIENCE_KEY = "company";
+/**
+ * The vault audience key from the hq-ontology-local spec
+ * (core/knowledge/public/hq-core/ontology-local-spec.md): the first 16 hex
+ * characters of `sha256(join(",", sort(unique(principal))))`. Each principal is
+ * trimmed, emails are lowercased, and person/agent uids keep their case. The
+ * literal `company` is the company-wide key. For one person this is the hash of
+ * their own lowercased email, which is the `@{personKey}` path segment.
+ *
+ * Matches `core/scripts/ontology-candidate.sh key` byte for byte, including its
+ * `LC_ALL=C sort` byte ordering.
+ */
+export declare function audienceKey(principals: readonly string[]): string;
+//# sourceMappingURL=audience.d.ts.map

package/dist/lib/hot-channels/audience.js

@@ -0,0 +1,25 @@
+import { createHash } from "node:crypto";
+/** Audience key for content visible to the whole company. */
+export const COMPANY_AUDIENCE_KEY = "company";
+/**
+ * The vault audience key from the hq-ontology-local spec
+ * (core/knowledge/public/hq-core/ontology-local-spec.md): the first 16 hex
+ * characters of `sha256(join(",", sort(unique(principal))))`. Each principal is
+ * trimmed, emails are lowercased, and person/agent uids keep their case. The
+ * literal `company` is the company-wide key. For one person this is the hash of
+ * their own lowercased email, which is the `@{personKey}` path segment.
+ *
+ * Matches `core/scripts/ontology-candidate.sh key` byte for byte, including its
+ * `LC_ALL=C sort` byte ordering.
+ */
+export function audienceKey(principals) {
+    const trimmed = principals.map((p) => p.trim()).filter((p) => p.length > 0);
+    if (trimmed.length === 0)
+        throw new Error("audience key needs at least one principal");
+    if (trimmed.length === 1 && trimmed[0].toLowerCase() === COMPANY_AUDIENCE_KEY) {
+        return COMPANY_AUDIENCE_KEY;
+    }
+    const normalized = [...new Set(trimmed.map((p) => (p.includes("@") ? p.toLowerCase() : p)))].sort((a, b) => Buffer.compare(Buffer.from(a, "utf8"), Buffer.from(b, "utf8")));
+    return createHash("sha256").update(normalized.join(",")).digest("hex").slice(0, 16);
+}
+//# sourceMappingURL=audience.js.map