@spacefast/common 0.0.24 → 0.2.1

package/dist/contracts/oauth-scope-actions.d.ts

@@ -0,0 +1,90 @@
+import { type StatticAction } from "./api-keys.js";
+/**
+ * Tenant-admission actions — the ONE declaration the credential compiler and
+ * scope-grantability both read, so they cannot drift. These are account-level:
+ * compiled onto the tenant root and checked ONLY there (creating a
+ * not-yet-existing team has no team to hang on), so their reach across the
+ * shared tenant grants no team authority. Every other action is team-role:
+ * compiled per team and intersected with the holder's LIVE role there.
+ */
+export declare const TENANT_ADMISSION_ACTIONS: readonly ["teams:create"];
+export declare function isTenantAdmissionAction(action: StatticAction): boolean;
+/**
+ * The one table binding OAuth scopes to IAM-lite actions, in both directions.
+ *
+ * Each scope declares only the actions it adds, plus the narrower scopes it
+ * subsumes. Everything else is derived:
+ *
+ * - forward (`oauthScopeActions`): a scope grants its own actions plus every
+ *   action of the scopes it covers, transitively. That is also what an API-key
+ *   preset with the same name is allowed to do, so `credential-policy.ts`
+ *   compiles presets from here rather than from a second list.
+ * - inverse (`oauthScopesForActions`): a policy's actions name the scopes whose
+ *   *own* actions they reach. Covered actions are deliberately not signals —
+ *   otherwise a read-only policy would label itself `publish:write` just for
+ *   holding `spaces:read`.
+ *
+ * Keep both halves honest by editing one entry: adding an action to a scope
+ * widens the grant and the label together, and `oauth-resources.test.ts` pins
+ * the derivation's invariants.
+ */
+declare const OAUTH_SCOPE_GRAPH: {
+    readonly "teams:read": {
+        readonly covers: readonly [];
+        readonly actions: readonly ["teams:read"];
+    };
+    readonly "teams:create": {
+        readonly covers: readonly [];
+        readonly actions: readonly ["teams:create"];
+    };
+    readonly "spaces:read": {
+        readonly covers: readonly [];
+        readonly actions: readonly ["spaces:read", "versions:read", "builds:read"];
+    };
+    readonly "spaces:write": {
+        readonly covers: readonly [];
+        readonly actions: readonly ["spaces:create", "spaces:write"];
+    };
+    readonly "spaces:rename": {
+        readonly covers: readonly [];
+        readonly actions: readonly ["spaces:rename"];
+    };
+    readonly "publish:write": {
+        readonly covers: readonly ["spaces:read", "spaces:write"];
+        readonly actions: readonly ["spaces:publish", "versions:promote", "versions:download", "builds:trigger", "builds:create"];
+    };
+    readonly "domains:read": {
+        readonly covers: readonly [];
+        readonly actions: readonly ["domains:read"];
+    };
+    readonly "domains:write": {
+        readonly covers: readonly ["domains:read"];
+        readonly actions: readonly ["domains:create", "domains:verify", "domains:assign", "domains:bind", "domains:delete", "domains:dns.write", "domains:purchase"];
+    };
+    readonly "spaces:publish": {
+        readonly covers: readonly [];
+        readonly actions: readonly ["spaces:publish"];
+    };
+    readonly "builds:trigger": {
+        readonly covers: readonly [];
+        readonly actions: readonly ["builds:trigger"];
+    };
+};
+export type OAuthScopeWithActions = keyof typeof OAUTH_SCOPE_GRAPH;
+export declare function oauthScopeHasActions(scope: string): scope is OAuthScopeWithActions;
+/**
+ * The scopes a credential policy can be *labelled* with: the capability set the
+ * dashboard and CLI offer per machine OAuth client. Derived from the graph's
+ * own order so the label list reads the way the consent screen does.
+ */
+export declare const OAUTH_PRIMARY_SCOPES: ("teams:read" | "teams:create" | "spaces:read" | "spaces:write" | "spaces:rename" | "publish:write" | "domains:read" | "domains:write" | "spaces:publish" | "builds:trigger")[];
+/** Every action a scope grants, including the scopes it subsumes. */
+export declare function oauthScopeActionsFor(scope: OAuthScopeWithActions): StatticAction[];
+/** Every action a set of scopes grants together. Unknown scopes grant nothing. */
+export declare function oauthScopeActions(scopes: readonly string[] | null | undefined): StatticAction[];
+/**
+ * The primary scopes a set of allowed actions amounts to. `*` is every primary
+ * scope; anything else matches on a scope's own actions only.
+ */
+export declare function oauthScopesForActions(actions: Iterable<string>): OAuthScopeWithActions[];
+export {};

package/dist/contracts/oauth-scope-actions.js

@@ -0,0 +1,126 @@
+import { StatticActionSchema } from "./api-keys.js";
+import { OAUTH_MCP_RESOURCE_SCOPES } from "./oauth-resources.js";
+/**
+ * Tenant-admission actions — the ONE declaration the credential compiler and
+ * scope-grantability both read, so they cannot drift. These are account-level:
+ * compiled onto the tenant root and checked ONLY there (creating a
+ * not-yet-existing team has no team to hang on), so their reach across the
+ * shared tenant grants no team authority. Every other action is team-role:
+ * compiled per team and intersected with the holder's LIVE role there.
+ */
+export const TENANT_ADMISSION_ACTIONS = [
+    "teams:create",
+];
+const TENANT_ADMISSION_ACTION_SET = new Set(TENANT_ADMISSION_ACTIONS);
+export function isTenantAdmissionAction(action) {
+    return TENANT_ADMISSION_ACTION_SET.has(action);
+}
+/**
+ * The one table binding OAuth scopes to IAM-lite actions, in both directions.
+ *
+ * Each scope declares only the actions it adds, plus the narrower scopes it
+ * subsumes. Everything else is derived:
+ *
+ * - forward (`oauthScopeActions`): a scope grants its own actions plus every
+ *   action of the scopes it covers, transitively. That is also what an API-key
+ *   preset with the same name is allowed to do, so `credential-policy.ts`
+ *   compiles presets from here rather than from a second list.
+ * - inverse (`oauthScopesForActions`): a policy's actions name the scopes whose
+ *   *own* actions they reach. Covered actions are deliberately not signals —
+ *   otherwise a read-only policy would label itself `publish:write` just for
+ *   holding `spaces:read`.
+ *
+ * Keep both halves honest by editing one entry: adding an action to a scope
+ * widens the grant and the label together, and `oauth-resources.test.ts` pins
+ * the derivation's invariants.
+ */
+const OAUTH_SCOPE_GRAPH = {
+    "teams:read": { covers: [], actions: ["teams:read"] },
+    "teams:create": { covers: [], actions: ["teams:create"] },
+    "spaces:read": {
+        covers: [],
+        actions: ["spaces:read", "versions:read", "builds:read"],
+    },
+    "spaces:write": { covers: [], actions: ["spaces:create", "spaces:write"] },
+    "spaces:rename": { covers: [], actions: ["spaces:rename"] },
+    // The publish tier is read + write plus the version and build verbs a
+    // publish flow needs. `spaces:publish` and `builds:trigger` are also offered
+    // on their own as granular API-resource scopes; they stay listed here as
+    // publish's own actions so a policy holding nothing but them still labels as
+    // a publisher.
+    "publish:write": {
+        covers: ["spaces:read", "spaces:write"],
+        actions: [
+            "spaces:publish",
+            "versions:promote",
+            "versions:download",
+            "builds:trigger",
+            "builds:create",
+        ],
+    },
+    "domains:read": { covers: [], actions: ["domains:read"] },
+    "domains:write": {
+        covers: ["domains:read"],
+        actions: [
+            "domains:create",
+            "domains:verify",
+            "domains:assign",
+            "domains:bind",
+            "domains:delete",
+            "domains:dns.write",
+            "domains:purchase",
+        ],
+    },
+    // Granular API-resource scopes. They never label a policy on their own — the
+    // inverse only ranges over the primary scopes below.
+    "spaces:publish": { covers: [], actions: ["spaces:publish"] },
+    "builds:trigger": { covers: [], actions: ["builds:trigger"] },
+};
+export function oauthScopeHasActions(scope) {
+    return scope in OAUTH_SCOPE_GRAPH;
+}
+const primaryScopeSet = new Set(OAUTH_MCP_RESOURCE_SCOPES);
+/**
+ * The scopes a credential policy can be *labelled* with: the capability set the
+ * dashboard and CLI offer per machine OAuth client. Derived from the graph's
+ * own order so the label list reads the way the consent screen does.
+ */
+export const OAUTH_PRIMARY_SCOPES = Object.keys(OAUTH_SCOPE_GRAPH)
+    .filter(oauthScopeHasActions)
+    .filter((scope) => primaryScopeSet.has(scope));
+// Derived action lists are emitted in `StatticActionSchema` order, so a
+// credential's permissions read the same however the graph is authored and a
+// reordered entry never churns the wire contract.
+const ACTION_ORDER = new Map(StatticActionSchema.options.map((action, index) => [action, index]));
+function actionsForScope(scope, seen) {
+    if (seen.has(scope))
+        return [];
+    seen.add(scope);
+    const entry = OAUTH_SCOPE_GRAPH[scope];
+    return [
+        ...entry.actions,
+        ...entry.covers
+            .filter(oauthScopeHasActions)
+            .flatMap((covered) => actionsForScope(covered, seen)),
+    ];
+}
+/** Every action a scope grants, including the scopes it subsumes. */
+export function oauthScopeActionsFor(scope) {
+    return [...new Set(actionsForScope(scope, new Set()))].toSorted((left, right) => (ACTION_ORDER.get(left) ?? 0) - (ACTION_ORDER.get(right) ?? 0));
+}
+/** Every action a set of scopes grants together. Unknown scopes grant nothing. */
+export function oauthScopeActions(scopes) {
+    return [
+        ...new Set((scopes ?? []).filter(oauthScopeHasActions).flatMap((scope) => oauthScopeActionsFor(scope))),
+    ];
+}
+/**
+ * The primary scopes a set of allowed actions amounts to. `*` is every primary
+ * scope; anything else matches on a scope's own actions only.
+ */
+export function oauthScopesForActions(actions) {
+    const allowed = new Set(actions);
+    if (allowed.has("*"))
+        return [...OAUTH_PRIMARY_SCOPES];
+    return OAUTH_PRIMARY_SCOPES.filter((scope) => OAUTH_SCOPE_GRAPH[scope].actions.some((action) => allowed.has(action)));
+}

package/dist/contracts/operations.d.ts

@@ -43,7 +43,7 @@ export declare const UserOperationSchema: z.ZodObject<{
         path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         provider: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
             registrar: "registrar";
-            wpcloud: "wpcloud";
+            infra: "infra";
             dns: "dns";
             runtime: "runtime";
         }>>>;
@@ -68,9 +68,9 @@ export declare const UserOperationSchema: z.ZodObject<{
         integration_release: "integration_release";
     }>;
     versionSource: z.ZodOptional<z.ZodEnum<{
-        direct_upload: "direct_upload";
         git: "git";
         settings: "settings";
+        direct_upload: "direct_upload";
     }>>;
     integrationRelease: z.ZodOptional<z.ZodObject<{
         environment: z.ZodEnum<{
@@ -117,7 +117,7 @@ export declare const operationListResponseSchema: z.ZodObject<{
             path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
             provider: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
                 registrar: "registrar";
-                wpcloud: "wpcloud";
+                infra: "infra";
                 dns: "dns";
                 runtime: "runtime";
             }>>>;
@@ -142,9 +142,9 @@ export declare const operationListResponseSchema: z.ZodObject<{
             integration_release: "integration_release";
         }>;
         versionSource: z.ZodOptional<z.ZodEnum<{
-            direct_upload: "direct_upload";
             git: "git";
             settings: "settings";
+            direct_upload: "direct_upload";
         }>>;
         integrationRelease: z.ZodOptional<z.ZodObject<{
             environment: z.ZodEnum<{
@@ -222,6 +222,29 @@ export declare const SuperadminOperationListSchema: z.ZodObject<{
     total: z.ZodNumber;
     windowHours: z.ZodNumber;
 }, z.core.$strip>;
+export declare const SuperadminOperationDetailSchema: z.ZodObject<{
+    id: z.ZodString;
+    eventType: z.ZodString;
+    status: z.ZodString;
+    resourceType: z.ZodString;
+    resourceId: z.ZodString;
+    attempts: z.ZodNumber;
+    dueAt: z.ZodNullable<z.ZodString>;
+    leaseExpiresAt: z.ZodNullable<z.ZodString>;
+    stuck: z.ZodBoolean;
+    blockedByOperationId: z.ZodNullable<z.ZodString>;
+    inflightKey: z.ZodNullable<z.ZodString>;
+    lastError: z.ZodNullable<z.ZodString>;
+    createdAt: z.ZodString;
+    updatedAt: z.ZodString;
+    finishedAt: z.ZodNullable<z.ZodString>;
+    firstDueAt: z.ZodString;
+    payload: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    progress: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    receipt: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    cursor: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export type SuperadminOperationDetail = z.infer<typeof SuperadminOperationDetailSchema>;
 export declare const SuperadminOperationSummarySchema: z.ZodObject<{
     windowHours: z.ZodNumber;
     live: z.ZodObject<{

package/dist/contracts/operations.js

@@ -32,13 +32,13 @@ export const operationListQuerySchema = cursorListQuerySchema.extend({
         .string()
         .min(1)
         .optional()
-        .describe("Filter to operations touching one resource type, e.g. `space`."),
+        .describe("Filter to operations touching one resource type, for example `space`."),
     resourceId: z.string().min(1).optional().describe("Filter to operations touching one resource."),
     spaceId: z
         .string()
         .min(1)
         .optional()
-        .describe("Filter to operations pertaining to one Space — its own operations plus those of its versions and builds. The Space must be readable by the caller."),
+        .describe("Filter to operations for one Space: its own operations plus those of its versions and builds. The Space must be readable by the caller."),
 });
 export const operationListResponseSchema = z.object({
     data: z.array(UserOperationSchema),
@@ -46,8 +46,7 @@ export const operationListResponseSchema = z.object({
 });
 // ---------------------------------------------------------------------------
 // Superadmin operator surface: the operations rows ARE the queue, bucketed by
-// claim eligibility. Served by the control plane's feed service and consumed
-// by the superadmin dashboard and the e2e harness.
+// claim eligibility.
 /** Buckets an operator triages by. Live buckets partition the live population:
  *  a queued row is exactly one of ready / scheduled / blocked. */
 export const SUPERADMIN_OPERATION_FILTERS = [
@@ -75,8 +74,8 @@ export const SuperadminOperationRowSchema = z.object({
     resourceType: z.string(),
     resourceId: z.string(),
     attempts: z.number().int().nonnegative(),
-    // The mutable eligibility clock, meaningless once the row is terminal — null
-    // there rather than a stale instant an operator would read as a schedule.
+    // The mutable eligibility clock. Null once the row is terminal, rather than a
+    // stale instant an operator would read as a schedule.
     dueAt: z.string().datetime().nullable(),
     leaseExpiresAt: z.string().datetime().nullable(),
     // Computed with the database clock so row labels agree with server-side
@@ -94,6 +93,13 @@ export const SuperadminOperationListSchema = z.object({
     total: z.number().int().nonnegative(),
     windowHours: z.number().int().positive(),
 });
+export const SuperadminOperationDetailSchema = SuperadminOperationRowSchema.extend({
+    firstDueAt: z.string().datetime(),
+    payload: z.record(z.string(), z.unknown()).nullable(),
+    progress: z.record(z.string(), z.unknown()).nullable(),
+    receipt: z.record(z.string(), z.unknown()).nullable(),
+    cursor: z.record(z.string(), z.unknown()).nullable(),
+});
 export const SuperadminOperationSummarySchema = z.object({
     windowHours: z.number().int().positive(),
     live: z.object({

package/dist/contracts/pages.d.ts

@@ -1,36 +1,43 @@
 import { z } from "zod";
 export declare const SITE_PAGE_IDS: readonly ["404", "denied", "access", "index", "preview"];
 export declare const sitePageIdSchema: z.ZodEnum<{
+    access: "access";
     denied: "denied";
     index: "index";
     preview: "preview";
-    access: "access";
     404: "404";
 }>;
 export type SitePageId = z.infer<typeof sitePageIdSchema>;
 export declare const ROUTE_PAGE_IDS: readonly ["404", "denied", "access"];
 export declare const routePageIdSchema: z.ZodEnum<{
-    denied: "denied";
     access: "access";
+    denied: "denied";
     404: "404";
 }>;
 export type RoutePageId = z.infer<typeof routePageIdSchema>;
-export declare const CUSTOM_PAGE_IDS: readonly ["404", "denied", "access", "index", "preview", "collab"];
+export declare const CUSTOM_PAGE_IDS: readonly ["404", "denied", "access", "index", "preview", "collab", "login", "undeployed", "suspended", "gone", "runtime-error", "rate-limited"];
 export declare const customPageIdSchema: z.ZodEnum<{
     collab: "collab";
+    login: "login";
+    access: "access";
+    suspended: "suspended";
     denied: "denied";
     index: "index";
     preview: "preview";
-    access: "access";
     404: "404";
+    undeployed: "undeployed";
+    gone: "gone";
+    "runtime-error": "runtime-error";
+    "rate-limited": "rate-limited";
 }>;
 export type CustomPageId = z.infer<typeof customPageIdSchema>;
 export declare const COLLAB_PAGE_SOURCE = "_pages/collab.html";
 export declare const COLLAB_PAGE_PATH: "/_pages/collab.html";
 export declare const COLLAB_PAGE_ELEMENTS: readonly ["sf-space", "sf-comments", "sf-thread", "sf-timeline", "sf-presence", "sf-versions"];
-export declare const PLATFORM_PAGE_IDS: readonly ["undeployed", "suspended", "legal", "gone", "runtime-error", "rate-limited", "tier-unavailable", "proxy-error", "method-not-allowed", "content-too-large"];
+export declare const PLATFORM_PAGE_IDS: readonly ["login", "undeployed", "suspended", "legal", "gone", "runtime-error", "rate-limited", "tier-unavailable", "proxy-error", "method-not-allowed", "content-too-large"];
 export declare const platformPageIdSchema: z.ZodEnum<{
     legal: "legal";
+    login: "login";
     suspended: "suspended";
     undeployed: "undeployed";
     gone: "gone";
@@ -51,7 +58,10 @@ export type PageDefinition = {
     noindex: boolean;
     customTemplate: boolean;
 };
-export declare const PAGE_CATALOG: Readonly<Record<SitePageId, PageDefinition>>;
+type PageCatalog = {
+    [PageId in SitePageId]: PageDefinition;
+};
+export declare const PAGE_CATALOG: PageCatalog;
 export declare const PAGE_SOURCE_MAX_BYTES: number;
 export declare const PAGES_DIRECTORY = "_pages";
 export declare const PAGE_LAYOUT_FILE = "_layout.html";
@@ -59,13 +69,27 @@ export declare const pageArtifactKeySchema: z.ZodString;
 export declare const runtimePagesSchema: z.ZodObject<{
     routes: z.ZodRecord<z.ZodString, z.ZodObject<{
         pages: z.ZodOptional<z.ZodRecord<z.ZodEnum<{
-            denied: "denied";
             access: "access";
+            denied: "denied";
             404: "404";
         }>, z.ZodString>>;
         index: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
     previews: z.ZodRecord<z.ZodString, z.ZodString>;
+    platform: z.ZodOptional<z.ZodRecord<z.ZodEnum<{
+        legal: "legal";
+        login: "login";
+        suspended: "suspended";
+        undeployed: "undeployed";
+        gone: "gone";
+        "runtime-error": "runtime-error";
+        "rate-limited": "rate-limited";
+        "tier-unavailable": "tier-unavailable";
+        "proxy-error": "proxy-error";
+        "method-not-allowed": "method-not-allowed";
+        "content-too-large": "content-too-large";
+    }>, z.ZodString>>;
     collab: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type RuntimePages = z.infer<typeof runtimePagesSchema>;
+export {};

package/dist/contracts/pages.js

@@ -6,11 +6,24 @@ export const routePageIdSchema = z.enum(ROUTE_PAGE_IDS);
 // `collab` is publishable but has no built-in template: with no layout of their
 // own a Space's reviewers get the platform frame at `/__/collab`, so there is
 // nothing for a default `_pages/collab.html` to be. Hence CUSTOM ⊃ SITE.
-export const CUSTOM_PAGE_IDS = ["404", "denied", "access", "index", "preview", "collab"];
+export const CUSTOM_PAGE_IDS = [
+    "404",
+    "denied",
+    "access",
+    "index",
+    "preview",
+    "collab",
+    "login",
+    "undeployed",
+    "suspended",
+    "gone",
+    "runtime-error",
+    "rate-limited",
+];
 export const customPageIdSchema = z.enum(CUSTOM_PAGE_IDS);
 // The Space-level review room the collaboration orb expands into, and the URL
 // its compiled document answers at (collab-public-api.html §3). One room per
-// Space, so one page, at the root — never a per-directory override.
+// Space: one page, at the root, never a per-directory override.
 // The PHP mirror is SPACEFAST_COLLAB_PAGE_PATH in runtime/engine/shared/context.php.
 export const COLLAB_PAGE_SOURCE = "_pages/collab.html";
 export const COLLAB_PAGE_PATH = `/${COLLAB_PAGE_SOURCE}`;
@@ -26,6 +39,7 @@ export const COLLAB_PAGE_ELEMENTS = [
     "sf-versions",
 ];
 export const PLATFORM_PAGE_IDS = [
+    "login",
     "undeployed",
     "suspended",
     "legal",
@@ -68,9 +82,9 @@ export const PAGE_CATALOG = {
         customTemplate: false,
     },
     // The visitor access page: the deny surface WITH lanes (sign in, SSO,
-    // password, request an invite). Rendered by the runtime at the requested URL;
-    // publishers may fully retheme it — the runtime injects the functional lane
-    // blocks into the sf-access-* slots so forms and states stay correct.
+    // password, request an invite), rendered at the requested URL. Publishers may
+    // fully retheme it; the runtime injects the lane blocks into the sf-access-*
+    // slots so forms and states stay correct.
     access: {
         id: "access",
         status: 403,
@@ -107,6 +121,9 @@ export const runtimePagesSchema = z.object({
         index: pageArtifactKeySchema.optional(),
     })),
     previews: z.record(z.string().startsWith("/").max(2048), pageArtifactKeySchema),
+    // Partner platform pages are compiled with tenant/team presentation at
+    // finalize. First-party versions omit this map and keep the PHP fallback.
+    platform: z.record(platformPageIdSchema, pageArtifactKeySchema).optional(),
     // Present only when the Space published its own review room; its absence is
     // what tells the SDK to expand into the platform frame instead.
     collab: pageArtifactKeySchema.optional(),

package/dist/contracts/partner-notifications.d.ts

@@ -0,0 +1,3 @@
+export declare const PRINCIPAL_NOTIFICATION_EVENT_CODES: readonly ["principal.notification.claim", "principal.notification.space_expiry", "principal.notification.access_invitation", "principal.notification.access_request", "principal.notification.access_verification", "principal.notification.publish_receipt", "principal.notification.comment"];
+export type PrincipalNotificationEventCode = (typeof PRINCIPAL_NOTIFICATION_EVENT_CODES)[number];
+export declare const PRINCIPAL_NOTIFICATION_EVENT_PREFIX = "principal.notification.";

package/dist/contracts/partner-notifications.js

@@ -0,0 +1,65 @@
+// The `principal.notification.*` catalog (partner API spec §7 "Events").
+//
+// For a partner tenant, Spacefast does NOT send email to the tenant's own end
+// customers (principals): a partner white-labels that surface. Instead, each
+// customer-facing notification that Spacefast would otherwise email is delivered
+// to the partner as a webhook event on the tenant subscription, and the partner
+// sends its own branded message. No active subscription → no send and no
+// Spacefast-sender fallback (§7 L343-345). `ten_main` consumer email is
+// untouched.
+//
+// This module is the subscribe-side catalog: the codes a partner subscribes to
+// and the guards over them. `activity.ts` folds this list into
+// `ACTIVITY_EVENT_CODES` so these are first-class taxonomy codes — every one
+// carries a dashboard activity-grammar row and is a valid webhook `events`
+// filter. The test pins that fold as a subset relationship.
+//
+// Enumeration is from a complete audit of the partner-reachable email send
+// sites, keeping only notifications whose recipient is a partner tenant's own
+// customer. Dropped: Spacefast dashboard-ACCOUNT auth / security notices
+// (password reset, account email verification, provider changes) — a partner
+// customer's dashboard account authenticates through the partner's own issuer via
+// partner tokens, so Spacefast never sends those; and team-member /
+// dashboard-collaborator email, which is not a partner end-customer notification.
+// NOTE: a private space's own visitor email-verification challenges (open-page
+// verify, access-request verify) are a different thing — they reach the partner's
+// end customer and ARE delegated, via `access_verification` below.
+export const PRINCIPAL_NOTIFICATION_EVENT_CODES = [
+    // A claimable space's claim link is available to hand to the customer who
+    // created it (partner API spec §13 Q3 — the one certain event). Spacefast
+    // surfaces the claim link in its own CLI/API response for `ten_main`; for a
+    // partner tenant the link reaches the customer only through the partner, so
+    // this event carries it.
+    "principal.notification.claim",
+    // A claimable space is expiring soon and can still be kept by claiming it.
+    // The Spacefast-sent expiry reminder for a partner-owned claimable space
+    // (operations/jobs/space-lifecycle.ts) becomes this event instead.
+    "principal.notification.space_expiry",
+    // A person was invited to access a space. The Spacefast-sent space access
+    // invitation for a partner space (access/email.ts) becomes this event.
+    "principal.notification.access_invitation",
+    // Someone requested access to a private space and the owner must review it,
+    // or a pending request was decided (approved/denied). The Spacefast-sent
+    // access-request review + decision mail for a partner space (access/email.ts,
+    // access/transition.ts) becomes this event.
+    "principal.notification.access_request",
+    // A visitor to a partner's private space must verify their email address —
+    // either to open a page behind a verified-email gate, or to submit an access
+    // request. Spacefast would otherwise send the visitor an essential-auth
+    // "verify your email" link (access/email.ts, access/verified-email-proof.ts);
+    // for a partner space that recipient is the partner's own end customer, so the
+    // verify URL is delegated as this event for the partner to deliver instead.
+    "principal.notification.access_verification",
+    // A publish/build lifecycle receipt for a partner space, where applicable
+    // (§7 "publish receipt where applicable"). Partner spaces early-exit the
+    // team-scoped receipt paths today; this is the code those paths emit on.
+    "principal.notification.publish_receipt",
+    // Comment activity on a partner space (a new thread, reply, or mention). The
+    // Spacefast-sent collaboration email for a partner space (cast-worker.ts)
+    // becomes this event; the partner notifies its own customer.
+    "principal.notification.comment",
+];
+// The prefix every principal-notification code shares. `subscriptions` filters
+// select on it as a wildcard (`principal.notification.*`), so a partner can
+// subscribe to the whole class in one filter.
+export const PRINCIPAL_NOTIFICATION_EVENT_PREFIX = "principal.notification.";