@indigoai-us/hq-cloud 6.15.0 → 6.15.2

package/src/sync/pull-scope.ts

@@ -1,265 +0,0 @@
-/**
- * Effective per-company PULL scope resolution (US-005), shared between
- * `hq-sync-runner` (the menubar's background sync) and `hq sync pull|now`
- * (the hq-cli foreground sync).
- *
- * BACKGROUND — why this lives in one place. The runner historically owned
- * this resolver while hq-cli's pull paths resolved the membership's sync-mode
- * only to drive the narrow-hint banner and then called `sync()` WITHOUT a
- * `syncMode`/`prefixSet`. That meant every hq-cli pull silently ran
- * `syncMode: "all"` and stamped an `all`-mode `PullRecord` (prefixSet `[""]`)
- * — even for a membership whose real mode is `shared`/`custom`. For an owner
- * (whose STS is wide by role-bypass) that journals the WHOLE company. The next
- * menubar runner sync then resolves the REAL narrowed scope, scope-shrinks
- * against the seeded `[""]`, and — if any out-of-scope file was edited locally
- * — throws `ScopeShrinkBlockedError(all → shared)` and exits 2 on every
- * subsequent run: a permanent wedge (DEV-1768 / feedback_f7663e92).
- *
- * The two surfaces drifting apart is exactly what caused the wedge, so the
- * resolver is defined ONCE here and consumed by both. Any future change to how
- * scope is derived now lands for the runner and the CLI in lockstep.
- *
- * SESSIONS ARE PUSH-ONLY (US-006). Session transcripts are pushed by clients
- * into the company vault under `sessions/{personUid}/...`, but the sync engine
- * NEVER auto-pulls that prefix onto grantee laptops — in EVERY sync mode,
- * including `all` (which otherwise means a full-bucket pull) and an owner's
- * role-wide scope. That never-pull contract is expressed HERE as
- * `PullScope.excludePrefixes` (always carrying {@link SESSIONS_SCOPE_PREFIX}),
- * NOT in `ignore.ts` (which only filters the push-side walk — sessions MUST
- * still upload). A specific session is materialized on demand via `hq files
- * get`, which pins the key so it survives scope-shrink pruning. The exclude set
- * is subtracted from the pull's download filter but is deliberately NOT fed
- * into scope-shrink, so a locally-authored (`direction:"up"`) or pinned
- * on-demand-materialized session is never orphaned. See `computePullPlan`
- * (subtraction) and `scope-shrink.ts` (retention).
- */
-import * as fs from "fs";
-import * as path from "path";
-import {
-  coalescePrefixes,
-  grantPathToScopePrefix,
-  pathToScopePrefix,
-} from "../prefix-coalesce.js";
-import type {
-  ExplicitGrant,
-  MembershipSyncConfig,
-  SyncMode,
-} from "../vault-client.js";
-
-/**
- * Minimal structural surface `resolvePullScope` needs. Both the runner's
- * `VaultClientSurface` and hq-cli's concrete `VaultClient` satisfy it, so
- * either can be passed without an adapter.
- */
-export interface PullScopeClient {
-  listMyMemberships(): Promise<
-    Array<{ companyUid: string; membershipKey: string; role?: string }>
-  >;
-  getMembershipSyncConfig?: (
-    membershipId: string,
-  ) => Promise<MembershipSyncConfig>;
-  listMyExplicitGrants?: (companyUid: string) => Promise<ExplicitGrant[]>;
-}
-
-/**
- * Effective download scope for one company leg (US-005). Resolved per company
- * just before its pull, then handed to `sync()` as `{ syncMode, prefixSet }`.
- */
-export interface PullScope {
-  syncMode: SyncMode;
-  /** Coalesced company-relative prefixes; omitted/undefined for `all`. */
-  prefixSet?: string[];
-  /**
-   * Company-relative prefixes subtracted from the effective PULL scope in
-   * EVERY mode — the push-only set. Always carries {@link SESSIONS_SCOPE_PREFIX}
-   * (US-006): session transcripts are pushed into the vault but never
-   * auto-pulled onto grantee laptops, even under `all`/owner scope. A key is
-   * downloaded iff it is covered by the inclusion `prefixSet` (or `all`) AND
-   * NOT covered by any `excludePrefixes` entry. Distinct from `prefixSet` and
-   * deliberately NOT fed into scope-shrink, so a locally-authored or pinned
-   * on-demand-materialized session is never pruned. Stamped on every
-   * `resolvePullScope` return via {@link sessionsPushOnlyScope}.
-   */
-  excludePrefixes: string[];
-}
-
-/**
- * Company-relative prefix under which session transcripts are pushed
- * (`sessions/{personUid}/...`). Push-only by contract (US-006): a client
- * uploads its own session transcripts here, but the sync engine NEVER
- * auto-pulls this prefix onto grantee laptops — in ANY sync mode, including
- * `all`. Materializing a specific session is an on-demand action (`hq files
- * get`), which pins the key so it survives scope-shrink pruning.
- */
-export const SESSIONS_SCOPE_PREFIX = "sessions/";
-
-/**
- * Stamp the push-only session exclusion onto a resolved scope. Centralized so
- * NO `resolvePullScope` return site can silently regress to a full session pull
- * (the architect's flagged risk): the exclusion rides EVERY mode — `all`,
- * owner→all, agent→all, config-all, shared, custom, and every degrade-to-`all`
- * path — because each return is built through this helper.
- */
-function sessionsPushOnlyScope(
-  scope: Omit<PullScope, "excludePrefixes">,
-): PullScope {
-  return { ...scope, excludePrefixes: [SESSIONS_SCOPE_PREFIX] };
-}
-
-/**
- * Resolve the effective download scope for a company target.
- *
- *   - `all`    → no prefix set; full-bucket pull (legacy behavior).
- *   - `shared` → coalesced caller explicit grants (company-relative paths,
- *                same namespace as `RemoteFile.key`).
- *   - `custom` → coalesced `customPaths` from the sync-config row.
- *
- * DEGRADE-TO-`all` CONTRACT: any failure (missing client method, membership
- * not found, network error, grant fetch error) returns `{ syncMode: "all" }`.
- * A transient failure must NEVER silently narrow scope — that would prune the
- * local tree. A genuinely-empty grant list (the method exists and returns `[]`)
- * is a real "nothing shared with me" and IS allowed to narrow.
- */
-export async function resolvePullScope(
-  client: PullScopeClient,
-  companyUid: string,
-  // Company slug — required to normalize grant paths (which may be anchored
-  // at `companies/<slug>/` or `<slug>/`) into the company-relative namespace.
-  slug: string,
-  // Local HQ root — used to read the per-machine pin set (`.hq/pins.json`).
-  // When omitted, pins are simply not unioned (no behavior change).
-  hqRoot?: string,
-): Promise<PullScope> {
-  if (!client.getMembershipSyncConfig) return sessionsPushOnlyScope({ syncMode: "all" });
-  try {
-    const memberships = await client.listMyMemberships();
-    const m = memberships.find((x) => x.companyUid === companyUid);
-    if (!m) return sessionsPushOnlyScope({ syncMode: "all" });
-    // OWNER role-bypass (feedback_67bdb8a4 / feedback_a46c3b37). An owner's
-    // effective vault access is the WHOLE company by role — the data plane
-    // resolves owner to `admin` on every key (`resolveEffectivePermission`'s
-    // role bypass; presign's `viewOthersFiles` is unconditional for owners).
-    // But the scope resolution below derives `shared` scope from
-    // `listMyExplicitGrants`, and that endpoint DELIBERATELY EXCLUDES the
-    // owner/admin role bypass — it answers "what is explicitly shared with
-    // me", not "what can I touch by role" (see hq-pro files-grants handler).
-    // An owner who owns by role (not by explicit grant) therefore resolves to
-    // an empty/sparse prefixSet, so the push uploads NOTHING (every path is
-    // filtered out by `wrapFilterWithScope`) and any in-role write — including
-    // a brand-new top-level project prefix the owner just created — is rejected
-    // by the server as `403 SCOPE_EXCEEDS_PARENT`. An owner has no meaningful
-    // "shared subset": they own everything, so their effective sync scope IS
-    // the full vault. Resolve them to `all` directly — restoring the pre-
-    // pull-scope-refactor behavior (owners always journaled the whole company).
-    // This is checked BEFORE the sync-config fetch so it holds even if a stray
-    // `shared` row exists for the owner. A `custom` choice would also be
-    // overridden here, which is intentional: an owner cannot be scoped below
-    // their role on the sync path without the server rejecting their own
-    // writes. Non-owner roles fall through to the grant-based resolution
-    // below — a member/guest's explicit grants ARE their full footprint, and a
-    // (conditionally bypassed) admin stays grant-scoped so a company that set
-    // `admin.viewOthersFiles=false` keeps its admins narrowed.
-    if (m.role === "owner") return sessionsPushOnlyScope({ syncMode: "all" });
-    // Agent memberships (`agt_…#cmp_…`) belong to an agent identity that owns NO
-    // person entity. hq-pro's per-membership sync-config endpoint sits behind an
-    // up-front person-gate, so an agent caller is rejected with
-    // `403 "Caller has no person entity — call POST /entity with type=person
-    // first"` BEFORE the route's own ownership check ever runs — captured
-    // server-side as the Sentry warning HQ-1R (one event per agent sync pass).
-    // Agents never set a scoped sync-config (that is a human-only menubar
-    // action) and a failed/absent config already degrades to `all` here, so the
-    // call is guaranteed to 403 and change nothing. Skip it for agent
-    // memberships and resolve `all` directly — behavior-preserving, minus the
-    // 403 spam. (A server-side alternative would be to exempt sync-config from
-    // the up-front person-gate and let its own `authorizeSyncConfigAccess`
-    // handle agent ownership; tracked as a possible follow-up.)
-    if (m.membershipKey?.startsWith("agt_")) return sessionsPushOnlyScope({ syncMode: "all" });
-    const cfg = await client.getMembershipSyncConfig(m.membershipKey);
-    if (cfg.syncMode === "all") return sessionsPushOnlyScope({ syncMode: "all" });
-
-    // Pins are company-relative prefixes a user explicitly materialized via
-    // `hq files get`. They're unioned into the scope so a scoped pull keeps
-    // them instead of pruning them as out-of-scope orphans. Pins only WIDEN
-    // scope, never narrow — and `all` mode (handled above) ignores them since
-    // it pulls everything anyway.
-    const pinPrefixes = hqRoot ? readPinnedPrefixes(hqRoot, slug) : [];
-
-    if (cfg.syncMode === "custom") {
-      const customPrefixes = (cfg.customPaths ?? []).map((p) =>
-        grantPathToScopePrefix(p, slug),
-      );
-      // A bare-everything entry ("" — e.g. a `*` path) collapses under
-      // `coalescePrefixes` (which drops empties) to "nothing", which would
-      // prune the whole tree. An everything-scope is semantically `all`.
-      if (customPrefixes.some((p) => p.prefix === "")) {
-        return sessionsPushOnlyScope({ syncMode: "all" });
-      }
-      return sessionsPushOnlyScope({
-        syncMode: "custom",
-        prefixSet: coalescePrefixes([
-          ...customPrefixes,
-          ...pinPrefixes.map(pathToScopePrefix),
-        ]),
-      });
-    }
-    // shared: scope to the caller's explicit grants. Real grant paths are
-    // inconsistent — full (`companies/<slug>/x/*`), slug-anchored
-    // (`<slug>/x/*`), company-relative (`x/*`), bare globs (`*`), and exact
-    // files all coexist in production — so each is normalized via
-    // `grantPathToPrefix` into a company-relative, startsWith-friendly prefix
-    // (the namespace the engine's `RemoteFile.key`s live in) before coalescing.
-    //
-    // SAFETY: if the client can't fetch grants, we must NOT fall through to an
-    // empty `shared` scope — that would tell the engine "nothing is in scope"
-    // and scope-shrink would prune every clean local file. Degrade to `all`
-    // instead. A genuinely-empty grant list (the method exists and returns
-    // []) is a real "nothing shared with me" and is allowed to narrow.
-    if (!client.listMyExplicitGrants) return sessionsPushOnlyScope({ syncMode: "all" });
-    const grants = await client.listMyExplicitGrants(companyUid);
-    const sharedPrefixes = grants.map((g) =>
-      grantPathToScopePrefix(g.path, slug),
-    );
-    // A wildcard grant (`*`) normalizes to "" = everything. Since
-    // `coalescePrefixes` drops empties (collapsing "everything" to "nothing"),
-    // treat any such grant as full-access `all` rather than risk pruning.
-    if (sharedPrefixes.some((p) => p.prefix === "")) {
-      return sessionsPushOnlyScope({ syncMode: "all" });
-    }
-    return sessionsPushOnlyScope({
-      syncMode: "shared",
-      prefixSet: coalescePrefixes([
-        ...sharedPrefixes,
-        ...pinPrefixes.map(pathToScopePrefix),
-      ]),
-    });
-  } catch {
-    // Degrade to `all` — never prune on a resolution failure.
-    return sessionsPushOnlyScope({ syncMode: "all" });
-  }
-}
-
-/**
- * Read the per-machine pin set (`<hqRoot>/.hq/pins.json`) and return the
- * company-relative pinned prefixes for `slug`. These are prefixes the user
- * materialized on demand via `hq files get` that must survive a scoped pull.
- *
- * Tolerant by construction: a missing, unreadable, or malformed file yields
- * `[]` (no pins) — pins only ever widen scope, so "no pins" is the safe
- * default. Empty-string entries are dropped (an everything-pin is meaningless
- * here; `all` mode already covers that case).
- */
-export function readPinnedPrefixes(hqRoot: string, slug: string): string[] {
-  try {
-    const raw = fs.readFileSync(path.join(hqRoot, ".hq", "pins.json"), "utf-8");
-    const parsed = JSON.parse(raw) as { pins?: Record<string, unknown> };
-    const list = parsed?.pins?.[slug];
-    if (Array.isArray(list)) {
-      return list.filter(
-        (p): p is string => typeof p === "string" && p.length > 0,
-      );
-    }
-  } catch {
-    /* missing / unreadable / malformed → no pins */
-  }
-  return [];
-}

package/src/sync/push-event.test.ts

@@ -1,266 +0,0 @@
-/**
- * Unit tests for `src/sync/push-event.ts` (US-007 port).
- *
- * Covers the three required acceptance assertions:
- *  1. A known-good fixture round-trips through encode → decode unchanged.
- *  2. Unknown extra fields on the input are dropped silently (no throw).
- *  3. Missing required fields throw a typed `PushEventDecodeError` whose
- *     `.issues` exposes the underlying zod issues.
- *
- * Also covers the supporting invariants needed to keep the wire contract
- * stable across the watcher → server → receiver hop: malformed JSON, bad
- * hash/timestamp formats, and the integer/range bounds on `sequenceNumber`.
- */
-
-import { describe, expect, it } from "vitest";
-
-import {
-  PushEventDecodeError,
-  decodePushEvent,
-  encodePushEvent,
-  type PushEvent,
-  type PushEventInput,
-} from "../../src/sync/index.js";
-
-// A canonical, valid PushEvent. All other tests derive from this fixture so
-// any single field mutation can't accidentally pass for the wrong reason.
-const validFixture: PushEvent = {
-  relativePath: "docs/architecture/overview.md",
-  kind: "upsert",
-  contentHash:
-    "sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
-  mtime: "2026-05-18T12:34:56.789Z",
-  originDeviceId: "device-laptop-a",
-  originTenantId: "tenant-indigo",
-  sequenceNumber: 42,
-  eventTimestamp: "2026-05-18T12:35:00.000Z",
-};
-
-const deleteFixture: PushEvent = {
-  relativePath: "docs/architecture/overview.md",
-  kind: "delete",
-  originDeviceId: "device-laptop-a",
-  originTenantId: "tenant-indigo",
-  sequenceNumber: 43,
-  eventTimestamp: "2026-05-18T12:36:00.000Z",
-};
-
-describe("PushEvent encode/decode", () => {
-  // ── Acceptance #1: round-trip ──────────────────────────────────────────
-  it("round-trips a known-good fixture through encode → decode", () => {
-    const encoded = encodePushEvent(validFixture);
-    expect(typeof encoded).toBe("string");
-
-    const decoded = decodePushEvent(encoded);
-    expect(decoded).toEqual(validFixture);
-
-    // Re-encoding the decoded value must produce byte-identical output —
-    // catches accidental field re-ordering or coercion drift.
-    expect(encodePushEvent(decoded)).toBe(encoded);
-  });
-
-  it("decodes from a pre-parsed object as well as from a JSON string", () => {
-    const fromObject = decodePushEvent({ ...validFixture });
-    const fromString = decodePushEvent(JSON.stringify(validFixture));
-    expect(fromObject).toEqual(validFixture);
-    expect(fromString).toEqual(validFixture);
-  });
-
-  it("round-trips a delete tombstone without contentHash or mtime", () => {
-    const encoded = encodePushEvent(deleteFixture);
-    expect(JSON.parse(encoded)).toEqual(deleteFixture);
-    expect(decodePushEvent(encoded)).toEqual(deleteFixture);
-  });
-
-  it("defaults an absent kind to upsert for backward compatibility", () => {
-    const legacy = { ...validFixture } as PushEventInput;
-    delete legacy.kind;
-
-    const decoded = decodePushEvent(legacy);
-    expect(decoded).toEqual(validFixture);
-    expect(JSON.parse(encodePushEvent(legacy))).toEqual(validFixture);
-  });
-
-  // ── Acceptance #2: unknown fields dropped ──────────────────────────────
-  it("drops unknown extra fields silently (does not throw)", () => {
-    const withExtras = {
-      ...validFixture,
-      // Future producers may add fields like `originAppVersion`; today's
-      // consumers must not crash on them.
-      originAppVersion: "1.2.3",
-      experimentalFlag: true,
-      nested: { ignored: "yes" },
-    };
-
-    const decoded = decodePushEvent(withExtras);
-    expect(decoded).toEqual(validFixture);
-    expect(decoded).not.toHaveProperty("originAppVersion");
-    expect(decoded).not.toHaveProperty("experimentalFlag");
-    expect(decoded).not.toHaveProperty("nested");
-
-    // Round-tripping through JSON behaves the same way.
-    const decodedFromJson = decodePushEvent(JSON.stringify(withExtras));
-    expect(decodedFromJson).toEqual(validFixture);
-  });
-
-  // ── Acceptance #3: missing required fields throw typed error ───────────
-  it.each([
-    "relativePath",
-    "originDeviceId",
-    "originTenantId",
-    "sequenceNumber",
-    "eventTimestamp",
-  ] as const)("throws PushEventDecodeError when %s is missing", (field) => {
-    const partial: Record<string, unknown> = { ...validFixture };
-    delete partial[field];
-
-    let caught: unknown;
-    try {
-      decodePushEvent(partial);
-    } catch (err) {
-      caught = err;
-    }
-
-    expect(caught).toBeInstanceOf(PushEventDecodeError);
-    const error = caught as PushEventDecodeError;
-    expect(error.stage).toBe("schema-validation");
-    expect(error.issues.length).toBeGreaterThan(0);
-    // The zod issue path must point at the missing field — that's what
-    // downstream callers rely on to render structured diagnostics.
-    expect(error.issues.some((issue) => issue.path.includes(field))).toBe(true);
-  });
-
-  it("rejects an upsert without contentHash and mtime via the schema refinement", () => {
-    let caught: unknown;
-    try {
-      decodePushEvent({
-        ...validFixture,
-        contentHash: undefined,
-        mtime: undefined,
-      });
-    } catch (err) {
-      caught = err;
-    }
-
-    expect(caught).toBeInstanceOf(PushEventDecodeError);
-    const error = caught as PushEventDecodeError;
-    expect(error.stage).toBe("schema-validation");
-    expect(error.issues.some((issue) => issue.message === "upsert requires contentHash and mtime")).toBe(true);
-  });
-
-  it("PushEventDecodeError carries the underlying zod issues array", () => {
-    // Multiple missing fields → multiple issues, all reachable via `.issues`.
-    const sparse = { relativePath: "x.md" } as unknown;
-    let caught: unknown;
-    try {
-      decodePushEvent(sparse);
-    } catch (err) {
-      caught = err;
-    }
-    expect(caught).toBeInstanceOf(PushEventDecodeError);
-    const error = caught as PushEventDecodeError;
-    expect(error.issues.length).toBeGreaterThanOrEqual(4);
-  });
-
-  // ── Supporting wire-contract invariants ────────────────────────────────
-  it("throws PushEventDecodeError on malformed JSON input", () => {
-    let caught: unknown;
-    try {
-      decodePushEvent("{not valid json");
-    } catch (err) {
-      caught = err;
-    }
-    expect(caught).toBeInstanceOf(PushEventDecodeError);
-    const error = caught as PushEventDecodeError;
-    expect(error.stage).toBe("json-parse");
-    expect(error.issues.length).toBe(1);
-  });
-
-  it("surfaces a JSON-parseable non-object payload as schema-validation, not json-parse", () => {
-    // `'42'` is syntactically valid JSON, so the parse stage clears; the
-    // object-shape check is what fails. Pinning this here keeps the JSDoc
-    // contract (see decodePushEvent docs) honest.
-    let caught: unknown;
-    try {
-      decodePushEvent("42");
-    } catch (err) {
-      caught = err;
-    }
-    expect(caught).toBeInstanceOf(PushEventDecodeError);
-    const error = caught as PushEventDecodeError;
-    expect(error.stage).toBe("schema-validation");
-  });
-
-  it.each([
-    ["raw hex without `sha256:` prefix", "e".repeat(64)],
-    ["wrong algorithm prefix", `md5:${"a".repeat(64)}`],
-    ["uppercase hex", `sha256:${"A".repeat(64)}`],
-    ["too few hex chars", `sha256:${"a".repeat(63)}`],
-  ])("rejects contentHash: %s", (_label, badHash) => {
-    expect(() =>
-      decodePushEvent({ ...validFixture, contentHash: badHash }),
-    ).toThrow(PushEventDecodeError);
-  });
-
-  it.each([
-    ["missing timezone", "2026-05-18T12:34:56.789"],
-    ["space separator", "2026-05-18 12:34:56Z"],
-    ["date only", "2026-05-18"],
-  ])("rejects ISO-8601 timestamps: %s", (_label, badTimestamp) => {
-    expect(() =>
-      decodePushEvent({ ...validFixture, mtime: badTimestamp }),
-    ).toThrow(PushEventDecodeError);
-    expect(() =>
-      decodePushEvent({ ...validFixture, eventTimestamp: badTimestamp }),
-    ).toThrow(PushEventDecodeError);
-  });
-
-  it("accepts a sequenceNumber of 0 and rejects negative / fractional / oversized values", () => {
-    // 0 is allowed — sequence numbers are non-negative, not strictly positive.
-    expect(decodePushEvent({ ...validFixture, sequenceNumber: 0 })).toEqual({
-      ...validFixture,
-      sequenceNumber: 0,
-    });
-
-    expect(() =>
-      decodePushEvent({ ...validFixture, sequenceNumber: -1 }),
-    ).toThrow(PushEventDecodeError);
-    expect(() =>
-      decodePushEvent({ ...validFixture, sequenceNumber: 1.5 }),
-    ).toThrow(PushEventDecodeError);
-    expect(() =>
-      decodePushEvent({
-        ...validFixture,
-        sequenceNumber: Number.MAX_SAFE_INTEGER + 1,
-      }),
-    ).toThrow(PushEventDecodeError);
-  });
-
-  it("encodePushEvent validates and drops unknown fields from the output", () => {
-    // We cast through `unknown` because the public type forbids extra keys —
-    // this models a producer that hands us a wider object by mistake.
-    const wider = {
-      ...validFixture,
-      stray: "field",
-    } as unknown as PushEvent;
-    const encoded = encodePushEvent(wider);
-    expect(encoded.includes("stray")).toBe(false);
-    expect(JSON.parse(encoded)).toEqual(validFixture);
-  });
-
-  it("encodePushEvent throws PushEventDecodeError when input is invalid", () => {
-    const bad = { ...validFixture, contentHash: "not-a-hash" } as PushEvent;
-    let caught: unknown;
-    try {
-      encodePushEvent(bad);
-    } catch (err) {
-      caught = err;
-    }
-    expect(caught).toBeInstanceOf(PushEventDecodeError);
-    const error = caught as PushEventDecodeError;
-    expect(error.stage).toBe("schema-validation");
-    expect(
-      error.issues.some((issue) => issue.path.includes("contentHash")),
-    ).toBe(true);
-  });
-});