@synap-core/sdk 1.5.0 → 1.5.1

package/src/connect/hub-types.ts

@@ -38,9 +38,22 @@ export interface PodEntity {
   /** ISO 8601. */
   createdAt?: string;
   updatedAt?: string;
+  /** The roles it wears, with `includeFacets`; absent when it wears none. */
+  facetSlugs?: string[];
+  /** Each role's overlay, with `includeFacets`; absent when it wears none. */
+  facets?: PodEntityFacet[];
   [key: string]: unknown;
 }
 
+/** One role an entity wears (`FacetRowAnnotation`). */
+export interface PodEntityFacet {
+  facetId: string;
+  /** The role, e.g. `lead`. */
+  slug: string;
+  properties: Record<string, unknown>;
+  status: string | null;
+}
+
 export interface ListEntitiesOptions {
   /** One granted space. Omitted: every space the connection can read. */
   workspaceId?: string;
@@ -53,6 +66,10 @@ export interface ListEntitiesOptions {
   sort?: string;
   /** With `workspaceId`: also the person's pod-wide rows (the pod's default: true). */
   includePodWide?: boolean;
+  /** Only the entities wearing this role, e.g. `lead`. */
+  facetSlug?: string;
+  /** Put `facetSlugs` and `facets` on each row that wears a role. */
+  includeFacets?: boolean;
 }
 
 export type PodConnectionSource = "graph" | "property" | "thread" | "context_channel" | "focus_session";

package/src/connect/index.ts

@@ -48,6 +48,7 @@ export type {
   PodEntity,
   PodEntityConnection,
   PodEntityConnections,
+  PodEntityFacet,
   PodFileUrl,
   PodFocusSession,
   PodSessionSlot,

package/src/testing/auth-server.ts

@@ -29,6 +29,15 @@
  * the sessions about it), `GET /documents/:id` (`{ document }`), `GET
  * /focus-sessions` (an ARRAY; `workspaceId` or `projectId` required; status,
  * limit 1-50, lens, kind, subjectEntityId), `POST /proposals/:id/approve`.
+ * 1.5.1, roles (seed `entities[].facets`; `seedRoles` is desugared into them): the
+ * reach rule (a granted space's rows, plus the pod-wide rows with a role in
+ * one); `GET /entities` filters by `facetSlug` (and a `profileSlug` naming a
+ * role), drops the pod-wide rows of a workspace lens on `includePodWide=false`,
+ * and with `includeFacets=true` puts `facetSlugs` + `facets` on the rows that
+ * wear a visible one; `GET /entities/:id/facets` (`{ facets: [{ facet,
+ * profile, effectiveProperties }] }`). The token sees a facet as a member of
+ * a granted space does (its seed `workspaceId`), never another. A role is known by its slug only: no 404 for an
+ * undeclared `facetSlug`, a synthetic profile id, `effectiveProperties` empty.
  *
  * Who the token acts as: `actsAs: "person"` answers
  * `synap_acts_as: "person"`, applies writes directly (unless `writeMode`
@@ -48,7 +57,8 @@
  */
 import { pkceChallenge, randomToken } from "../connect/encoding";
 import type { PodActsAs, PodGrant, PodUser } from "../connect/types";
-import type { MockPodSeed, MockSeedDocument, MockSeedRelation, MockSeedSession } from "./seed";
+import { desugarSeedRoles } from "./roles";
+import type { MockPodSeed, MockSeedDocument, MockSeedFacet, MockSeedRelation, MockSeedSession } from "./seed";
 
 /** A placeholder pod origin; never contacted. */
 export const MOCK_AUTH_ISSUER = "https://pod.mock-synap.test";
@@ -236,13 +246,47 @@ export function createMockAuthServer(options: MockAuthServerOptions = {}): MockA
   const writes: Array<{ method: string; path: string; body: unknown }> = [];
   const proposals: MockProposal[] = [];
   const seed = options.seed ?? {};
-  const entities: Array<Record<string, unknown>> = [...(seed.entities ?? []), ...(options.entities ?? [])];
+  // One role model: a seed is desugared by parseMockPodSeed; `entities` (and a seed built in code) here.
+  const entities: Array<Record<string, unknown>> = [...(seed.entities ?? []), ...(options.entities ?? [])].map((e, i) =>
+    desugarSeedRoles(e, `entities[${i}]`),
+  );
   const sessions: MockSeedSession[] = [...(seed.sessions ?? [])];
   const documents: MockSeedDocument[] = [...(seed.documents ?? [])];
   const relations: MockSeedRelation[] = [...(seed.relations ?? [])];
   const templateOf = new Map((seed.spaces ?? []).filter((sp) => sp.templateSlug).map((sp) => [sp.id, sp.templateSlug!]));
   const approvals: string[] = [];
   const seededAt = new Date(now()).toISOString();
+
+  /** The roles (facets) an entity wears: the seed's `facets` (`seedRoles` was desugared into them). */
+  const rolesOf = (e: Record<string, unknown>): MockSeedFacet[] =>
+    Array.isArray(e.facets) ? (e.facets as MockSeedFacet[]).filter((f) => typeof f?.slug === "string") : [];
+  /**
+   * What the token's grant lets it read of an entity (the pod's grant clause):
+   * a row of a granted space, or a pod-wide row (`workspaceId` null) with a live
+   * role in one. The pod sends no role field on an entity row, so the mock takes
+   * its roles as SEED input (`facets`) and answers them only when asked.
+   */
+  function readableEntity(e: Record<string, unknown>, spaces: ReadonlySet<string>, only?: string | null): boolean {
+    if (typeof e.workspaceId === "string" && spaces.has(e.workspaceId) && (!only || e.workspaceId === only)) return true;
+    // A pod-wide row is reached by any role in the space; a row of ANOTHER space only by a role stamped in this one.
+    return facetsOf(e, spaces, only ?? undefined).some((f) => e.workspaceId == null || !f.sharedRole);
+  }
+  /**
+   * The roles of `e` a read sees: what a member of a granted space sees
+   * (backend `facetVisibilityConditions` under the token's grant), i.e. a role
+   * whose seed space is granted; a workspace lens sees that space's roles only.
+   */
+  const facetsOf = (e: Record<string, unknown>, spaces: ReadonlySet<string>, lens?: string): MockSeedFacet[] =>
+    rolesOf(e).filter((f) => typeof f.workspaceId === "string" && spaces.has(f.workspaceId) && (lens === undefined || f.workspaceId === lens));
+  /** backend `FacetRowAnnotation`: what `includeFacets=true` puts on a row. */
+  const facetRow = (f: MockSeedFacet) => ({ facetId: f.facetId, slug: f.slug, properties: f.properties ?? {}, status: f.status ?? null });
+  /** A row as the Hub answers it (`entityToWire`): roles ride on it only when asked. */
+  const entityWire = (e: Record<string, unknown>): Record<string, unknown> => {
+    const { facets: _facets, facetSlugs: _facetSlugs, ...wire } = e;
+    return wire;
+  };
+  const readSpaces = (scope: readonly string[]): Set<string> =>
+    new Set(grant.filter((g) => /^entity\.(.+\.)?read$/.test(g.permission) && scope.includes(g.permission)).map((g) => g.workspaceId));
   for (const p of seed.proposals ?? []) {
     proposals.push({
       proposalType: "create",
@@ -404,11 +448,12 @@ export function createMockAuthServer(options: MockAuthServerOptions = {}): MockA
   });
 
   /** The seeded read doors (1.5); null when `path` is none of them. */
-  function readSeeded(path: string, query: URLSearchParams): Response | null {
+  function readSeeded(path: string, query: URLSearchParams, scope: readonly string[]): Response | null {
+    const spaces = readSpaces(scope);
     const conn = /^\/entities\/([^/]+)\/connections$/.exec(path);
     if (conn) {
       const id = decodeURIComponent(conn[1]);
-      const ws = query.get("workspaceId");
+      const ws = query.get("workspaceId") ?? undefined;
       const limit = Math.min(Math.max(Number(query.get("limit") ?? 50) || 50, 1), 200);
       const inLens = (e: Record<string, unknown>) => !ws || e.workspaceId === ws || e.workspaceId == null;
       const connections: Array<Record<string, unknown>> = [];
@@ -421,10 +466,15 @@ export function createMockAuthServer(options: MockAuthServerOptions = {}): MockA
         const otherId = outgoing ? r.targetEntityId : r.sourceEntityId;
         const other = entities.find((e) => e.id === otherId);
         // As the pod: an edge whose far end is gone or out of the lens is not a neighbour.
-        if (!other || !inLens(other)) continue;
+        if (!other || !inLens(other) || !readableEntity(other, spaces)) continue;
         connections.push({
           entityId: otherId,
-          entity: { ...other, type: other.profileSlug ?? other.type ?? null, facetSlugs: other.facetSlugs ?? [] },
+          // relations.ts: the raw row plus its role slugs under the read's facet lens (a 1.5.0 seed's own facetSlugs otherwise).
+          entity: {
+            ...entityWire(other),
+            type: other.profileSlug ?? other.type ?? null,
+            facetSlugs: rolesOf(other).length > 0 ? facetsOf(other, spaces, ws).map((f) => f.slug) : (other.facetSlugs ?? []),
+          },
           label: r.type,
           direction: outgoing ? "outgoing" : "incoming",
           source: "graph",
@@ -457,8 +507,41 @@ export function createMockAuthServer(options: MockAuthServerOptions = {}): MockA
     const entity = /^\/entities\/([^/]+)$/.exec(path);
     if (entity) {
       const found = entities.find((e) => e.id === decodeURIComponent(entity[1]));
-      // The pod answers a miss with an EMPTY 404 body (rest/entities.ts `c.body(null, 404)`).
-      return found ? json(200, found) : new Response(null, { status: 404 });
+      // The pod answers a miss with an EMPTY 404 body (rest/entities.ts `c.body(null, 404)`); so does a row the grant cannot read.
+      return found && readableEntity(found, spaces) ? json(200, entityWire(found)) : new Response(null, { status: 404 });
+    }
+    const roles = /^\/entities\/([^/]+)\/facets$/.exec(path);
+    if (roles) {
+      const found = entities.find((e) => e.id === decodeURIComponent(roles[1]));
+      if (!found || !readableEntity(found, spaces)) return new Response(null, { status: 404 });
+      // getEffectiveFacets under the whole floor: each live facet row, its role-profile, that profile's effective properties.
+      return json(200, {
+        facets: facetsOf(found, spaces).map((f) => ({
+          facet: {
+            id: f.facetId,
+            entityId: found.id,
+            profileId: `profile_${f.slug}`,
+            userId: found.userId ?? user.id,
+            // A stamped facet answers its space; a shared role's facet is stored pod-wide.
+            workspaceId: f.sharedRole ? null : f.workspaceId,
+            contextEntityId: null,
+            status: f.status ?? null,
+            statusCategory: null,
+            properties: f.properties ?? {},
+            metadata: {},
+            createdByKind: null,
+            createdByUserId: null,
+            agentUserId: null,
+            sourceProposalId: null,
+            correlationId: null,
+            createdAt: seededAt,
+            updatedAt: seededAt,
+            deletedAt: null,
+          },
+          profile: { id: `profile_${f.slug}`, slug: f.slug, profileKind: "role" },
+          effectiveProperties: [],
+        })),
+      });
     }
     const doc = /^\/documents\/([^/]+)$/.exec(path);
     if (doc) {
@@ -535,12 +618,31 @@ export function createMockAuthServer(options: MockAuthServerOptions = {}): MockA
     if (method === "GET" && path === "/users/me") return json(200, user);
     if (method === "GET" && path === "/entities") {
       // The pod answers an ARRAY (rest/entities.ts), not a page object.
-      const ws = query.get("workspaceId");
+      const ws = query.get("workspaceId") || undefined;
       const kind = query.get("profileSlug");
+      const role = query.get("facetSlug");
+      // A workspace lens keeps the pod-wide rows unless told not to (rest/entities.ts: `!== "false"`).
+      const podWide = query.get("includePodWide") !== "false";
+      const withFacets = query.get("includeFacets") === "true";
       const offset = Number(query.get("offset") ?? 0) || 0;
       const limit = Number(query.get("limit") ?? 50) || 50;
-      const rows = entities.filter((e) => (!ws || e.workspaceId === ws) && (!kind || e.profileSlug === kind));
-      return json(200, rows.slice(offset, offset + limit));
+      // Granted spaces' rows, plus the pod-wide rows roled in them (read-only, as a member of the space).
+      const spaces = readSpaces(row.scope);
+      const rows = entities.filter((e) => {
+        if (!readableEntity(e, spaces, ws)) return false;
+        // includePodWide=false keeps the rows with a role STAMPED in the space; it drops those reached only through a shared role.
+        if (ws && !podWide && e.workspaceId !== ws && !facetsOf(e, spaces, ws).some((f) => !f.sharedRole)) return false;
+        const slugs = facetsOf(e, spaces, ws).map((f) => f.slug);
+        // A profileSlug naming a role matches its wearers too (entities.list's facet branch).
+        return (!kind || e.profileSlug === kind || slugs.includes(kind)) && (!role || slugs.includes(role));
+      });
+      return json(
+        200,
+        rows.slice(offset, offset + limit).map((e) => {
+          const facets = withFacets ? facetsOf(e, spaces, ws).map(facetRow) : [];
+          return facets.length > 0 ? { ...entityWire(e), facetSlugs: facets.map((f) => f.slug), facets } : entityWire(e);
+        }),
+      );
     }
     if (method === "GET" && path === "/proposals") {
       // The grant clause: proposals are read only where the token holds proposal.read (else none, not a 403).
@@ -561,7 +663,7 @@ export function createMockAuthServer(options: MockAuthServerOptions = {}): MockA
       return json(200, { proposals: page, limit, offset, total: rows.length, hasMore: offset + page.length < rows.length });
     }
     if (method === "GET") {
-      const read = readSeeded(path, query);
+      const read = readSeeded(path, query, row.scope);
       if (read) return read;
     }
     const approve = method === "POST" ? /^\/proposals\/([^/]+)\/approve$/.exec(path) : null;
@@ -581,6 +683,12 @@ export function createMockAuthServer(options: MockAuthServerOptions = {}): MockA
       approvals.push(p.id);
       return json(200, { success: true, proposalId: p.id, proposal: { ...p } });
     }
+    // A pod-wide row's core fields are outside a space-scoped grant: refused (the pod: 403 or 404, not yet pinned), nothing written, no proposal.
+    const patched = method === "PATCH" ? /^\/entities\/([^/]+)$/.exec(path) : null;
+    if (patched) {
+      const target = entities.find((e) => e.id === decodeURIComponent(patched[1]));
+      if (target && target.workspaceId == null) return json(403, { error: "grant does not allow" });
+    }
     if (method !== "GET") {
       writes.push({ method, path, body });
       const fields = body && typeof body === "object" ? (body as Record<string, unknown>) : {};

package/src/testing/roles.ts

@@ -0,0 +1,27 @@
+/**
+ * The mock's ONE role model is `facets` (./seed.ts `MockSeedFacet`). The
+ * deprecated `seedRoles` shorthand is desugared into it here, once, by
+ * `parseMockPodSeed` and by `createMockAuthServer` for `options.entities`, so
+ * nothing downstream reads `seedRoles`. Not exported from `@synap-core/sdk/testing`.
+ */
+import type { MockSeedFacet } from "./seed";
+
+/**
+ * `row` with its `seedRoles` turned into `facets` (a generated `facetId`, no
+ * overlay). A role stated in both (same slug, same space) is a TypeError
+ * naming the entity: one fact, one place, never a silent merge.
+ */
+export function desugarSeedRoles(row: Record<string, unknown>, at: string): Record<string, unknown> {
+  if (!Array.isArray(row.seedRoles)) return row;
+  const { seedRoles, ...rest } = row;
+  const facets = Array.isArray(row.facets) ? (row.facets as MockSeedFacet[]) : [];
+  const shorthand = (seedRoles as Array<{ profileSlug?: unknown; workspaceId?: unknown }>)
+    .filter((r) => typeof r?.profileSlug === "string" && typeof r.workspaceId === "string")
+    .map((r, i): MockSeedFacet => ({ facetId: `seedrole_${String(row.id)}_${i}`, slug: r.profileSlug as string, workspaceId: r.workspaceId as string }));
+  for (const r of shorthand) {
+    if (facets.some((f) => f?.slug === r.slug && f.workspaceId === r.workspaceId)) {
+      throw new TypeError(`${at} ("${String(row.id)}"): the role "${r.slug}" in ${r.workspaceId} is in both facets and seedRoles; keep it in facets only`);
+    }
+  }
+  return { ...rest, facets: [...facets, ...shorthand] };
+}

package/src/testing/seed.ts

@@ -14,8 +14,41 @@
  * `relations` as graph edges for `GET /entities/:id/connections`, `proposals`
  * as `GET /proposals?view=basic` rows, `spaces` name each granted space's
  * template (`synap_grant[].templateSlug` on the token response).
+ *
+ * An entity's roles ride on its row as `facets`, the shape `GET /entities?
+ * includeFacets=true` answers them (`{ facetId, slug, properties, status }`),
+ * plus the seed-only space each is stamped in, so a seed row reads like a pod
+ * row read with includeFacets. The mock derives `facetSlugs` and the reach rule
+ * from them and serves neither field unless asked, as the pod.
  */
 import type { MockProposal } from "./auth-server";
+import { desugarSeedRoles } from "./roles";
+
+/** One role an entity wears (backend `FacetRowAnnotation`, plus the space it is stamped in). */
+export interface MockSeedFacet {
+  facetId: string;
+  /** The role's slug, e.g. `lead`. */
+  slug: string;
+  /** The facet's overlay properties. Default `{}`. */
+  properties?: Record<string, unknown>;
+  /** Its lifecycle status. Default null. */
+  status?: string | null;
+  /**
+   * Seed only, never served: the space the role is in, i.e. the space whose
+   * members see the facet (stamped there, or a pod-wide facet of a role granted
+   * to it). A role in a granted space puts a pod-wide entity in the app's
+   * reach; a workspace lens sees the roles of that space only.
+   */
+  workspaceId: string;
+  /**
+   * Seed only, never served: the role is SHARED, i.e. stored pod-wide (null
+   * `workspaceId`) and granted to `workspaceId`, which then means "the space it
+   * is granted to". Default false = stamped in `workspaceId`. The pod treats the
+   * two alike for reach, except `includePodWide=false` on a space lens, which
+   * drops a pod-wide row reached only through a shared role.
+   */
+  sharedRole?: boolean;
+}
 
 export interface MockSeedEntity {
   id: string;
@@ -23,6 +56,21 @@ export interface MockSeedEntity {
   workspaceId?: string | null;
   title?: string | null;
   properties?: Record<string, unknown>;
+  /**
+   * The roles (facets) it wears, in the wire shape plus the space each is in
+   * (`MockSeedFacet`). SEED INPUT ONLY: the pod sends them only to
+   * `includeFacets`, and so does the mock. A pod-wide entity (`workspaceId:
+   * null`) with a role in a granted space is readable by the app, as a member
+   * of that space sees it. Absent = none.
+   */
+  facets?: MockSeedFacet[];
+  /**
+   * @deprecated Use `facets`; removed in 2.0. Shorthand for `facets` entries
+   * with no id and no overlay: `parseMockPodSeed` turns each into a facet (a
+   * generated `facetId`, empty properties, a null status). A role stated in
+   * both is refused.
+   */
+  seedRoles?: Array<{ profileSlug: string; workspaceId: string }>;
   [key: string]: unknown;
 }
 
@@ -113,8 +161,36 @@ export function parseMockPodSeed(input: string | unknown): MockPodSeed {
       for (const field of REQUIRED[key]) {
         if (typeof (row as Record<string, unknown>)[field] !== "string") throw new TypeError(`seed.${key}[${i}].${field}: expected a string`);
       }
+      if (key === "entities") checkFacets((row as Record<string, unknown>).facets, `seed.entities[${i}].facets`);
     });
   }
-  // A JSON round trip: what the mock serves is what a file could hold.
-  return JSON.parse(JSON.stringify(obj)) as MockPodSeed;
+  (obj.entities as Array<Record<string, unknown>> | undefined)?.forEach((row, i) => {
+    const roles = row.seedRoles;
+    if (roles === undefined) return;
+    if (!Array.isArray(roles)) throw new TypeError(`seed.entities[${i}].seedRoles: expected an array`);
+    roles.forEach((r, j) => {
+      for (const field of ["profileSlug", "workspaceId"]) {
+        if (!r || typeof r !== "object" || typeof (r as Record<string, unknown>)[field] !== "string") {
+          throw new TypeError(`seed.entities[${i}].seedRoles[${j}].${field}: expected a string`);
+        }
+      }
+    });
+  });
+  // A JSON round trip: what the mock serves is what a file could hold. Then ONE role model: seedRoles → facets.
+  const out = JSON.parse(JSON.stringify(obj)) as MockPodSeed;
+  if (out.entities) out.entities = out.entities.map((row, i) => desugarSeedRoles(row, `seed.entities[${i}]`) as MockSeedEntity);
+  return out;
+}
+
+function checkFacets(facets: unknown, at: string): void {
+  if (facets === undefined) return;
+  if (!Array.isArray(facets)) throw new TypeError(`${at}: expected an array`);
+  facets.forEach((f, j) => {
+    if (!f || typeof f !== "object" || Array.isArray(f)) throw new TypeError(`${at}[${j}]: expected an object`);
+    for (const field of ["facetId", "slug", "workspaceId"]) {
+      if (typeof (f as Record<string, unknown>)[field] !== "string") throw new TypeError(`${at}[${j}].${field}: expected a string`);
+    }
+    const shared = (f as Record<string, unknown>).sharedRole;
+    if (shared !== undefined && typeof shared !== "boolean") throw new TypeError(`${at}[${j}].sharedRole: expected a boolean`);
+  });
 }