@indigoai-us/hq-cloud 5.22.0 → 5.24.0

package/src/types.ts

@@ -34,12 +34,60 @@ export interface JournalEntry {
    * against `syncedAt`.
    */
   remoteEtag?: string;
+  /**
+   * Tombstone marker (Journal v2, US-005). When set, this entry represents
+   * a file that was pruned by a scope shrink — either implicitly (next pull
+   * after the membership's effective scope narrowed) or explicitly (via
+   * `hq sync narrow --apply`). Tombstones are kept for `TOMBSTONE_TTL_MS`
+   * (30d) so subsequent pulls under the same shrunk scope don't re-flag
+   * the same paths as orphans, then garbage-collected.
+   */
+  removedAt?: string;
+  removedReason?: "scope_shrink" | "narrow_apply" | "manual";
+}
+
+/**
+ * Per-pull boundary record (Journal v2, US-005).
+ *
+ * Recorded at the end of every per-company sync leg so the next pull can
+ * detect "scope changed" against `prefixSet` and compute orphans
+ * deterministically. `pulls[]` is append-only; old records are not pruned
+ * (cheap, useful for incident forensics — one row per pull per company).
+ */
+export interface PullRecord {
+  /** ULID-shaped id (crockford base32, lexically sortable). */
+  pullId: string;
+  companyUid: string;
+  startedAt: string;
+  completedAt: string;
+  /** Effective sync-mode at pull start. */
+  syncMode: "all" | "shared" | "custom";
+  /**
+   * Coalesced prefixes used to drive ListObjectsV2 for this pull. Empty for
+   * v1-migrated records (no recorded scope; treated as full-bucket "all").
+   */
+  prefixSet: string[];
+  scopeChangeDetected: boolean;
+  orphansRemoved: number;
+  orphansBlocked: number;
 }
 
 export interface SyncJournal {
-  version: "1";
+  /**
+   * Schema version. `"1"` is the pre-US-005 shape (no `pulls`, no
+   * tombstone fields on entries). `"2"` adds per-pull records and
+   * tombstone markers; readers MUST tolerate either and migrate v1 → v2
+   * in place on the first v2 write.
+   */
+  version: "1" | "2";
   lastSync: string;
   files: Record<string, JournalEntry>;
+  /**
+   * Per-pull boundary records (v2 only). Always present on v2 journals.
+   * v1 journals do not carry this field — readers should treat absence as
+   * "no recorded history; treat last scope as 'all'/empty".
+   */
+  pulls?: PullRecord[];
 }
 
 export interface SyncStatus {

package/src/vault-client.test.ts

@@ -14,6 +14,8 @@ import {
   VaultClientError,
   pickCanonicalPersonEntity,
   type EntityInfo,
+  type ExplicitGrant,
+  type MembershipSyncConfig,
 } from "./vault-client.js";
 
 // ---------------------------------------------------------------------------
@@ -694,6 +696,263 @@ describe("VaultClient identity bootstrap", () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// Browse-vs-sync SDK methods (US-004)
+//
+// listMyExplicitGrants, getMembershipSyncConfig, setMembershipSyncConfig
+// wrap the US-002/US-003 hq-pro endpoints. Tests assert URL shape, payload
+// shape, error mapping (401/404/network), and the empty-grants fallback
+// that lets call sites treat "no grants" as a normal state.
+// ---------------------------------------------------------------------------
+
+describe("listMyExplicitGrants (US-004)", () => {
+  it("GETs /v1/files/grants with the company query param and returns grants[]", async () => {
+    const grant: ExplicitGrant = {
+      companyUid: "cmp_abc",
+      path: "shared/docs",
+      permission: "read",
+      source: "person",
+    };
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        grants: [grant],
+        computedAt: "2026-05-20T12:00:00.000Z",
+      }),
+    );
+
+    const grants = await client.listMyExplicitGrants("cmp_abc");
+
+    expect(grants).toEqual([grant]);
+
+    const [url, init] = fetchSpy.mock.calls[0] as [string, RequestInit];
+    expect(url).toBe(
+      "https://vault.test.example.com/v1/files/grants?company=cmp_abc",
+    );
+    expect(init.method).toBe("GET");
+    expect(init.body).toBeUndefined();
+  });
+
+  it("URL-encodes the companyUid query parameter", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, { grants: [], computedAt: "2026-05-20T12:00:00.000Z" }),
+    );
+
+    await client.listMyExplicitGrants("cmp/with spaces&weird=chars");
+
+    const [url] = fetchSpy.mock.calls[0] as [string];
+    expect(url).toBe(
+      "https://vault.test.example.com/v1/files/grants?company=cmp%2Fwith%20spaces%26weird%3Dchars",
+    );
+  });
+
+  it("returns [] when the server omits the grants key (empty graph)", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, { computedAt: "2026-05-20T12:00:00.000Z" }),
+    );
+
+    const grants = await client.listMyExplicitGrants("cmp_abc");
+    expect(grants).toEqual([]);
+  });
+
+  it("maps 401 to VaultAuthError", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(401, { error: "Missing or invalid authorization token" }),
+    );
+
+    await expect(client.listMyExplicitGrants("cmp_abc")).rejects.toThrow(
+      VaultAuthError,
+    );
+  });
+
+  it("maps 404 to VaultNotFoundError", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(404, { error: "Unknown route" }),
+    );
+
+    await expect(client.listMyExplicitGrants("cmp_abc")).rejects.toThrow(
+      VaultNotFoundError,
+    );
+  });
+
+  it("surfaces transport errors after exhausting retries", async () => {
+    fetchSpy.mockRejectedValue(new Error("ECONNREFUSED"));
+
+    await expect(client.listMyExplicitGrants("cmp_abc")).rejects.toThrow(
+      /ECONNREFUSED/,
+    );
+    // 1 initial + 3 retries = 4 attempts on a persistent network error.
+    expect(fetchSpy).toHaveBeenCalledTimes(4);
+  });
+});
+
+describe("getMembershipSyncConfig (US-004)", () => {
+  it("GETs /v1/memberships/{id}/sync-config and returns the row verbatim", async () => {
+    const row: MembershipSyncConfig = {
+      membershipId: "psn_1#cmp_abc",
+      syncMode: "custom",
+      customPaths: ["shared/docs", "personal/psn_1"],
+      isDefault: false,
+      updatedAt: "2026-05-20T12:00:00.000Z",
+      updatedBy: "psn_admin",
+    };
+    fetchSpy.mockResolvedValueOnce(jsonResponse(200, row));
+
+    const result = await client.getMembershipSyncConfig("psn_1#cmp_abc");
+
+    expect(result).toEqual(row);
+
+    const [url, init] = fetchSpy.mock.calls[0] as [string, RequestInit];
+    expect(url).toBe(
+      // `#` in the membershipKey MUST be URL-encoded — otherwise the
+      // server sees a fragment, not a path segment.
+      "https://vault.test.example.com/v1/memberships/psn_1%23cmp_abc/sync-config",
+    );
+    expect(init.method).toBe("GET");
+    expect(init.body).toBeUndefined();
+  });
+
+  it("returns the default row (isDefault: true) without updatedAt/updatedBy", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        membershipId: "psn_1#cmp_abc",
+        syncMode: "all",
+        isDefault: true,
+      }),
+    );
+
+    const result = await client.getMembershipSyncConfig("psn_1#cmp_abc");
+    expect(result.isDefault).toBe(true);
+    expect(result.updatedAt).toBeUndefined();
+    expect(result.updatedBy).toBeUndefined();
+  });
+
+  it("maps 401 to VaultAuthError", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(401, { error: "Token expired" }),
+    );
+
+    await expect(
+      client.getMembershipSyncConfig("psn_1#cmp_abc"),
+    ).rejects.toThrow(VaultAuthError);
+  });
+
+  it("maps 404 to VaultNotFoundError (membership tombstoned or missing)", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(404, {
+        error: "Membership not found or not active: psn_1#cmp_abc",
+      }),
+    );
+
+    await expect(
+      client.getMembershipSyncConfig("psn_1#cmp_abc"),
+    ).rejects.toThrow(VaultNotFoundError);
+  });
+
+  it("surfaces network errors after retry exhaustion", async () => {
+    fetchSpy.mockRejectedValue(new Error("socket hang up"));
+
+    await expect(
+      client.getMembershipSyncConfig("psn_1#cmp_abc"),
+    ).rejects.toThrow(/socket hang up/);
+    expect(fetchSpy).toHaveBeenCalledTimes(4);
+  });
+});
+
+describe("setMembershipSyncConfig (US-004)", () => {
+  it("PUTs the partial body to /v1/memberships/{id}/sync-config", async () => {
+    const persisted: MembershipSyncConfig = {
+      membershipId: "psn_1#cmp_abc",
+      syncMode: "custom",
+      customPaths: ["shared/docs"],
+      isDefault: false,
+      updatedAt: "2026-05-20T12:00:00.000Z",
+      updatedBy: "psn_1",
+    };
+    fetchSpy.mockResolvedValueOnce(jsonResponse(200, persisted));
+
+    const result = await client.setMembershipSyncConfig("psn_1#cmp_abc", {
+      syncMode: "custom",
+      customPaths: ["shared/docs"],
+    });
+
+    expect(result).toEqual(persisted);
+
+    const [url, init] = fetchSpy.mock.calls[0] as [string, RequestInit];
+    expect(url).toBe(
+      "https://vault.test.example.com/v1/memberships/psn_1%23cmp_abc/sync-config",
+    );
+    expect(init.method).toBe("PUT");
+    const headers = init.headers as Record<string, string>;
+    expect(headers["Content-Type"]).toBe("application/json");
+    expect(headers.Authorization).toBe("Bearer test-jwt-token-123");
+    expect(JSON.parse(init.body as string)).toEqual({
+      syncMode: "custom",
+      customPaths: ["shared/docs"],
+    });
+  });
+
+  it("supports the shared mode without customPaths", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        membershipId: "psn_1#cmp_abc",
+        syncMode: "shared",
+        isDefault: false,
+        updatedAt: "2026-05-20T12:00:00.000Z",
+        updatedBy: "psn_1",
+      }),
+    );
+
+    const result = await client.setMembershipSyncConfig("psn_1#cmp_abc", {
+      syncMode: "shared",
+    });
+
+    expect(result.syncMode).toBe("shared");
+    expect(result.customPaths).toBeUndefined();
+
+    const [, init] = fetchSpy.mock.calls[0] as [string, RequestInit];
+    expect(JSON.parse(init.body as string)).toEqual({ syncMode: "shared" });
+  });
+
+  it("maps 401 to VaultAuthError", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(401, { error: "Token expired" }),
+    );
+
+    await expect(
+      client.setMembershipSyncConfig("psn_1#cmp_abc", { syncMode: "all" }),
+    ).rejects.toThrow(VaultAuthError);
+  });
+
+  it("maps 404 to VaultNotFoundError when the membership is gone", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(404, { error: "Membership not found" }),
+    );
+
+    await expect(
+      client.setMembershipSyncConfig("psn_1#cmp_abc", { syncMode: "all" }),
+    ).rejects.toThrow(VaultNotFoundError);
+  });
+
+  it("maps 409 to VaultConflictError", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(409, { error: "Concurrent write conflict" }),
+    );
+
+    await expect(
+      client.setMembershipSyncConfig("psn_1#cmp_abc", { syncMode: "all" }),
+    ).rejects.toThrow(VaultConflictError);
+  });
+
+  it("surfaces network errors after retry exhaustion", async () => {
+    fetchSpy.mockRejectedValue(new Error("ETIMEDOUT"));
+
+    await expect(
+      client.setMembershipSyncConfig("psn_1#cmp_abc", { syncMode: "all" }),
+    ).rejects.toThrow(/ETIMEDOUT/);
+    expect(fetchSpy).toHaveBeenCalledTimes(4);
+  });
+});
+
 // ---------------------------------------------------------------------------
 // Refreshable authToken getter
 //
@@ -787,3 +1046,79 @@ describe("authToken getter (refreshable token)", () => {
     }
   });
 });
+
+// ---------------------------------------------------------------------------
+// Raw vend (POST /vend, purpose-aware after US-009)
+// ---------------------------------------------------------------------------
+
+describe("vend (POST /vend, purpose-aware)", () => {
+  it("POSTs to /vend with paths/operations/purpose and returns credentials + policySize", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        credentials: {
+          accessKeyId: "AKIA-BROWSE",
+          secretAccessKey: "secret",
+          sessionToken: "token",
+          expiration: "2026-05-20T13:00:00.000Z",
+        },
+        paths: ["shared/docs/"],
+        operations: "read-only",
+        purpose: "browse",
+        policySize: 412,
+        requestId: "req_xyz",
+      }),
+    );
+
+    const out = await client.vend({
+      paths: ["shared/docs/"],
+      operations: "read-only",
+      purpose: "browse",
+    });
+
+    expect(out.purpose).toBe("browse");
+    expect(out.policySize).toBe(412);
+    expect(out.credentials.accessKeyId).toBe("AKIA-BROWSE");
+    expect(out.credentials.sessionToken).toBe("token");
+
+    const [url, init] = fetchSpy.mock.calls[0] as [string, RequestInit];
+    expect(url).toBe("https://vault.test.example.com/vend");
+    expect((init.method as string).toUpperCase()).toBe("POST");
+    expect(JSON.parse(init.body as string)).toEqual({
+      paths: ["shared/docs/"],
+      operations: "read-only",
+      purpose: "browse",
+    });
+  });
+
+  it("forwards purpose='sync' verbatim (no client-side defaulting)", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        credentials: {
+          accessKeyId: "k",
+          secretAccessKey: "s",
+          sessionToken: "t",
+          expiration: "2026-05-20T13:00:00.000Z",
+        },
+        paths: ["shared/"],
+        operations: "read-only",
+        purpose: "sync",
+        policySize: 200,
+      }),
+    );
+
+    await client.vend({
+      paths: ["shared/"],
+      operations: "read-only",
+      purpose: "sync",
+      duration: 1800,
+    });
+
+    const [, init] = fetchSpy.mock.calls[0] as [string, RequestInit];
+    expect(JSON.parse(init.body as string)).toEqual({
+      paths: ["shared/"],
+      operations: "read-only",
+      purpose: "sync",
+      duration: 1800,
+    });
+  });
+});

package/src/vault-client.ts

@@ -151,6 +151,137 @@ export interface CreateEntityResult {
   entity: EntityInfo;
 }
 
+// -- Browse-vs-sync types (US-002, US-003, US-004) -----------------------
+
+/**
+ * Source kind for an explicit per-company file-ACL grant. Mirrors the
+ * server enum in hq-pro `vault-service/handlers/files-grants.ts`.
+ *
+ * `'open'` collapses two server-side shapes that are indistinguishable to
+ * the caller — the legacy `acl.open === true` floor and an explicit
+ * `granteeType: 'company-wide'` row. Both mean "every active member of
+ * this company sees this prefix".
+ */
+export type GrantSource = "person" | "email" | "group" | "open";
+
+/** Permission level surfaced on a grant row. Matches `AclPermission`. */
+export type GrantPermission = "read" | "write" | "admin";
+
+/**
+ * One row in the response of `GET /v1/files/grants?company={uid}`.
+ *
+ * Role-bypass (owner/admin) entries are intentionally excluded by the
+ * server — this is the caller's EXPLICIT grant graph, not the full set
+ * of prefixes they can touch by virtue of role.
+ */
+export interface ExplicitGrant {
+  companyUid: string;
+  path: string;
+  permission: GrantPermission;
+  source: GrantSource;
+}
+
+/**
+ * Effective sync mode for a single membership. Mirrors the server's
+ * resolved view from `GET /v1/memberships/{id}/sync-config`:
+ *
+ *   - `shared` — sync only `shared/` and the caller's `personal/` prefix
+ *   - `all`    — sync every prefix the caller has read access to
+ *   - `custom` — sync the explicit `customPaths` list (server validates)
+ *
+ * `isDefault: true` means no row exists in DDB and the server is
+ * falling back to its built-in default (currently `'all'` for legacy
+ * memberships created pre-US-003). When `true`, `updatedAt`/`updatedBy`
+ * are absent because there's no row to attribute.
+ */
+export type SyncMode = "shared" | "all" | "custom";
+
+export interface MembershipSyncConfig {
+  membershipId: string;
+  syncMode: SyncMode;
+  customPaths?: string[];
+  /**
+   * `true` when the server returned the built-in default because no
+   * sync-config row exists for this membership. PUT always returns
+   * `false` — writing the row is what makes it non-default.
+   */
+  isDefault: boolean;
+  /** Present only when a sync-config row exists (i.e. `isDefault: false`). */
+  updatedAt?: string;
+  /** Present only when a sync-config row exists. PersonUid of the writer. */
+  updatedBy?: string;
+}
+
+/**
+ * Input shape for {@link VaultClient.setMembershipSyncConfig}. The server
+ * validates the combination — `customPaths` is required when `syncMode`
+ * is `'custom'` and rejected otherwise.
+ */
+export interface SetMembershipSyncConfigInput {
+  syncMode: SyncMode;
+  customPaths?: string[];
+}
+
+// -- Raw vend (legacy POST /vend, purpose-aware after US-009) -------------
+
+/**
+ * Why the caller is requesting STS-scoped credentials. Mirrors the
+ * hq-pro vault-service enum (`src/vault-service/policy-builder.ts`).
+ *
+ *   - `'sync'`   — background machine sync. Role-bypass MUST NOT widen
+ *     the path set: credentials are scoped to exactly the requested
+ *     paths (which the sync engine has already narrowed via US-005).
+ *   - `'browse'` — interactive exploration (hq-console Explore,
+ *     `hq files browse`, admin spelunking). Admin/owner role-bypass
+ *     APPLIES — the caller may receive credentials covering paths
+ *     beyond their explicit ACL grants.
+ *
+ * The server defaults missing/empty to `'sync'` (the safer choice).
+ * The client doesn't mirror that default — every caller should be
+ * explicit about its intent so audit rows are accurate.
+ */
+export type VendPurpose = "sync" | "browse";
+
+export type VaultOperation = "read-only" | "read-write" | "staged-write";
+
+/**
+ * Input shape for {@link VaultClient.vend}. The server validates
+ * combinations — e.g. `purpose: 'sync'` rejects bucket-wide `'*'` paths
+ * as defense in depth against role-bypass widening on the sync path.
+ */
+export interface VendInput {
+  paths: string[];
+  operations: VaultOperation;
+  /** Why these credentials are being vended. See {@link VendPurpose}. */
+  purpose: VendPurpose;
+  /** STS session lifetime in seconds. Server default is 900 (15m). */
+  duration?: number;
+}
+
+export interface VendCredentials {
+  accessKeyId: string;
+  secretAccessKey: string;
+  sessionToken: string;
+  /** ISO-8601 STS-native expiration string. */
+  expiration: string;
+}
+
+export interface VendResult {
+  credentials: VendCredentials;
+  /** Echo of the server-resolved paths after ACL intersection. */
+  paths: string[];
+  operations: VaultOperation;
+  /** Echo of the effective purpose (server-defaulted to 'sync' if absent). */
+  purpose: VendPurpose;
+  /**
+   * Size of the rendered IAM session policy in characters. Lets the
+   * caller detect when it's nearing the 2048-char IAM ceiling so it can
+   * fan out across multiple vends or shrink its path set.
+   */
+  policySize: number;
+  requestId?: string;
+}
+
 // -- STS child vending (VLT-8) --------------------------------------------
 
 export type TaskAction = "read" | "write";
@@ -356,6 +487,71 @@ export class VaultClient {
     return data.invites;
   }
 
+  // -- Browse-vs-sync (US-002, US-003, US-004) -----------------------------
+
+  /**
+   * List the caller's EXPLICIT per-company file-ACL grants. Backed by
+   * `GET /v1/files/grants?company={companyUid}` (hq-pro US-002).
+   *
+   * Role-bypass (owner/admin) entries are excluded server-side — the
+   * response is the caller's actual grant graph, not the full set of
+   * prefixes they can touch by virtue of role. Used by the
+   * browse-vs-sync UI to render an honest grant graph and by the
+   * sync engine to narrow what it pulls.
+   *
+   * Returns `[]` (NOT a 404) when the caller has no explicit grants in
+   * this company, so call sites can treat "empty graph" as a normal
+   * state without catching errors.
+   */
+  async listMyExplicitGrants(companyUid: string): Promise<ExplicitGrant[]> {
+    const data = await this.get<{ grants: ExplicitGrant[]; computedAt: string }>(
+      `/v1/files/grants?company=${encodeURIComponent(companyUid)}`,
+    );
+    return data.grants ?? [];
+  }
+
+  /**
+   * Read the effective sync-mode for a single membership. Backed by
+   * `GET /v1/memberships/{id}/sync-config` (hq-pro US-003).
+   *
+   * The server resolves the effective view — when no row exists for the
+   * membership it returns the built-in default with `isDefault: true`
+   * and omits `updatedAt`/`updatedBy`. Callers should treat `isDefault:
+   * true` as "no explicit config yet" rather than special-casing 404.
+   *
+   * Authorization: caller must own the membership OR hold admin/owner
+   * on the company that the membership belongs to. The server 404s
+   * tombstoned/revoked memberships.
+   */
+  async getMembershipSyncConfig(
+    membershipId: string,
+  ): Promise<MembershipSyncConfig> {
+    return this.get<MembershipSyncConfig>(
+      `/v1/memberships/${encodeURIComponent(membershipId)}/sync-config`,
+    );
+  }
+
+  /**
+   * Write the sync-mode for a single membership. Backed by
+   * `PUT /v1/memberships/{id}/sync-config` (hq-pro US-003).
+   *
+   * Server validates: `customPaths` is required when `syncMode` is
+   * `'custom'` and rejected otherwise. The returned row reflects the
+   * persisted state with `isDefault: false` (writing the row is what
+   * makes it non-default) and the server-assigned `updatedAt` +
+   * `updatedBy`.
+   */
+  async setMembershipSyncConfig(
+    membershipId: string,
+    partial: SetMembershipSyncConfigInput,
+  ): Promise<MembershipSyncConfig> {
+    return this.request<MembershipSyncConfig>(
+      "PUT",
+      `/v1/memberships/${encodeURIComponent(membershipId)}/sync-config`,
+      partial,
+    );
+  }
+
   // -- Entity operations ----------------------------------------------------
 
   readonly entity = {
@@ -467,6 +663,33 @@ export class VaultClient {
     return data;
   }
 
+  // -- Raw vend (POST /vend) ------------------------------------------------
+
+  /**
+   * POST `/vend` — vend STS-scoped credentials for an explicit path list.
+   *
+   * This is the legacy raw-vend endpoint (distinct from `/sts/vend`,
+   * `/sts/vend-self`, and `/sts/vend-child`). Per US-009 it accepts a
+   * `purpose` discriminator that controls whether admin/owner
+   * role-bypass widens the resulting session policy beyond the
+   * caller's explicit ACL grants:
+   *
+   *   - `purpose: 'browse'` — role-bypass APPLIES (interactive
+   *     `hq files browse`, admin spelunking).
+   *   - `purpose: 'sync'`   — role-bypass SUPPRESSED (background sync;
+   *     credentials are scoped to exactly what the caller has explicitly
+   *     been granted, regardless of role).
+   *
+   * The server defaults missing/empty to `'sync'` but every first-party
+   * caller should be explicit so audit attribution is correct.
+   *
+   * Used by `hq files browse`/`hq files cat` (US-008) to peek at vault
+   * objects without ever materialising them under `companies/{co}/`.
+   */
+  async vend(input: VendInput): Promise<VendResult> {
+    return this.post<VendResult>("/vend", input);
+  }
+
   // -- STS operations (VLT-8) -----------------------------------------------
 
   readonly sts = {