@indigoai-us/hq-cli 5.345.191 → 5.345.194

package/dist/lib/signals/steps/upload.js

@@ -0,0 +1,324 @@
+/**
+ * upload step (Hot-Signal Sync US-005).
+ *
+ * The step changes nothing about vault sync. `hq sync` and the background
+ * runner push and pull exactly what they did before Hot-Signal Sync (owner
+ * decision 2026-11-01). Promoted signals and company sources/ stay local
+ * because hq-cloud refuses client uploads of signals/** and sources/**;
+ * sharing promoted signals through audience ACLs is a later, separate
+ * hq-cloud change.
+ *
+ * 1. Member projection: pulls the caller's own
+ *    `ontology/projections/members/{memberUid}/v1/` prefix into
+ *    workspace/signals/projections/{company}/{memberUid}/v1/ and records its
+ *    state. hq-pro has no export trigger route yet (triggerProjectionExport).
+ * 2. Contributions: every signal promoted since the upload watermark
+ *    (workspace/signals/upload/{company}/{memberUid}.json) is sanitized
+ *    (src/lib/signals/sanitize.ts) and posted, one request each, to
+ *      POST /v1/files/contributions/company/{slug}/meetings
+ *      { destination: "member-signals/{memberUid}/observations/meetings/@{aud}/{type}/{id}.md",
+ *        contribution: sanitized-contribution.v1 }
+ *    The server writes only under the caller's own member-signals prefix.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { refreshMemberProjection, triggerProjectionExport, memberProjectionPrefix } from "../projection.js";
+import { sanitizeSignal, MEETING_SOURCE_RE, splitFrontmatter } from "../sanitize.js";
+const MAX_TRACKED_SHAS = 5000;
+export function contributionRoute(company) {
+    return `/v1/files/contributions/company/${encodeURIComponent(company)}/meetings`;
+}
+export function watermarkRel(company, memberUid) {
+    return `workspace/signals/upload/${company}/${memberUid}.json`;
+}
+export function readWatermark(hqRoot, company, memberUid) {
+    try {
+        const raw = JSON.parse(fs.readFileSync(path.join(hqRoot, watermarkRel(company, memberUid)), "utf8"));
+        return {
+            lastUploadedAt: typeof raw.lastUploadedAt === "string" ? raw.lastUploadedAt : null,
+            uploaded: Array.isArray(raw.uploaded) ? raw.uploaded.filter((s) => typeof s === "string") : [],
+            rejected: raw.rejected && typeof raw.rejected === "object" ? raw.rejected : {},
+        };
+    }
+    catch {
+        return { lastUploadedAt: null, uploaded: [], rejected: {} };
+    }
+}
+/** Promoted signals for a company not yet uploaded or rejected, newer than the watermark. */
+export function listSignalCandidates(hqRoot, company, wm) {
+    const companyRoot = path.join(hqRoot, "companies", company);
+    const signalsRoot = path.join(companyRoot, "signals");
+    const since = wm.lastUploadedAt ? Date.parse(wm.lastUploadedAt) : -Infinity;
+    const done = new Set([...wm.uploaded, ...Object.keys(wm.rejected)]);
+    const out = [];
+    const walk = (dir, depth) => {
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            if (e.name.startsWith("_") || e.name.startsWith("."))
+                continue;
+            const abs = path.join(dir, e.name);
+            if (e.isDirectory() && depth < 2)
+                walk(abs, depth + 1);
+            else if (e.isFile() && e.name.endsWith(".md")) {
+                const sha = e.name.slice(0, -3);
+                if (done.has(sha))
+                    continue;
+                const mtimeMs = fs.statSync(abs).mtimeMs;
+                if (mtimeMs <= since)
+                    continue;
+                out.push({ rel: path.relative(companyRoot, abs).split(path.sep).join("/"), sha, mtimeMs });
+            }
+        }
+    };
+    walk(signalsRoot, 0);
+    return out.sort((a, b) => a.mtimeMs - b.mtimeMs || a.rel.localeCompare(b.rel));
+}
+/** A 422 rejection that can pass on a later run (the source or receipt is not in the vault yet). */
+function isRetryableRejection(parsed) {
+    return Array.isArray(parsed.reasons) && parsed.reasons.length > 0 && parsed.reasons.every((r) => r === "source_unavailable");
+}
+function parseBody(text) {
+    try {
+        const v = JSON.parse(text);
+        return v && typeof v === "object" ? v : {};
+    }
+    catch {
+        return {};
+    }
+}
+export const defaultUploadDeps = {
+    async getSession(company) {
+        const { ensureCognitoToken, DEFAULT_VAULT_API_URL } = await import("../../../utils/cognito-session.js");
+        const { resolveCallerPersonUid, getCompanyUid } = await import("../../../utils/vault-api.js");
+        let token;
+        try {
+            token = await ensureCognitoToken({ interactive: false });
+        }
+        catch {
+            return null;
+        }
+        const memberUid = await resolveCallerPersonUid(token, undefined, { command: "hq signals run" });
+        const companyUid = await getCompanyUid(token, company);
+        return { token, memberUid, companyUid, baseUrl: DEFAULT_VAULT_API_URL };
+    },
+    fetch: (url, init) => fetch(url, init),
+    async readVaultObject(session, company, key) {
+        const { createCompanyPresignClient } = await import("../../../commands/files-browse.js");
+        const { GetObjectCommand } = await import("@aws-sdk/client-s3");
+        const client = createCompanyPresignClient({ token: session.token, companyUid: session.companyUid, companySlug: company });
+        try {
+            const resp = (await client.send(new GetObjectCommand({ Bucket: session.companyUid, Key: key })));
+            if (!resp.Body)
+                return null;
+            const chunks = [];
+            for await (const c of resp.Body)
+                chunks.push(Buffer.isBuffer(c) ? c : Buffer.from(c));
+            return Buffer.concat(chunks).toString("utf8");
+        }
+        catch (err) {
+            const e = err;
+            if (e.name === "NoSuchKey" || e.name === "NotFound" || e.status === 404 || e.$metadata?.httpStatusCode === 404)
+                return null;
+            throw err;
+        }
+    },
+};
+function base() {
+    return { status: "skipped", itemsIn: 0, itemsOut: 0, uploaded: { count: 0, bytes: 0 } };
+}
+async function planDryRun(ctx) {
+    // No network under --dry-run: the member is not resolved, so the watermark
+    // is read only when exactly one member has one for this company.
+    const wmDir = path.join(ctx.hqRoot, "workspace", "signals", "upload", ctx.company);
+    let memberUid = "<memberUid>";
+    try {
+        const files = fs.readdirSync(wmDir).filter((f) => f.endsWith(".json"));
+        if (files.length === 1)
+            memberUid = files[0].slice(0, -5);
+    }
+    catch {
+        // no watermark yet
+    }
+    const wm = readWatermark(ctx.hqRoot, ctx.company, memberUid);
+    const candidates = listSignalCandidates(ctx.hqRoot, ctx.company, wm);
+    const plan = [];
+    plan.push(`would pull ontology/projections/members/${memberUid}/v1/ into workspace/signals/projections/${ctx.company}/${memberUid}/v1/`);
+    let eligible = 0;
+    for (const c of candidates) {
+        let sourceRef = "";
+        try {
+            const fm = splitFrontmatter(fs.readFileSync(path.join(ctx.hqRoot, "companies", ctx.company, c.rel), "utf8")).frontmatter;
+            sourceRef = typeof fm.source_ref === "string" ? fm.source_ref : "";
+        }
+        catch {
+            // unreadable; reported below
+        }
+        if (!MEETING_SOURCE_RE.test(sourceRef)) {
+            plan.push(`skip ${c.rel}: non-meeting-source`);
+            continue;
+        }
+        eligible += 1;
+        plan.push(`would POST ${contributionRoute(ctx.company)} ${c.rel} -> member-signals/${memberUid}/observations/meetings/...`);
+    }
+    plan.push(`would upload up to ${eligible} sanitized observation(s); nothing uploaded (dry run)`);
+    return { ...base(), itemsIn: candidates.length, plan };
+}
+export function createUploadStep(overrides = {}) {
+    return {
+        name: "upload",
+        dryRun: planDryRun,
+        async run(ctx) {
+            const deps = { ...defaultUploadDeps, ...overrides, ...(ctx.uploadDeps ?? {}) };
+            if (ctx.dryRun)
+                return planDryRun(ctx);
+            const session = await deps.getSession(ctx.company);
+            if (!session) {
+                return { ...base(), skippedReason: "no-login", errorKind: "signed-out" };
+            }
+            let projection;
+            try {
+                memberProjectionPrefix(session.memberUid);
+                projection = await refreshMemberProjection({
+                    company: ctx.company,
+                    memberUid: session.memberUid,
+                    read: (key) => deps.readVaultObject(session, ctx.company, key),
+                    write: ctx.write,
+                    now: ctx.now,
+                });
+            }
+            catch (err) {
+                projection = { state: "missing", watermark: "none", entityCount: 0, error: err instanceof Error ? err.message : String(err) };
+            }
+            const exportTrigger = await triggerProjectionExport({ company: ctx.company, memberUid: session.memberUid });
+            const detail = {
+                projection: { state: projection.state, watermark: projection.watermark, entityCount: projection.entityCount, ...(projection.error ? { error: projection.error.slice(0, 200) } : {}) },
+                projectionExport: exportTrigger,
+            };
+            const wm = readWatermark(ctx.hqRoot, ctx.company, session.memberUid);
+            const candidates = listSignalCandidates(ctx.hqRoot, ctx.company, wm);
+            const companyRoot = path.join(ctx.hqRoot, "companies", ctx.company);
+            const url = `${session.baseUrl.replace(/\/+$/, "")}${contributionRoute(ctx.company)}`;
+            const skipped = {};
+            let count = 0;
+            let bytes = 0;
+            let transient = 0;
+            let rejected = 0;
+            let earliestRetryMs = Infinity;
+            let stop = null;
+            for (const c of candidates) {
+                const s = sanitizeSignal({
+                    companyRoot,
+                    signalRel: c.rel,
+                    memberUid: session.memberUid,
+                    companyUid: session.companyUid,
+                    projectionState: projection.state,
+                    projectionWatermark: projection.watermark,
+                });
+                if (!s.ok) {
+                    skipped[s.reason] = (skipped[s.reason] ?? 0) + 1;
+                    continue;
+                }
+                if (!s.destination.startsWith(`member-signals/${session.memberUid}/`)) {
+                    throw new Error("upload: destination outside the caller's member-signals prefix");
+                }
+                const body = JSON.stringify({ destination: s.destination, contribution: s.contribution });
+                let status;
+                let parsed;
+                try {
+                    const resp = await deps.fetch(url, {
+                        method: "POST",
+                        headers: {
+                            "Content-Type": "application/json",
+                            Authorization: `Bearer ${session.token}`,
+                            "x-hq-client-name": "@indigoai-us/hq-cli",
+                        },
+                        body,
+                    });
+                    status = resp.status;
+                    parsed = parseBody(await resp.text());
+                }
+                catch {
+                    transient += 1;
+                    earliestRetryMs = Math.min(earliestRetryMs, c.mtimeMs);
+                    continue;
+                }
+                if (status >= 200 && status < 300) {
+                    count += 1;
+                    bytes += Buffer.byteLength(body);
+                    wm.uploaded.push(c.sha);
+                    continue;
+                }
+                if (status === 401) {
+                    stop = { ...base(), skippedReason: "no-login", errorKind: "signed-out", error: "hq-pro returned 401" };
+                    break;
+                }
+                if (status === 403 && parsed.code === "CONTRIBUTION_DISABLED") {
+                    stop = { ...base(), skippedReason: "flag-off" };
+                    break;
+                }
+                // Company-wide answers: one request is enough, and the watermark holds
+                // so every signal goes once the company is reachable.
+                if (status === 404 && parsed.code === "WRITE_COMPANY_NOT_FOUND") {
+                    stop = { ...base(), status: "failed", error: "hq-pro has no company with this slug (WRITE_COMPANY_NOT_FOUND)", errorKind: "config" };
+                    break;
+                }
+                if (parsed.code === "WRITE_BUCKET_NOT_PROVISIONED") {
+                    stop = { ...base(), status: "failed", error: "the company vault is not provisioned yet (WRITE_BUCKET_NOT_PROVISIONED); will retry", errorKind: "transient" };
+                    break;
+                }
+                if ((status === 422 || status === 409 || status === 400) && !isRetryableRejection(parsed)) {
+                    rejected += 1;
+                    wm.rejected[c.sha] = parsed.code ?? `http-${status}`;
+                    continue;
+                }
+                if (status === 403) {
+                    stop = { ...base(), status: "failed", error: `hq-pro refused the contribution: ${parsed.code ?? "403"}`, errorKind: "other" };
+                    break;
+                }
+                transient += 1;
+                earliestRetryMs = Math.min(earliestRetryMs, c.mtimeMs);
+            }
+            if (stop && count === 0) {
+                // Keep the projection pull but write no watermark change.
+                return { ...stop, itemsIn: candidates.length, detail };
+            }
+            // Advance the watermark to the run start, except past a signal that
+            // must be retried.
+            const runStart = ctx.now().getTime();
+            const next = Number.isFinite(earliestRetryMs) ? Math.min(runStart, earliestRetryMs - 1) : runStart;
+            const prior = wm.lastUploadedAt ? Date.parse(wm.lastUploadedAt) : -Infinity;
+            if (!stop)
+                wm.lastUploadedAt = new Date(Math.max(prior, next)).toISOString();
+            wm.uploaded = wm.uploaded.slice(-MAX_TRACKED_SHAS);
+            ctx.write(watermarkRel(ctx.company, session.memberUid), `${JSON.stringify(wm, null, 2)}\n`);
+            const result = {
+                status: "ok",
+                itemsIn: candidates.length,
+                itemsOut: count,
+                uploaded: { count, bytes },
+                detail: { ...detail, rejected, skipped },
+            };
+            if (stop) {
+                return { ...stop, status: "partial", itemsIn: candidates.length, itemsOut: count, uploaded: { count, bytes }, detail: result.detail };
+            }
+            if (transient > 0) {
+                result.status = count > 0 ? "partial" : "failed";
+                result.error = `${transient} contribution(s) failed; will retry`;
+                result.errorKind = "transient";
+            }
+            else if (candidates.length === 0) {
+                result.status = "skipped";
+                result.skippedReason = "nothing-new";
+            }
+            return result;
+        },
+    };
+}
+export const uploadStep = createUploadStep();
+//# sourceMappingURL=upload.js.map

package/dist/lib/signals/write-guard.d.ts

@@ -0,0 +1,63 @@
+import type { WriteGuard } from "../hot-channels/loop.js";
+export declare class WriteGuardError extends Error {
+    constructor(message: string);
+}
+export interface WriteGuardScope {
+    /** Limit the companies/{co}/ roots to this company. */
+    company?: string;
+}
+/** True when anything (a dangling symlink included) exists at p. */
+export declare function lexists(p: string): boolean;
+/** Returns the resolved absolute target path or throws WriteGuardError. */
+export declare function assertAllowedPath(root: string, relPath: string, scope?: WriteGuardScope): string;
+export declare function guardedWrite(root: string, relPath: string, data: string, scope?: WriteGuardScope): void;
+/**
+ * One guard for both the signals engine and the hot-channel loop. It
+ * satisfies the WriteGuard interface in src/lib/hot-channels/loop.ts
+ * (beforeWrite) and adds the path-checked writer.
+ */
+export interface SignalsWriteGuard extends WriteGuard {
+    assertAllowed: (relPath: string) => string;
+    write: (relPath: string, data: string) => void;
+}
+export declare function createSignalsWriteGuard(root: string, beforeWrite?: () => Promise<void>, scope?: WriteGuardScope): SignalsWriteGuard;
+/**
+ * Delete one file through the same checks as a write: the path must sit in an
+ * allowed root (and, scoped, in that company's folder) after links are
+ * followed, and may not itself be a link. Throws WriteGuardError otherwise.
+ */
+export declare function guardedRemove(root: string, relPath: string, scope?: WriteGuardScope): void;
+/** Remove an empty directory through the guard. A link is refused, never removed or followed. */
+export declare function guardedRmdir(root: string, relPath: string, scope?: WriteGuardScope): void;
+/**
+ * The HQ-relative path an absolute path really points at, with every link
+ * followed (the file's own link included), or null when it does not exist or
+ * resolves outside the HQ root. Company ownership for a delete is decided on
+ * this path, never on the lexical one.
+ */
+export declare function realRelPath(root: string, absPath: string): string | null;
+/**
+ * Refuse, before anything writes there, a tree under relDir that holds a link
+ * leaving relDir's own allowed root (with scope.company, that company's
+ * folder). The walk uses lstat and does not descend through links. It covers
+ * writers that take no HQ-relative path (the hot-channel loop, the candidate
+ * script); it is a preflight, so a link created after it is not seen.
+ */
+export declare function assertNoEscapingLinks(root: string, relDir: string, scope?: WriteGuardScope): void;
+/**
+ * Guard for writers that hold an absolute vault root and an absolute file
+ * (the hot-channel loop: landing, cursors, ledger, sync lock, signals pass,
+ * alert state, push buffer cleanup). Call it before every write, rename,
+ * link or delete.
+ *
+ * When the vault root is `{hq}/companies/{co}`, the file goes through
+ * assertAllowedPath scoped to that company, the same check the signals engine
+ * uses: it must sit under the company's sources/, signals/ or ontology/ folder
+ * and stay there after links are followed. Any other vault root (a test
+ * folder, a person vault) gets the same rule against the vault itself: the
+ * file must be inside it lexically and after links are followed, the vault
+ * folder may not be a link, and the file may not be a link. Throws
+ * WriteGuardError otherwise.
+ */
+export declare function assertVaultPath(vaultRoot: string, file: string): string;
+//# sourceMappingURL=write-guard.d.ts.map

package/dist/lib/signals/write-guard.js

@@ -0,0 +1,287 @@
+/**
+ * Guarded writer for the signals engine. Refuses any path outside:
+ *   workspace/signals/, workspace/vault-staging/, personal/signals/,
+ *   companies/{co}/ontology/, companies/{co}/signals/, companies/{co}/sources/
+ * Rejects absolute paths, `..` segments, symlinked parents that resolve
+ * outside the HQ root or outside an allowed root, and symlinks (dangling ones
+ * too) at the target. Writes are atomic: a temp file under a random name
+ * opened with O_EXCL ("wx"), then a rename. With `scope.company` set, the
+ * companies/ roots are limited to that one company.
+ *
+ * A path must also resolve inside the same allowed root it names: after
+ * symlinks are followed, `workspace/signals/x` has to land under
+ * workspace/signals/, and `companies/{co}/signals/x` under
+ * companies/{co}/signals/. A link that moves a write into another root (most
+ * importantly into another company's folder) is refused, scoped or not.
+ */
+import { randomBytes } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+export class WriteGuardError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "WriteGuardError";
+    }
+}
+const ALLOWED = [
+    /^workspace\/signals\/.+/,
+    /^workspace\/vault-staging\/.+/,
+    /^personal\/signals\/.+/,
+    /^companies\/[^/]+\/ontology\/.+/,
+    /^companies\/[^/]+\/signals\/.+/,
+    /^companies\/[^/]+\/sources\/.+/,
+];
+function allowedRoot(rel, scope) {
+    const root = ALLOWED.findIndex((re) => re.test(rel));
+    if (root < 0)
+        return null;
+    if (!rel.startsWith("companies/"))
+        return { root };
+    const company = rel.split("/")[1];
+    // Exact, case-sensitive match: on a case-insensitive volume two spellings
+    // of a slug are one folder, so anything but the exact slug fails closed.
+    if (scope.company !== undefined && company !== scope.company)
+        return null;
+    return { root, company };
+}
+function sameRoot(a, b) {
+    return a.root === b.root && a.company === b.company;
+}
+/** True when anything (a dangling symlink included) exists at p. */
+export function lexists(p) {
+    try {
+        fs.lstatSync(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** The first HQ-relative prefix of rel that is a symlink, for error messages. */
+function firstLinkedSegment(realRoot, rel) {
+    const parts = rel.split("/");
+    for (let i = 1; i <= parts.length; i += 1) {
+        const prefix = parts.slice(0, i).join("/");
+        try {
+            if (fs.lstatSync(path.join(realRoot, prefix)).isSymbolicLink())
+                return prefix;
+        }
+        catch {
+            return null;
+        }
+    }
+    return null;
+}
+/** Returns the resolved absolute target path or throws WriteGuardError. */
+export function assertAllowedPath(root, relPath, scope = {}) {
+    if (!relPath || path.isAbsolute(relPath) || /^[a-zA-Z]:/.test(relPath)) {
+        throw new WriteGuardError(`write-guard: path must be HQ-root relative: ${relPath}`);
+    }
+    const segments = relPath.split(/[\\/]+/);
+    if (segments.includes("..")) {
+        throw new WriteGuardError(`write-guard: path traversal rejected: ${relPath}`);
+    }
+    const rel = segments.filter((s) => s && s !== ".").join("/");
+    const lexicalRoot = allowedRoot(rel, scope);
+    if (!lexicalRoot) {
+        throw new WriteGuardError(`write-guard: path outside allowed roots: ${relPath}`);
+    }
+    const realRoot = fs.realpathSync(root);
+    const target = path.join(realRoot, rel);
+    // Resolve the nearest existing ancestor so a symlinked parent cannot escape.
+    // lexists, not existsSync: existsSync follows links, so a dangling link
+    // would read as absent and skip the check.
+    let ancestor = path.dirname(target);
+    const rest = [path.basename(target)];
+    while (!lexists(ancestor)) {
+        rest.unshift(path.basename(ancestor));
+        ancestor = path.dirname(ancestor);
+    }
+    let realAncestor;
+    try {
+        realAncestor = fs.realpathSync(ancestor);
+    }
+    catch {
+        throw new WriteGuardError(`write-guard: dangling symlink in path: ${relPath}`);
+    }
+    const resolved = path.join(realAncestor, ...rest);
+    const resolvedRel = path.relative(realRoot, resolved).split(path.sep).join("/");
+    if (resolvedRel.startsWith("..") || path.isAbsolute(resolvedRel)) {
+        throw new WriteGuardError(`write-guard: symlink escape rejected: ${relPath}`);
+    }
+    // Unscoped here so the error can name the root it landed in; sameRoot below
+    // ties it back to the lexical root, which already passed the scope check.
+    const resolvedRoot = allowedRoot(resolvedRel, {});
+    if (!resolvedRoot) {
+        throw new WriteGuardError(`write-guard: symlink escape rejected: ${relPath}`);
+    }
+    // A scoped write outside companies/ (workspace/signals/runs/{date}/{co}.json,
+    // watermarks/{co}/, projections/{co}/ and so on) names its company somewhere
+    // below the root, where the root check cannot see it. Hold it to its exact
+    // path: no link at all below the HQ root, so another company's state there
+    // cannot be reached through one.
+    const linkedWithinScopedWorkspace = scope.company !== undefined && lexicalRoot.company === undefined && resolvedRel !== rel;
+    if (linkedWithinScopedWorkspace && sameRoot(lexicalRoot, resolvedRoot)) {
+        throw new WriteGuardError(`write-guard: ${relPath} passes through a link at ${firstLinkedSegment(realRoot, rel) ?? "an unknown segment"}; ` +
+            "a company-scoped signals write may not pass through a link inside the HQ root");
+    }
+    if (!sameRoot(lexicalRoot, resolvedRoot) || linkedWithinScopedWorkspace) {
+        const where = resolvedRoot.company !== undefined ? `company ${resolvedRoot.company}'s folder` : resolvedRel;
+        throw new WriteGuardError(`write-guard: ${relPath} resolves through a link into ${where}; refusing a write that leaves its own root`);
+    }
+    if (lexists(resolved) && fs.lstatSync(resolved).isSymbolicLink()) {
+        throw new WriteGuardError(`write-guard: refusing to write through symlink: ${relPath}`);
+    }
+    return resolved;
+}
+export function guardedWrite(root, relPath, data, scope = {}) {
+    const abs = assertAllowedPath(root, relPath, scope);
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    const tmp = `${abs}.tmp-${process.pid}-${randomBytes(6).toString("hex")}`;
+    // "wx" is O_CREAT|O_EXCL: it fails on any existing entry, symlinks included.
+    fs.writeFileSync(tmp, data, { flag: "wx" });
+    try {
+        fs.renameSync(tmp, abs);
+    }
+    catch (err) {
+        fs.rmSync(tmp, { force: true });
+        throw err;
+    }
+}
+export function createSignalsWriteGuard(root, beforeWrite, scope = {}) {
+    return {
+        beforeWrite: beforeWrite ?? (async () => { }),
+        assertAllowed: (relPath) => assertAllowedPath(root, relPath, scope),
+        write: (relPath, data) => {
+            guardedWrite(root, relPath, data, scope);
+        },
+    };
+}
+/**
+ * Delete one file through the same checks as a write: the path must sit in an
+ * allowed root (and, scoped, in that company's folder) after links are
+ * followed, and may not itself be a link. Throws WriteGuardError otherwise.
+ */
+export function guardedRemove(root, relPath, scope = {}) {
+    const abs = assertAllowedPath(root, relPath, scope);
+    fs.rmSync(abs, { force: true });
+}
+/** Remove an empty directory through the guard. A link is refused, never removed or followed. */
+export function guardedRmdir(root, relPath, scope = {}) {
+    const abs = assertAllowedPath(root, relPath, scope);
+    fs.rmdirSync(abs);
+}
+/**
+ * The HQ-relative path an absolute path really points at, with every link
+ * followed (the file's own link included), or null when it does not exist or
+ * resolves outside the HQ root. Company ownership for a delete is decided on
+ * this path, never on the lexical one.
+ */
+export function realRelPath(root, absPath) {
+    let real;
+    try {
+        real = fs.realpathSync(absPath);
+    }
+    catch {
+        return null;
+    }
+    const rel = path.relative(fs.realpathSync(root), real);
+    if (!rel || rel.startsWith("..") || path.isAbsolute(rel))
+        return null;
+    return rel.split(path.sep).join("/");
+}
+/**
+ * Refuse, before anything writes there, a tree under relDir that holds a link
+ * leaving relDir's own allowed root (with scope.company, that company's
+ * folder). The walk uses lstat and does not descend through links. It covers
+ * writers that take no HQ-relative path (the hot-channel loop, the candidate
+ * script); it is a preflight, so a link created after it is not seen.
+ */
+export function assertNoEscapingLinks(root, relDir, scope = {}) {
+    const probe = (rel) => {
+        assertAllowedPath(root, `${rel}/.write-guard-probe`, scope);
+    };
+    probe(relDir);
+    const realRoot = fs.realpathSync(root);
+    const walk = (rel) => {
+        let entries;
+        try {
+            entries = fs.readdirSync(path.join(realRoot, rel), { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            const child = `${rel}/${e.name}`;
+            if (e.isSymbolicLink())
+                probe(child);
+            else if (e.isDirectory())
+                walk(child);
+        }
+    };
+    walk(relDir);
+}
+/**
+ * realpath of the nearest existing ancestor of an absolute path, with the
+ * missing tail appended. A dangling link on the way fails closed.
+ */
+function resolveNearest(abs, label) {
+    let ancestor = abs;
+    const rest = [];
+    while (!lexists(ancestor)) {
+        const parent = path.dirname(ancestor);
+        if (parent === ancestor)
+            break;
+        rest.unshift(path.basename(ancestor));
+        ancestor = parent;
+    }
+    try {
+        return path.join(fs.realpathSync(ancestor), ...rest);
+    }
+    catch {
+        throw new WriteGuardError(`write-guard: dangling symlink in path: ${label}`);
+    }
+}
+/**
+ * Guard for writers that hold an absolute vault root and an absolute file
+ * (the hot-channel loop: landing, cursors, ledger, sync lock, signals pass,
+ * alert state, push buffer cleanup). Call it before every write, rename,
+ * link or delete.
+ *
+ * When the vault root is `{hq}/companies/{co}`, the file goes through
+ * assertAllowedPath scoped to that company, the same check the signals engine
+ * uses: it must sit under the company's sources/, signals/ or ontology/ folder
+ * and stay there after links are followed. Any other vault root (a test
+ * folder, a person vault) gets the same rule against the vault itself: the
+ * file must be inside it lexically and after links are followed, the vault
+ * folder may not be a link, and the file may not be a link. Throws
+ * WriteGuardError otherwise.
+ */
+export function assertVaultPath(vaultRoot, file) {
+    const absVault = path.resolve(vaultRoot);
+    const absFile = path.resolve(absVault, file);
+    const rel = path.relative(absVault, absFile);
+    if (!rel || rel.startsWith("..") || path.isAbsolute(rel)) {
+        throw new WriteGuardError(`write-guard: ${file} is outside the vault ${vaultRoot}`);
+    }
+    const relPosix = rel.split(path.sep).join("/");
+    const company = path.basename(absVault);
+    if (path.basename(path.dirname(absVault)) === "companies" && company) {
+        const hqRoot = path.dirname(path.dirname(absVault));
+        return assertAllowedPath(hqRoot, ["companies", company, relPosix].join("/"), { company });
+    }
+    if (lexists(absVault) && fs.lstatSync(absVault).isSymbolicLink()) {
+        throw new WriteGuardError(`write-guard: vault root ${vaultRoot} is a link`);
+    }
+    const realVault = resolveNearest(absVault, vaultRoot);
+    const resolved = resolveNearest(absFile, file);
+    const inside = path.relative(realVault, resolved);
+    if (!inside || inside.startsWith("..") || path.isAbsolute(inside)) {
+        throw new WriteGuardError(`write-guard: ${file} resolves through a link outside the vault ${vaultRoot}`);
+    }
+    if (lexists(absFile) && fs.lstatSync(absFile).isSymbolicLink()) {
+        throw new WriteGuardError(`write-guard: refusing to write through symlink: ${file}`);
+    }
+    return resolved;
+}
+//# sourceMappingURL=write-guard.js.map