@indigoai-us/hq-cli 5.289.0 → 5.291.0

package/dist/commands/secrets.js

@@ -5,6 +5,7 @@ import { cognitoCachePrincipalUid, ensureCognitoToken } from "../utils/cognito-s
 import { isAuthError } from "../utils/auth-error.js";
 import { DEFAULT_SECRETS_CACHE_TTL_MS, hasCacheEntry, readCache, writeCache, removeCacheEntry, clearAllCache, } from "../utils/secrets-cache.js";
 import { computeSha256 } from "../utils/integrity.js";
+import { isPlanGateError } from "../utils/plan-gate-error.js";
 import { SECRET_NAME_PATTERN, GROUP_ID_PATTERN, EMAIL_PATTERN } from "./_patterns.js";
 import { describeSecretsScope, formatSecretSaved, formatSecretsListEmpty, formatSecretsListHeader, } from "./secrets-scope.js";
 import { vaultApiFetch, getCompanyUid, getEntityUid, looksLikeCompanyUid, } from "../utils/vault-api.js";
@@ -988,6 +989,11 @@ export function registerSecretsCommand(program) {
             }
         }
         catch (err) {
+            // A plan-limit refusal goes to main.ts's shared renderer, which prints
+            // the reason, usage, fix options and upgrade link, offers the upgrade
+            // interactively, and exits non-zero.
+            if (isPlanGateError(err))
+                throw err;
             console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
             process.exit(1);
         }
@@ -1650,6 +1656,9 @@ export function registerSecretsCommand(program) {
             console.log(chalk.dim("  One-time use — link is invalidated after first submission."));
         }
         catch (err) {
+            // Same shared plan-limit renderer as `secrets set` (see main.ts).
+            if (isPlanGateError(err))
+                throw err;
             console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
             process.exit(1);
         }

package/dist/commands/skill.d.ts

@@ -18,6 +18,7 @@ import { Command } from "commander";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { vaultApiFetch, getCompanyUid } from "../utils/vault-api.js";
 import { surfaceCompanySkill } from "../lib/company-skill-wrapper.js";
+import { type PlanLimitRefusalSummary } from "../lib/billing/plan-limit-refusals.js";
 export declare const SKILL_UID_PATTERN: RegExp;
 export declare const SKILL_SLUG_PATTERN: RegExp;
 interface SkillSyncInput {
@@ -30,6 +31,8 @@ interface SkillSyncResult {
     filesUploaded: number;
     filesSkipped: number;
     aborted: boolean;
+    /** Set when a plan limit refused the upload; absent or null otherwise. */
+    planLimit?: PlanLimitRefusalSummary | null;
 }
 export declare function parseSkillUid(markdown: string): string | undefined;
 export declare function readActiveCompanySlug(hqRoot: string): string | undefined;

package/dist/commands/skill.js

@@ -27,25 +27,47 @@ import { surfaceCompanySkill } from "../lib/company-skill-wrapper.js";
 import { AuthError } from "../utils/auth-error.js";
 import { redactErrorText } from "../utils/redact-error-text.js";
 import { stampVaultAccessDenied, vaultAccessDeniedDiagnostics, } from "../utils/vault-access-denied-error.js";
+import { PlanGateError } from "../utils/plan-gate-error.js";
+import { createPlanLimitRefusalTracker, trackingProgressRecorder, } from "../lib/billing/plan-limit-refusals.js";
 export const SKILL_UID_PATTERN = /^skl_[A-Za-z0-9]+$/;
 export const SKILL_SLUG_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
 const COMPANY_SLUG_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
 const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/;
 const SHA256_HEX_PATTERN = /^[0-9a-f]{64}$/;
 async function defaultSyncFile(input) {
+    // The runner reports a plan-limit refusal as an event, not a throw, and still
+    // returns normally. Track it so the command cannot claim "Sync: complete".
+    const tracker = createPlanLimitRefusalTracker({ companySlug: input.companySlug });
     const result = await share({
         paths: [input.filePath],
         company: input.companySlug,
         hqRoot: input.hqRoot,
         vaultConfig: buildVaultConfig(input.token),
         onConflict: "abort",
+        progressRecorder: trackingProgressRecorder(tracker, input.companySlug),
     });
     return {
         filesUploaded: result.filesUploaded,
         filesSkipped: result.filesSkipped,
         aborted: result.aborted,
+        planLimit: tracker.summary(),
     };
 }
+/**
+ * The upload of a stamped skill file was refused by a plan limit. Registration
+ * and the local stamp already succeeded, so say that on stderr, then return a
+ * typed plan gate for main.ts to render (reason and upgrade link) and exit
+ * non-zero. Never "Skill ready … Sync: complete".
+ */
+function skillUploadRefused(skillUid, filePath, companySlug, refused) {
+    console.warn(chalk.yellow(`⚠ Skill ${skillUid} is stamped locally at '${filePath}', but the upload was refused by your plan limit.`));
+    return new PlanGateError("PLAN_LIMIT_EXCEEDED", {
+        reason: `${refused.message ?? "New files are paused by your plan limit."} ` +
+            "The skill file was not uploaded. Once the limit is sorted, upload it with: " +
+            `hq sync push --company ${companySlug} '${filePath}'`,
+        ...(refused.upgradeUrl ? { upgradeUrl: refused.upgradeUrl } : {}),
+    });
+}
 export function parseSkillUid(markdown) {
     const match = markdown.match(FRONTMATTER_RE);
     if (!match)
@@ -575,6 +597,9 @@ export function registerSkillCommand(program, deps = {}) {
                 // Sentry rather than filing a crash on its first occurrence.
                 throw localSkillError(`Skill ${registered.skillUid} is stamped locally at '${filePath}', but sync aborted because the remote file conflicts.`);
             }
+            if (syncResult.planLimit) {
+                throw skillUploadRefused(registered.skillUid, filePath, companySlug, syncResult.planLimit);
+            }
         }
         console.log(chalk.green(`Skill ready: ${registered.skillUid}`));
         console.log(`  File:     ${filePath}`);
@@ -739,6 +764,9 @@ export function registerSkillCommand(program, deps = {}) {
             if (syncResult.aborted) {
                 throw localSkillError(`Skill ${skillUid} is stamped locally at '${canonicalPath}', but sync aborted because the remote file conflicts.`);
             }
+            if (syncResult.planLimit) {
+                throw skillUploadRefused(skillUid, canonicalPath, companySlug, syncResult.planLimit);
+            }
         }
         console.log(chalk.green(`Skill promoted: ${skillUid}`));
         console.log(`  File:     ${canonicalPath}`);

package/dist/fast-core.js

@@ -54,6 +54,7 @@ export async function runFastCore(argv) {
         args: parsed.args,
         cwd: process.cwd(),
         hqRoot,
+        env: parsed.entry.name === "hq-session" ? { HQ_HQ_SESSION_NO_CLI: "1" } : undefined,
     });
     // Propagate verbatim: these scripts use their exit code as their interface.
     process.exit(code);

package/dist/lib/billing/free-month.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The free-month offer hq-pro attaches to Starter plan-limit payloads (the
+ * usage-limits nag and the hard-stop 402 body). Kept in a leaf module with no
+ * imports so the plan-gate error decoder can reuse the one parser without
+ * pulling in the HTTP layer that itself imports the decoder.
+ */
+export interface PlanLimitFreeMonth {
+    eligible: boolean;
+    trialDays?: number;
+    url?: string;
+}
+/**
+ * Parse `freeMonth` off a server payload. Anything but an explicit
+ * `eligible: true` is "no offer": an absent or malformed field never invents
+ * one.
+ */
+export declare function parseFreeMonth(value: unknown): PlanLimitFreeMonth | undefined;
+//# sourceMappingURL=free-month.d.ts.map

package/dist/lib/billing/free-month.js

@@ -0,0 +1,31 @@
+/**
+ * The free-month offer hq-pro attaches to Starter plan-limit payloads (the
+ * usage-limits nag and the hard-stop 402 body). Kept in a leaf module with no
+ * imports so the plan-gate error decoder can reuse the one parser without
+ * pulling in the HTTP layer that itself imports the decoder.
+ */
+/**
+ * Parse `freeMonth` off a server payload. Anything but an explicit
+ * `eligible: true` is "no offer": an absent or malformed field never invents
+ * one.
+ */
+export function parseFreeMonth(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        return undefined;
+    }
+    const rec = value;
+    if (rec.eligible !== true)
+        return undefined;
+    const url = typeof rec.url === "string" && rec.url.trim().length > 0
+        ? rec.url.trim()
+        : undefined;
+    const trialDays = typeof rec.trialDays === "number" && Number.isFinite(rec.trialDays)
+        ? rec.trialDays
+        : undefined;
+    return {
+        eligible: true,
+        ...(trialDays !== undefined ? { trialDays } : {}),
+        ...(url ? { url } : {}),
+    };
+}
+//# sourceMappingURL=free-month.js.map

package/dist/lib/billing/plan-limit-refusals.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Collect the files a sync push was refused by a plan limit, from the surfaces
+ * the pinned `@indigoai-us/hq-cloud` runner already has, so `hq sync push`,
+ * `hq sync now` and `hq skill create` never print a success line over a
+ * refusal.
+ *
+ * The runner reports a refusal two ways today:
+ *
+ *   1. A `{ type: "plan-limit", upgradeUrl }` event, emitted once per push pass
+ *      when a presign row carried a code it recognises. It names no path.
+ *   2. A per-file `{ type: "error", path, message }` event for a 402 it does not
+ *      recognise (hq-pro's hard-stop body). The message is hq-cloud's
+ *      `describeError` string, which carries `http=402` and, when the server
+ *      sent one, `code=…`.
+ *
+ * `@indigoai-us/hq-cloud` 6.18.17 (US-012) recognises the hard-stop body,
+ * names each refused path on the `plan-limit` event (`paths`, `count`) and
+ * stops re-sending paused keys. The `path`/`paths`/`count` reads below consume
+ * that event; the `error`-message parsing stays for runners older than
+ * 6.18.17.
+ */
+import { type SyncProgressEvent } from "@indigoai-us/hq-cloud";
+/** What one push leg was refused. `null` from the tracker means nothing was. */
+export interface PlanLimitRefusalSummary {
+    /**
+     * Refused files the runner reported. A `plan-limit` event with no path or
+     * count still means at least one file, so this is never 0.
+     */
+    count: number;
+    /** Vault-relative paths the runner named, de-duplicated, in report order. */
+    paths: string[];
+    /** Server sentence from a refused file's error, when one was carried. */
+    message?: string;
+    /** Server-selected (or company billing fallback) upgrade link. */
+    upgradeUrl?: string;
+}
+export interface PlanLimitRefusalTracker {
+    observe(event: SyncProgressEvent): void;
+    summary(): PlanLimitRefusalSummary | null;
+}
+/** True when a runner `error` message is a plan-limit (402) refusal. */
+export declare function isPlanLimitErrorMessage(message: unknown): boolean;
+/**
+ * @param opts.companySlug the push target's slug, used for the company billing
+ *   link when the runner did not carry one. Omit for a personal-vault leg.
+ */
+export declare function createPlanLimitRefusalTracker(opts?: {
+    companySlug?: string;
+}): PlanLimitRefusalTracker;
+/**
+ * The `progressRecorder` for a share() call: feeds the tracker and still writes
+ * the shared progress snapshot, exactly as share()'s default recorder does.
+ * Passing the recorder rather than `onEvent` keeps share()'s own console output
+ * unchanged. `company` is the snapshot label: the target slug, or null for the
+ * personal vault.
+ */
+export declare function trackingProgressRecorder(tracker: PlanLimitRefusalTracker, company: string | null): (event: SyncProgressEvent) => void;
+/** Add a later leg's refusals to an earlier total. */
+export declare function mergePlanLimitRefusals(a: PlanLimitRefusalSummary | null | undefined, b: PlanLimitRefusalSummary | null | undefined): PlanLimitRefusalSummary | null;
+/**
+ * Plain lines describing a refusal: what was not uploaded, why, and the
+ * upgrade link. Colour and the leading status line are the caller's.
+ */
+export declare function renderPlanLimitRefusalLines(summary: PlanLimitRefusalSummary, indent?: string): string[];
+/** "1 new file" / "3 new files", or "new files" when only a notice said so. */
+export declare function describeRefusedCount(summary: PlanLimitRefusalSummary): string;
+/** {@link describeRefusedCount} with its verb: "1 new file was", "new files were". */
+export declare function describeRefusedFiles(summary: PlanLimitRefusalSummary): string;
+//# sourceMappingURL=plan-limit-refusals.d.ts.map

package/dist/lib/billing/plan-limit-refusals.js

@@ -0,0 +1,187 @@
+/**
+ * Collect the files a sync push was refused by a plan limit, from the surfaces
+ * the pinned `@indigoai-us/hq-cloud` runner already has, so `hq sync push`,
+ * `hq sync now` and `hq skill create` never print a success line over a
+ * refusal.
+ *
+ * The runner reports a refusal two ways today:
+ *
+ *   1. A `{ type: "plan-limit", upgradeUrl }` event, emitted once per push pass
+ *      when a presign row carried a code it recognises. It names no path.
+ *   2. A per-file `{ type: "error", path, message }` event for a 402 it does not
+ *      recognise (hq-pro's hard-stop body). The message is hq-cloud's
+ *      `describeError` string, which carries `http=402` and, when the server
+ *      sent one, `code=…`.
+ *
+ * `@indigoai-us/hq-cloud` 6.18.17 (US-012) recognises the hard-stop body,
+ * names each refused path on the `plan-limit` event (`paths`, `count`) and
+ * stops re-sending paused keys. The `path`/`paths`/`count` reads below consume
+ * that event; the `error`-message parsing stays for runners older than
+ * 6.18.17.
+ */
+import { createSyncProgressRecorder, } from "@indigoai-us/hq-cloud";
+import { planLimitUpgradeFallbackUrl } from "./plan-limit-upgrade-url.js";
+/** Upgrade destination when neither the event nor the error named one. */
+const FALLBACK_UPGRADE_URL = "https://hq.computer/billing";
+const PLAN_LIMIT_CODE_TOKEN = /\bcode=(?:PLAN_LIMIT_EXCEEDED|PLAN_LIMIT_REACHED|plan_limit_reached)\b/;
+const HTTP_402_TOKEN = /\bhttp=402\b/;
+const DIAGNOSTIC_TOKEN = /^(?:[A-Za-z]+Error|code=\S+|path=\S+|http=\d+|syscall=\S+|cause=\S+|causeHttp=\d+|host=\S+)$/;
+/** True when a runner `error` message is a plan-limit (402) refusal. */
+export function isPlanLimitErrorMessage(message) {
+    return (typeof message === "string" &&
+        (PLAN_LIMIT_CODE_TOKEN.test(message) || HTTP_402_TOKEN.test(message)));
+}
+/**
+ * The human sentence at the end of a `describeError` string, after its
+ * `Name code=… path=… http=…` diagnostic prefix. Everything up to the `http=`
+ * token is dropped first, because a `path=` value may itself contain spaces.
+ * Undefined when nothing but diagnostics (or a machine token) is left.
+ */
+function serverSentence(message) {
+    const http = /\bhttp=\d+\s+/.exec(message);
+    const rest = http ? message.slice(http.index + http[0].length) : message;
+    const words = rest.trim().split(/\s+/);
+    let index = 0;
+    while (index < words.length && DIAGNOSTIC_TOKEN.test(words[index]))
+        index++;
+    const sentence = words.slice(index).join(" ").trim();
+    if (!sentence || sentence === "plan_limit_reached")
+        return undefined;
+    return sentence;
+}
+function safeHttpsUrl(value) {
+    if (typeof value !== "string" || value.trim() !== value)
+        return undefined;
+    try {
+        const url = new URL(value);
+        return url.protocol === "https:" && !url.username && !url.password
+            ? value
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * @param opts.companySlug the push target's slug, used for the company billing
+ *   link when the runner did not carry one. Omit for a personal-vault leg.
+ */
+export function createPlanLimitRefusalTracker(opts = {}) {
+    const paths = [];
+    let noticeSeen = false;
+    let reportedCount = 0;
+    let message;
+    let upgradeUrl;
+    const addPath = (value) => {
+        if (typeof value === "string" && value && !paths.includes(value)) {
+            paths.push(value);
+        }
+    };
+    return {
+        observe(event) {
+            const record = event;
+            if (event.type === "plan-limit") {
+                noticeSeen = true;
+                upgradeUrl ??= safeHttpsUrl(record.upgradeUrl);
+                addPath(record.path);
+                if (Array.isArray(record.paths))
+                    record.paths.forEach(addPath);
+                if (typeof record.count === "number" && Number.isFinite(record.count)) {
+                    reportedCount += Math.max(0, Math.trunc(record.count));
+                }
+                return;
+            }
+            if (event.type === "error" &&
+                record.diagnostic !== true &&
+                isPlanLimitErrorMessage(record.message)) {
+                noticeSeen = true;
+                addPath(record.path);
+                message ??= serverSentence(record.message);
+            }
+        },
+        summary() {
+            if (!noticeSeen)
+                return null;
+            const fallbackUrl = opts.companySlug
+                ? planLimitUpgradeFallbackUrl(opts.companySlug, FALLBACK_UPGRADE_URL)
+                : undefined;
+            const url = upgradeUrl ?? fallbackUrl;
+            return {
+                count: Math.max(1, paths.length, reportedCount),
+                paths: [...paths],
+                ...(message ? { message } : {}),
+                ...(url ? { upgradeUrl: url } : {}),
+            };
+        },
+    };
+}
+/**
+ * The `progressRecorder` for a share() call: feeds the tracker and still writes
+ * the shared progress snapshot, exactly as share()'s default recorder does.
+ * Passing the recorder rather than `onEvent` keeps share()'s own console output
+ * unchanged. `company` is the snapshot label: the target slug, or null for the
+ * personal vault.
+ */
+export function trackingProgressRecorder(tracker, company) {
+    const record = createSyncProgressRecorder({ company, phase: "push" });
+    return (event) => {
+        tracker.observe(event);
+        record(event);
+    };
+}
+/** Add a later leg's refusals to an earlier total. */
+export function mergePlanLimitRefusals(a, b) {
+    if (!a)
+        return b ?? null;
+    if (!b)
+        return a;
+    const paths = [...a.paths];
+    for (const p of b.paths)
+        if (!paths.includes(p))
+            paths.push(p);
+    const message = a.message ?? b.message;
+    const upgradeUrl = a.upgradeUrl ?? b.upgradeUrl;
+    return {
+        count: a.count + b.count,
+        paths,
+        ...(message ? { message } : {}),
+        ...(upgradeUrl ? { upgradeUrl } : {}),
+    };
+}
+/** How many named paths to print before summarising the rest. */
+const MAX_LISTED_PATHS = 20;
+/**
+ * Plain lines describing a refusal: what was not uploaded, why, and the
+ * upgrade link. Colour and the leading status line are the caller's.
+ */
+export function renderPlanLimitRefusalLines(summary, indent = "  ") {
+    const lines = [];
+    lines.push(`${indent}${summary.message ?? "New files are paused by your plan limit."}`);
+    if (summary.paths.length > 0) {
+        lines.push(`${indent}Not uploaded:`);
+        for (const p of summary.paths.slice(0, MAX_LISTED_PATHS)) {
+            lines.push(`${indent}  - ${p}`);
+        }
+        const unnamed = summary.count - Math.min(summary.paths.length, MAX_LISTED_PATHS);
+        if (unnamed > 0)
+            lines.push(`${indent}  … and ${unnamed} more`);
+    }
+    else {
+        lines.push(`${indent}New files stay on this machine and were not uploaded.`);
+    }
+    if (summary.upgradeUrl)
+        lines.push(`${indent}Upgrade: ${summary.upgradeUrl}`);
+    return lines;
+}
+/** "1 new file" / "3 new files", or "new files" when only a notice said so. */
+export function describeRefusedCount(summary) {
+    if (summary.paths.length === 0 && summary.count <= 1)
+        return "new files";
+    return `${summary.count} new file${summary.count === 1 ? "" : "s"}`;
+}
+/** {@link describeRefusedCount} with its verb: "1 new file was", "new files were". */
+export function describeRefusedFiles(summary) {
+    const subject = describeRefusedCount(summary);
+    return `${subject} ${subject === "1 new file" ? "was" : "were"}`;
+}
+//# sourceMappingURL=plan-limit-refusals.js.map

package/dist/lib/billing/plan-lock.d.ts

@@ -20,6 +20,8 @@
  * An absent field is UNKNOWN, so nothing here ever infers over-limit from
  * missing data (hq-absent-field-never-means-constraining-value).
  */
+import { parseFreeMonth, type PlanLimitFreeMonth } from "./free-month.js";
+export { parseFreeMonth, type PlanLimitFreeMonth };
 /**
  * Dimensions the bind notice names with a remedy. Owner decision 7 (2026-09-17)
  * fixes the nagging set at these four: `deployments` and `storageBytes` are
@@ -38,11 +40,6 @@ export interface PlanLimitMembers {
 }
 /** @deprecated US-040 — alias of {@link PlanLimitMembers}. */
 export type PlanLockMembers = PlanLimitMembers;
-export interface PlanLimitFreeMonth {
-    eligible: boolean;
-    trialDays?: number;
-    url?: string;
-}
 export interface PlanLimitStatus {
     companySlug: string;
     companyUid?: string;
@@ -78,7 +75,6 @@ export declare const STARTER_AGENT_TARGET = 0;
 export declare const DEFAULT_UPGRADE_URL = "https://hq.computer/billing";
 /** The paid plan the nag sends owners to. Copy lives in ONE place. */
 export declare const WORKFORCE_PLAN_LABEL = "HQ Workforce ($500/mo)";
-export declare function parseFreeMonth(value: unknown): PlanLimitFreeMonth | undefined;
 /**
  * Pick the membership row for `companySlug` (or `cmp_…` uid) out of a decoded
  * `/membership/me` body. No matching row is UNKNOWN. Does not read `planLock`.

package/dist/lib/billing/plan-lock.js

@@ -22,7 +22,12 @@
  */
 import chalk from "chalk";
 import { vaultApiFetch } from "../../utils/vault-api.js";
+import { parseFreeMonth } from "./free-month.js";
 import { selectPlanLimitUpgradeUrl } from "./plan-limit-upgrade-url.js";
+// The free-month parser lives in a leaf module so the plan-gate 402 decoder can
+// share it without importing the HTTP layer; re-exported so existing callers
+// keep importing it from here.
+export { parseFreeMonth };
 /**
  * Dimensions the bind notice names with a remedy. Owner decision 7 (2026-09-17)
  * fixes the nagging set at these four: `deployments` and `storageBytes` are
@@ -98,22 +103,6 @@ function rowIsOver(value) {
     const limit = finiteNumber(rec.limit);
     return used !== null && limit !== null && used > limit;
 }
-export function parseFreeMonth(value) {
-    const rec = asRecord(value);
-    if (!rec)
-        return undefined;
-    if (rec.eligible !== true)
-        return undefined;
-    const url = typeof rec.url === "string" && rec.url.trim().length > 0
-        ? rec.url.trim()
-        : undefined;
-    const trialDays = finiteNumber(rec.trialDays) ?? undefined;
-    return {
-        eligible: true,
-        ...(trialDays !== undefined ? { trialDays } : {}),
-        ...(url ? { url } : {}),
-    };
-}
 /**
  * Pick the membership row for `companySlug` (or `cmp_…` uid) out of a decoded
  * `/membership/me` body. No matching row is UNKNOWN. Does not read `planLock`.

package/dist/lib/checkpoint-ontology/entity-file.d.ts

@@ -66,6 +66,27 @@ export type PatchResult = {
  * change, the file is returned unchanged so a rerun writes nothing.
  */
 export declare function patchEntityFile(content: string, patch: EntityPatch): PatchResult;
+/** A namespaced record in a source system, as the cloud schema's `external_refs` holds it. */
+export interface ExternalRef {
+    system: string;
+    namespace: string;
+    objectType?: string;
+    recordId: string;
+}
+export interface IdentityPatch {
+    externalIds: Record<string, string>;
+    webDomains: string[];
+    /** When set, the whole `external_refs` list; when absent, the key is left alone. */
+    externalRefs?: ExternalRef[];
+    lastUpdated: string;
+}
+/**
+ * Set `external_ids` and `web_domains` on an existing, valid entity file.
+ * A key whose value is already equal is left as it is; an absent key is
+ * appended at the end of the front matter. Nothing else changes except
+ * `last_updated`. When neither key changes the file is returned unchanged.
+ */
+export declare function setIdentityKeys(content: string, patch: IdentityPatch): PatchResult;
 export interface SignalBackRef {
     signalType: string;
     preview: string;

package/dist/lib/checkpoint-ontology/entity-file.js

@@ -206,6 +206,106 @@ function checkPatched(original, next, aliases, signalCount, lastUpdated) {
         return "patch_last_updated";
     return null;
 }
+function renderExternalIds(ids) {
+    const entries = Object.entries(ids);
+    if (entries.length === 0)
+        return "external_ids: {}";
+    return ["external_ids:", ...entries.map(([key, value]) => `  ${key}: ${quote(value)}`)].join("\n");
+}
+function renderExternalRefs(refs) {
+    if (refs.length === 0)
+        return "external_refs: []";
+    const lines = ["external_refs:"];
+    for (const ref of refs) {
+        lines.push(`  - system: ${quote(ref.system)}`, `    namespace: ${quote(ref.namespace)}`);
+        if (ref.objectType !== undefined)
+            lines.push(`    objectType: ${quote(ref.objectType)}`);
+        lines.push(`    recordId: ${quote(ref.recordId)}`);
+    }
+    return lines.join("\n");
+}
+function renderWebDomains(domains) {
+    if (domains.length === 0)
+        return "web_domains: []";
+    return ["web_domains:", ...domains.map((domain) => `  - ${quote(domain)}`)].join("\n");
+}
+/**
+ * Set `external_ids` and `web_domains` on an existing, valid entity file.
+ * A key whose value is already equal is left as it is; an absent key is
+ * appended at the end of the front matter. Nothing else changes except
+ * `last_updated`. When neither key changes the file is returned unchanged.
+ */
+export function setIdentityKeys(content, patch) {
+    const match = FRONTMATTER_RE.exec(content);
+    const parsed = parseEntityFile(content);
+    if (!match || !parsed)
+        return { ok: false, reason: "unparseable" };
+    const before = validateEntityFrontmatter(parsed.frontmatter);
+    if (typeof before === "string")
+        return { ok: false, reason: `invalid_existing:${before}` };
+    for (const key of Object.keys(patch.externalIds)) {
+        if (!/^[A-Za-z0-9_-]+$/.test(key))
+            return { ok: false, reason: "external_ids_key" };
+    }
+    const currentIds = (parsed.frontmatter.external_ids ?? {});
+    const currentDomains = (parsed.frontmatter.web_domains ?? []);
+    const currentRefs = parsed.frontmatter.external_refs ?? [];
+    const idsChanged = !isDeepStrictEqual(currentIds, patch.externalIds);
+    const domainsChanged = !isDeepStrictEqual(currentDomains, patch.webDomains);
+    const refsChanged = patch.externalRefs !== undefined && !isDeepStrictEqual(currentRefs, patch.externalRefs);
+    if (!idsChanged && !domainsChanged && !refsChanged)
+        return { ok: true, content, changed: false };
+    const newline = content.includes("\r\n") ? "\r\n" : "\n";
+    let lines = match[1].split(/\r?\n/);
+    if (idsChanged) {
+        const rendered = renderExternalIds(patch.externalIds);
+        lines = replaceTopLevelKey(lines, "external_ids", rendered) ?? [...lines, ...rendered.split("\n")];
+    }
+    if (domainsChanged) {
+        const rendered = renderWebDomains(patch.webDomains);
+        lines = replaceTopLevelKey(lines, "web_domains", rendered) ?? [...lines, ...rendered.split("\n")];
+    }
+    if (refsChanged) {
+        const rendered = renderExternalRefs(patch.externalRefs);
+        lines = replaceTopLevelKey(lines, "external_refs", rendered) ?? [...lines, ...rendered.split("\n")];
+    }
+    const stamped = replaceTopLevelKey(lines, "last_updated", `last_updated: ${patch.lastUpdated}`);
+    if (!stamped)
+        return { ok: false, reason: "missing_owned_key" };
+    lines = stamped;
+    const head = content.slice(0, content.indexOf(match[1]));
+    const tail = content.slice(content.indexOf(match[1]) + match[1].length);
+    const next = `${head}${lines.join(newline)}${tail}`;
+    const reparsed = parseEntityFile(next);
+    if (!reparsed)
+        return { ok: false, reason: "patch_unparseable" };
+    if (typeof validateEntityFrontmatter(reparsed.frontmatter) === "string")
+        return { ok: false, reason: "patch_invalid" };
+    const keys = new Set([...Object.keys(parsed.frontmatter), ...Object.keys(reparsed.frontmatter)]);
+    for (const key of keys) {
+        if (key === "external_ids" || key === "web_domains" || key === "last_updated")
+            continue;
+        if (key === "external_refs" && patch.externalRefs !== undefined)
+            continue;
+        if (!isDeepStrictEqual(parsed.frontmatter[key], reparsed.frontmatter[key])) {
+            return { ok: false, reason: `patch_changed_key:${key}` };
+        }
+    }
+    if (!isDeepStrictEqual(reparsed.frontmatter.external_ids ?? {}, patch.externalIds)) {
+        return { ok: false, reason: "patch_external_ids" };
+    }
+    if (!isDeepStrictEqual(reparsed.frontmatter.web_domains ?? [], patch.webDomains)) {
+        return { ok: false, reason: "patch_web_domains" };
+    }
+    if (refsChanged && !isDeepStrictEqual(reparsed.frontmatter.external_refs ?? [], patch.externalRefs)) {
+        return { ok: false, reason: "patch_external_refs" };
+    }
+    if (reparsed.frontmatter.last_updated !== patch.lastUpdated)
+        return { ok: false, reason: "patch_last_updated" };
+    if (reparsed.body !== parsed.body)
+        return { ok: false, reason: "patch_body" };
+    return { ok: true, content: next, changed: true };
+}
 /** hq-pro `previewSignalContent`: first 80 characters, one line. */
 export function previewSignalContent(canonicalContent) {
     const collapsed = canonicalContent.replace(/\s+/g, " ").trim();