@topolo/sdk 0.4.10 → 0.6.0

package/src/index.ts

@@ -10,7 +10,7 @@ export {
 } from "./client.js";
 export type { TopoloCredential, AgentIdentity } from "./auth.js";
 export {
-  DEFAULT_SERVICE_URLS,
+  DEFAULT_APP_URLS,
   APPLICATIONS,
   APPLICATION_REQUIREMENTS,
   APPLICATION_REQUIREMENTS_VERSION,
@@ -32,7 +32,7 @@ export {
   type ApplicationRequirementStatus,
   type ApplicationRequirementsAuditReport,
   type ServiceCatalogUrlEntry,
-  type ServiceId,
+  type AppApiId,
 } from "./services.js";
 export {
   TopoloSdkError,

package/src/modules/crm.test.ts

@@ -9,7 +9,7 @@ function stubFetch(responses: Array<{ status?: number; body?: unknown }>) {
   const impl = vi.fn(async (url: string, init: RequestInit) => {
     calls.push({ url, init });
     if (String(url).includes('/api/services/by-slug/')) {
-      return new Response(JSON.stringify({ success: true, data: { service_id: 'service_crm' } }), {
+      return new Response(JSON.stringify({ success: true, data: { app_id: 'service_crm' } }), {
         status: 200,
         headers: { 'Content-Type': 'application/json' },
       });
@@ -20,14 +20,14 @@ function stubFetch(responses: Array<{ status?: number; body?: unknown }>) {
           data: {
             services: [
               {
-                service_id: 'srv_crm',
+                app_id: 'app_crm',
                 app_slug: 'topolo-crm',
                 name: 'Topolo CRM',
                 api_base_url: 'https://crm.topolo.app',
                 launch_url: 'https://crm.topolo.app',
                 surface_kind: 'api',
                 status: 'active',
-                granted_permissions: ['srv_crm.contacts:read'],
+                granted_permissions: ['app_crm.contacts:read'],
               },
             ],
           },
@@ -61,7 +61,7 @@ function clientWith(impl: typeof fetch) {
 }
 
 beforeEach(() => {
-  TopoloClient.clearServiceIdCache();
+  TopoloClient.clearAppIdCache();
 });
 
 describe('CrmModule.listContacts', () => {

package/src/modules/identity.test.ts

@@ -9,7 +9,7 @@ function stubFetch(responses: Array<{ status?: number; body?: unknown }>) {
   const impl = vi.fn(async (url: string, init: RequestInit) => {
     calls.push({ url, init });
     if (String(url).includes('/api/services/by-slug/')) {
-      return new Response(JSON.stringify({ success: true, data: { service_id: 'service_auth' } }), {
+      return new Response(JSON.stringify({ success: true, data: { app_id: 'service_auth' } }), {
         status: 200,
         headers: { 'Content-Type': 'application/json' },
       });
@@ -48,12 +48,12 @@ function clientWith(
     credential,
     agent: AGENT,
     fetch: impl,
-    serviceIds: { auth: 'service_auth' },
+    appIds: { auth: 'service_auth' },
   });
 }
 
 beforeEach(() => {
-  TopoloClient.clearServiceIdCache();
+  TopoloClient.clearAppIdCache();
 });
 
 describe('IdentityModule.whoami', () => {
@@ -93,7 +93,7 @@ describe('IdentityModule.whoami', () => {
       {
         body: {
           credentialType: 'api_key',
-          user: { id: 'svc_1', email: 'svc@example.com' },
+          user: { id: 'usr_1', email: 'user@example.com' },
           organization: { id: 'org_2', slug: 'beta' },
         },
       },

package/src/modules/p2p.test.ts

@@ -9,7 +9,7 @@ function stubFetch(responses: Array<{ status?: number; body?: unknown }>) {
   const impl = vi.fn(async (url: string, init: RequestInit) => {
     calls.push({ url, init });
     if (String(url).includes('/api/services/by-slug/')) {
-      return new Response(JSON.stringify({ success: true, data: { service_id: 'service_p2p' } }), {
+      return new Response(JSON.stringify({ success: true, data: { app_id: 'service_p2p' } }), {
         status: 200,
         headers: { 'Content-Type': 'application/json' },
       });
@@ -19,14 +19,14 @@ function stubFetch(responses: Array<{ status?: number; body?: unknown }>) {
         data: {
           services: [
             {
-              service_id: 'srv_p2p',
+              app_id: 'app_p2p',
               app_slug: 'topolo-p2p',
               name: 'Topolo P2P',
               api_base_url: 'https://p2p.topolo.app',
               launch_url: 'https://p2p.topolo.app',
               surface_kind: 'api',
               status: 'active',
-              granted_permissions: ['srv_p2p.directory:read'],
+              granted_permissions: ['app_p2p.directory:read'],
             },
           ],
         },
@@ -61,7 +61,7 @@ function clientWith(impl: typeof fetch) {
 
 describe('P2PModule.listDirectory', () => {
   beforeEach(() => {
-    TopoloClient.clearServiceIdCache();
+    TopoloClient.clearAppIdCache();
   });
 
   it('GETs /api/directory/capabilities and unwraps the envelope', async () => {
@@ -75,7 +75,6 @@ describe('P2PModule.listDirectory', () => {
                 capability_id: 'cap_1',
                 publisher_org_id: 'org_a',
                 app_id: 'app_x',
-                service_id: 'service_x',
                 name: 'Demo',
                 description: 'A capability',
                 category: 'other',
@@ -117,7 +116,6 @@ describe('P2PModule.publishCapability', () => {
               capability_id: 'cap_z',
               publisher_org_id: 'org_p',
               app_id: 'app_x',
-              service_id: 'service_x',
               name: 'Demo',
               description: 'A capability',
               category: 'other',
@@ -140,7 +138,6 @@ describe('P2PModule.publishCapability', () => {
       capability_id: 'cap_z',
       publisher_org_id: 'org_p',
       app_id: 'app_x',
-      service_id: 'service_x',
       name: 'Demo',
       description: 'A capability',
       category: 'other',
@@ -174,7 +171,6 @@ describe('P2PModule.publishCapability', () => {
       capability_id: 'cap_other',
       publisher_org_id: 'org_target',
       app_id: 'app_x',
-      service_id: 'service_x',
       name: 'Demo',
       description: '...',
       category: 'other',

package/src/modules/p2p.ts

@@ -6,7 +6,6 @@ export interface P2PCapability {
   capability_id: string;
   publisher_org_id: string;
   app_id: string;
-  service_id: string;
   name: string;
   description: string;
   category: string;
@@ -26,7 +25,6 @@ export interface PublishCapabilityInput {
   capability_id: string;
   publisher_org_id: string;
   app_id: string;
-  service_id: string;
   name: string;
   description: string;
   category: string;
@@ -231,7 +229,6 @@ export class P2PModule {
         capability_id: input.capability_id,
         publisher_org_id: input.publisher_org_id,
         app_id: input.app_id,
-        service_id: input.service_id,
         name: input.name,
         description: input.description,
         category: input.category,

package/src/node/credential-store.ts

@@ -0,0 +1,311 @@
+import { mkdir, readFile, writeFile, chmod } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { homedir, platform } from 'node:os';
+import { dirname, join } from 'node:path';
+import { TopoloOAuth } from '../oauth.js';
+import type { TopoloCredential } from '../auth.js';
+
+/**
+ * Node-only credential store shared by the `topolo` CLI and `@topolo/mcp`.
+ *
+ * Both need to read (and refresh) the credential that `topolo auth login`
+ * writes to `$XDG_CONFIG_HOME/topolo/config.json`. This lives in a Node-only
+ * subpath (`@topolo/sdk/node`) so the isomorphic SDK core never imports
+ * `node:fs` — importing this module in a browser/worker bundle is a mistake.
+ *
+ * The CLI re-exports every symbol here from `packages/topolo-cli/src/config.ts`
+ * so existing call sites are unchanged; the MCP imports it directly to fall
+ * back to the on-disk credential when no `TOPOLO_*` env credential is set.
+ */
+
+export const TOPOLO_ENVIRONMENTS = ['production', 'staging', 'development', 'local'] as const;
+export type TopoloEnvironment = (typeof TOPOLO_ENVIRONMENTS)[number];
+
+export interface TopoloConfig {
+  credential?: TopoloCredential;
+  /** OAuth client_id used for the most recent login — needed to refresh the access token. */
+  oauthClientId?: string;
+  /** Per-service URL overrides — written when user runs `topolo config set-url`. */
+  serviceUrls?: Record<string, string>;
+  /** Optional agent label propagated as `X-Topolo-Agent`. */
+  agentName?: string;
+  /** Environment-scoped profiles. Legacy top-level fields are treated as production. */
+  profiles?: Partial<Record<TopoloEnvironment, TopoloEnvironmentProfile>>;
+}
+
+export interface TopoloEnvironmentProfile {
+  credential?: TopoloCredential;
+  oauthClientId?: string;
+  serviceUrls?: Record<string, string>;
+  agentName?: string;
+}
+
+/**
+ * Default service URLs per environment. `local` has no baked defaults — a
+ * local dev loop points services at ad-hoc ports, so it is driven entirely by
+ * `TOPOLO_LOCAL_SERVICE_URL_*` / `TOPOLO_SERVICE_URL_*` overrides.
+ */
+export const ENVIRONMENT_DEFAULT_SERVICE_URLS: Record<
+  TopoloEnvironment,
+  Record<string, string>
+> = {
+  production: {
+    developers: 'https://developers.topolo.app',
+  },
+  staging: {
+    auth: 'https://auth.stg.topolo.us',
+    developers: 'https://developers.stg.topolo.us',
+    seed: 'https://seed.stg.topolo.us',
+  },
+  development: {
+    auth: 'https://auth.topolo.dev',
+    developers: 'https://developers.topolo.dev',
+  },
+  local: {},
+};
+
+export function configPath(): string {
+  const override = process.env.TOPOLO_CONFIG_PATH;
+  if (override) return override;
+  const base = process.env.XDG_CONFIG_HOME
+    || (platform() === 'win32'
+      ? join(homedir(), 'AppData', 'Roaming')
+      : join(homedir(), '.config'));
+  return join(base, 'topolo', 'config.json');
+}
+
+export async function readConfig(): Promise<TopoloConfig> {
+  const path = configPath();
+  if (!existsSync(path)) return {};
+  try {
+    const raw = await readFile(path, 'utf8');
+    return JSON.parse(raw) as TopoloConfig;
+  } catch {
+    return {};
+  }
+}
+
+export async function writeConfig(config: TopoloConfig): Promise<void> {
+  const path = configPath();
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, JSON.stringify(config, null, 2) + '\n', 'utf8');
+  if (platform() !== 'win32') {
+    try {
+      await chmod(path, 0o600);
+    } catch {
+      /* non-fatal */
+    }
+  }
+}
+
+export function normalizeEnvironment(value: string | undefined): TopoloEnvironment {
+  const normalized = (value ?? 'production').trim().toLowerCase();
+  if (normalized === '' || normalized === 'production' || normalized === 'prod') {
+    return 'production';
+  }
+  if (normalized === 'staging' || normalized === 'stage' || normalized === 'stg') {
+    return 'staging';
+  }
+  if (normalized === 'development' || normalized === 'dev') {
+    return 'development';
+  }
+  if (normalized === 'local' || normalized === 'localhost') {
+    return 'local';
+  }
+  throw new Error(
+    `Unknown Topolo environment "${value}". Expected production, staging, development, or local.`,
+  );
+}
+
+export function selectedEnvironment(): TopoloEnvironment {
+  return normalizeEnvironment(process.env.TOPOLO_ENV);
+}
+
+export function envVarPrefix(environment: TopoloEnvironment): string {
+  if (environment === 'production') return 'TOPOLO_PRODUCTION';
+  if (environment === 'staging') return 'TOPOLO_STAGING';
+  if (environment === 'development') return 'TOPOLO_DEVELOPMENT';
+  return 'TOPOLO_LOCAL';
+}
+
+export function profileForEnvironment(
+  config: TopoloConfig,
+  environment: TopoloEnvironment = selectedEnvironment(),
+): TopoloEnvironmentProfile {
+  const profile = config.profiles?.[environment] ?? {};
+  if (environment === 'production') {
+    return {
+      credential: config.credential,
+      oauthClientId: config.oauthClientId,
+      ...profile,
+      serviceUrls: {
+        ...(config.serviceUrls ?? {}),
+        ...(profile.serviceUrls ?? {}),
+      },
+      agentName: profile.agentName ?? config.agentName,
+    };
+  }
+  return profile;
+}
+
+export function writeProfileConfig(
+  config: TopoloConfig,
+  environment: TopoloEnvironment,
+  profile: TopoloEnvironmentProfile,
+): TopoloConfig {
+  const profiles = { ...(config.profiles ?? {}) };
+  profiles[environment] = {
+    ...(profiles[environment] ?? {}),
+    ...profile,
+  };
+  return { ...config, profiles };
+}
+
+export function clearProfileCredential(
+  config: TopoloConfig,
+  environment: TopoloEnvironment,
+): TopoloConfig {
+  const next = { ...config };
+  if (environment === 'production') {
+    delete next.credential;
+    delete next.oauthClientId;
+  }
+  const profiles = { ...(config.profiles ?? {}) };
+  const profile = { ...(profiles[environment] ?? {}) };
+  delete profile.credential;
+  delete profile.oauthClientId;
+  profiles[environment] = profile;
+  return { ...next, profiles };
+}
+
+export function credentialSourceFromConfig(
+  config: TopoloConfig,
+  environment: TopoloEnvironment = selectedEnvironment(),
+): string {
+  const prefix = envVarPrefix(environment);
+  if (process.env[`${prefix}_API_KEY`]) return `env:${prefix}_API_KEY`;
+  if (process.env[`${prefix}_ACCESS_TOKEN`]) return `env:${prefix}_ACCESS_TOKEN`;
+  if (process.env.TOPOLO_API_KEY) return 'env:TOPOLO_API_KEY';
+  if (process.env.TOPOLO_ACCESS_TOKEN) return 'env:TOPOLO_ACCESS_TOKEN';
+  return profileForEnvironment(config, environment).credential ? 'config-file' : 'none';
+}
+
+/**
+ * Resolve credentials with env-var precedence over on-disk config.
+ * Env vars are what agents set in their environment; config is what
+ * interactive users get after running `topolo auth login`.
+ */
+export async function resolveCredential(
+  environment: TopoloEnvironment = selectedEnvironment(),
+): Promise<TopoloCredential | null> {
+  const prefix = envVarPrefix(environment);
+  const apiKey = process.env[`${prefix}_API_KEY`] ?? process.env.TOPOLO_API_KEY;
+  if (apiKey) return { kind: 'api_key', apiKey };
+
+  const accessToken = process.env[`${prefix}_ACCESS_TOKEN`] ?? process.env.TOPOLO_ACCESS_TOKEN;
+  if (accessToken) return { kind: 'access_token', accessToken };
+
+  const config = await readConfig();
+  return profileForEnvironment(config, environment).credential ?? null;
+}
+
+/**
+ * If the stored access_token is expired (or within the skew window) and a
+ * refresh_token + oauthClientId are present, exchange the refresh_token for a
+ * new pair and persist. On any failure returns the existing (stale) credential
+ * so the next API call fails naturally with auth_error — we don't nuke the
+ * user's config on a transient network blip.
+ */
+const REFRESH_SKEW_SECONDS = 60;
+
+export async function refreshCredentialIfNeeded(
+  environment: TopoloEnvironment = selectedEnvironment(),
+): Promise<TopoloCredential | null> {
+  const prefix = envVarPrefix(environment);
+  if (
+    process.env[`${prefix}_API_KEY`]
+    || process.env[`${prefix}_ACCESS_TOKEN`]
+    || process.env.TOPOLO_API_KEY
+    || process.env.TOPOLO_ACCESS_TOKEN
+  ) {
+    return resolveCredential(environment);
+  }
+
+  const config = await readConfig();
+  const profile = profileForEnvironment(config, environment);
+  const cred = profile.credential;
+  if (!cred || cred.kind !== 'access_token') return cred ?? null;
+  if (!cred.refreshToken || !cred.expiresAt || !profile.oauthClientId) return cred;
+
+  const now = Math.floor(Date.now() / 1000);
+  if (cred.expiresAt - REFRESH_SKEW_SECONDS > now) return cred;
+
+  try {
+    const oauth = new TopoloOAuth({
+      serviceUrls: resolveServiceUrls(profile.serviceUrls, environment) as Partial<
+        Record<'auth' | 'crm', string>
+      >,
+    });
+    const tokens = await oauth.refreshToken({
+      clientId: profile.oauthClientId,
+      refreshToken: cred.refreshToken,
+    });
+    const refreshed: TopoloCredential = {
+      kind: 'access_token',
+      accessToken: tokens.access_token,
+      ...(tokens.refresh_token
+        ? { refreshToken: tokens.refresh_token }
+        : { refreshToken: cred.refreshToken }),
+      expiresAt: Math.floor(Date.now() / 1000) + tokens.expires_in,
+    };
+    await writeConfig(
+      environment === 'production' && !config.profiles?.production
+        ? { ...config, credential: refreshed }
+        : writeProfileConfig(config, environment, { credential: refreshed }),
+    );
+    return refreshed;
+  } catch {
+    return cred;
+  }
+}
+
+export function resolveAgentName(configAgentName?: string): string | undefined {
+  return process.env.TOPOLO_AGENT_NAME ?? configAgentName;
+}
+
+export function resolveServiceUrls(
+  configUrls?: Record<string, string>,
+  environment: TopoloEnvironment = selectedEnvironment(),
+): Record<string, string> | undefined {
+  const merged: Record<string, string> = {
+    ...ENVIRONMENT_DEFAULT_SERVICE_URLS[environment],
+    ...(configUrls ?? {}),
+  };
+
+  // Env wins. Pull env-specific and global service URL vars that might be set.
+  const prefix = `${envVarPrefix(environment)}_SERVICE_URL_`;
+  for (const [k, v] of Object.entries(process.env)) {
+    if (k.startsWith(prefix) && v) {
+      merged[k.slice(prefix.length).toLowerCase()] = v;
+    }
+  }
+  for (const [k, v] of Object.entries(process.env)) {
+    if (k.startsWith('TOPOLO_SERVICE_URL_') && v) {
+      merged[k.slice('TOPOLO_SERVICE_URL_'.length).toLowerCase()] = v;
+    }
+  }
+  return Object.keys(merged).length > 0 ? merged : undefined;
+}
+
+export function resolvedProfileConfig(
+  config: TopoloConfig,
+  environment: TopoloEnvironment = selectedEnvironment(),
+): TopoloEnvironmentProfile {
+  const profile = profileForEnvironment(config, environment);
+  return {
+    credential: profile.credential,
+    oauthClientId: profile.oauthClientId,
+    agentName: profile.agentName,
+    serviceUrls: resolveServiceUrls(profile.serviceUrls, environment),
+  };
+}

package/src/oauth.ts

@@ -1,5 +1,5 @@
 import { TopoloAuthError, TopoloHttpError } from './errors.js';
-import { resolveServiceUrl, type ServiceId } from './services.js';
+import { resolveServiceUrl, type AppApiId } from './services.js';
 
 const DEVICE_GRANT = 'urn:ietf:params:oauth:grant-type:device_code';
 
@@ -22,7 +22,7 @@ export interface TokenResponse {
 
 export interface OAuthHelperOptions {
   /** Overrides for TopoloAuth URL. Staging/dev should pass a mapping. */
-  serviceUrls?: Partial<Record<ServiceId, string>>;
+  serviceUrls?: Partial<Record<AppApiId, string>>;
   /** Injected fetch. Defaults to global fetch. */
   fetch?: typeof fetch;
 }

package/src/services.generated.ts

@@ -2,7 +2,7 @@
 // Source of truth: topolo.cloudcontrol.json in every app repo.
 // Regenerate: npm run generate:services
 
-export const SERVICES = {
+export const APP_API_URLS = {
   agent: "https://agent.topolo.app",
   auth: "https://auth.topolo.app",
   backup: "https://backup.topolo.app",
@@ -52,4 +52,4 @@ export const SERVICES = {
   web: "https://web.topolo.app",
 } as const;
 
-export type ServiceId = keyof typeof SERVICES;
+export type AppApiId = keyof typeof APP_API_URLS;

package/src/services.test.ts

@@ -3,7 +3,7 @@ import {
   APPLICATION_REQUIREMENTS,
   APPLICATION_REQUIREMENTS_VERSION,
   APPLICATIONS,
-  DEFAULT_SERVICE_URLS,
+  DEFAULT_APP_URLS,
   auditAllApplicationRequirements,
   auditApplicationRequirements,
   applicationRequirementScopes,
@@ -62,9 +62,9 @@ const EXPECTED_APPLICATION_IDS = [
   'web',
 ];
 
-describe('service registry', () => {
+describe('app API registry', () => {
   it('includes every production worker API that belongs to a platform application', () => {
-    expect(DEFAULT_SERVICE_URLS).toMatchObject({
+    expect(DEFAULT_APP_URLS).toMatchObject({
       calendar: 'https://calendar.topolo.app',
       books: 'https://books.topolo.app',
       consent: 'https://consent.topolo.app',
@@ -73,34 +73,34 @@ describe('service registry', () => {
       one: 'https://www.topolo.app',
       web: 'https://web.topolo.app',
     });
-    expect(DEFAULT_SERVICE_URLS).toMatchObject({
+    expect(DEFAULT_APP_URLS).toMatchObject({
       success: 'https://success.topolo.app',
       forms: 'https://forms.topolo.app',
       survey: 'https://survey.topolo.app',
     });
-    expect(DEFAULT_SERVICE_URLS).not.toHaveProperty('web.api');
-    expect(DEFAULT_SERVICE_URLS).not.toHaveProperty('web.runtime');
+    expect(DEFAULT_APP_URLS).not.toHaveProperty('web.api');
+    expect(DEFAULT_APP_URLS).not.toHaveProperty('web.runtime');
   });
 
-  it('does not bake opaque Auth service ids into the generated registry', async () => {
+  it('does not bake opaque Auth app ids into the generated registry', async () => {
     const services = await import('./services.js');
 
-    expect(services).not.toHaveProperty('PLATFORM_SERVICE_IDS');
+    expect(services).not.toHaveProperty('PLATFORM_APP_IDS');
   });
 
-  it('maps every callable service back to an application catalog entry', () => {
+  it('maps every callable app API back to an application catalog entry', () => {
     const applicationServices = new Set<string>(
       Object.values(APPLICATIONS).flatMap((application) => [...application.services]),
     );
 
-    for (const serviceId of Object.keys(DEFAULT_SERVICE_URLS)) {
-      expect(applicationServices.has(serviceId)).toBe(true);
+    for (const appId of Object.keys(DEFAULT_APP_URLS)) {
+      expect(applicationServices.has(appId)).toBe(true);
     }
   });
 
   it('resolves services from explicit catalog API URLs', () => {
     expect(resolveCatalogServiceUrl({
-      serviceId: 'srv_crm',
+      appId: 'app_crm',
       slug: 'topolo-crm',
       name: 'Topolo CRM',
       launchUrl: 'https://crm.topolo.app',
@@ -110,7 +110,7 @@ describe('service registry', () => {
 
   it('does not infer callable URLs from launcher URLs', () => {
     expect(resolveCatalogServiceUrl({
-      serviceId: 'srv_crm',
+      appId: 'app_crm',
       slug: 'topolo-crm',
       name: 'Topolo CRM',
       launchUrl: 'https://crm.stg.topolo.us',
@@ -119,7 +119,7 @@ describe('service registry', () => {
 
   it('prefers explicit catalog API URLs over launch URLs', () => {
     expect(resolveCatalogServiceUrl({
-      serviceId: 'srv_future',
+      appId: 'app_future',
       slug: 'topolo-future',
       name: 'Future',
       launchUrl: 'https://future.topolo.app',
@@ -133,15 +133,15 @@ describe('application catalog', () => {
     expect(Object.keys(APPLICATIONS).sort()).toEqual(EXPECTED_APPLICATION_IDS);
   });
 
-  it('only references registered service IDs from application metadata', () => {
-    const registeredServices = new Set<string>(Object.keys(DEFAULT_SERVICE_URLS));
+  it('only references registered app API ids from application metadata', () => {
+    const registeredServices = new Set<string>(Object.keys(DEFAULT_APP_URLS));
 
     for (const application of Object.values(APPLICATIONS)) {
-      for (const serviceId of application.services) {
-        expect(registeredServices.has(serviceId)).toBe(true);
+      for (const appId of application.services) {
+        expect(registeredServices.has(appId)).toBe(true);
       }
       for (const target of application.deployTargets) {
-        if (target.serviceId) expect(registeredServices.has(target.serviceId)).toBe(true);
+        if (target.appId) expect(registeredServices.has(target.appId)).toBe(true);
       }
     }
   });
@@ -152,19 +152,19 @@ describe('application catalog', () => {
     // studio web worker (web.topolo.app/api); the API worker is de-routed and
     // no longer carries a public service registration.
     expect(
-      APPLICATIONS.web.deployTargets.find((target) => target.name === 'topolo-web-studio')?.serviceId,
+      APPLICATIONS.web.deployTargets.find((target) => target.name === 'topolo-web-studio')?.appId,
     ).toBe('web');
     expect(
-      APPLICATIONS.web.deployTargets.find((target) => target.name === 'topolo-web-api')?.serviceId,
+      APPLICATIONS.web.deployTargets.find((target) => target.name === 'topolo-web-api')?.appId,
     ).toBeNull();
     // topolo-web-runtime (Astro, sites.topolo.app) deploys from its own wrangler
     // config and is intentionally listed as non-callable, so it can never be an
-    // agent-callable service.
+    // agent-callable app API.
     expect(
-      APPLICATIONS.web.deployTargets.find((target) => target.name === 'topolo-web-runtime')?.serviceId,
+      APPLICATIONS.web.deployTargets.find((target) => target.name === 'topolo-web-runtime')?.appId,
     ).toBeNull();
     const callableTargetNames = APPLICATIONS.web.deployTargets
-      .filter((target) => target.serviceId)
+      .filter((target) => target.appId)
       .map((target) => target.name);
     expect(callableTargetNames).not.toContain('topolo-web-runtime');
   });
@@ -174,14 +174,14 @@ describe('application catalog', () => {
     // Front-door standardization: the callable `feed` service is served by the
     // feed web worker (feed.topolo.app/api); the API worker is de-routed.
     expect(
-      APPLICATIONS.feed.deployTargets.find((target) => target.name === 'topolo-feed-web')?.serviceId,
+      APPLICATIONS.feed.deployTargets.find((target) => target.name === 'topolo-feed-web')?.appId,
     ).toBe('feed');
     expect(
-      APPLICATIONS.feed.deployTargets.find((target) => target.name === 'topolo-feed-api')?.serviceId,
+      APPLICATIONS.feed.deployTargets.find((target) => target.name === 'topolo-feed-api')?.appId,
     ).toBeNull();
     // The analytics ingestion worker keeps its own host and is non-callable.
     expect(
-      APPLICATIONS.feed.deployTargets.find((target) => target.name === 'topolo-feed-analytics-api')?.serviceId,
+      APPLICATIONS.feed.deployTargets.find((target) => target.name === 'topolo-feed-analytics-api')?.appId,
     ).toBeNull();
   });
 });
@@ -214,7 +214,7 @@ describe('application requirements', () => {
     expect(adminRequirementIds).toContain('shared-shell-and-launcher');
     expect(adminRequirementIds).not.toContain('organization-scoped-data');
     expect(mailRequirementIds).toContain('organization-scoped-data');
-    expect(mailRequirementIds).toContain('service-registration-and-scopes');
+    expect(mailRequirementIds).toContain('app-registration-and-scopes');
     expect(mailRequirementIds).toContain('native-dashboard-widget');
   });
 
@@ -226,7 +226,7 @@ describe('application requirements', () => {
     expect(audit.application.id).toBe('mail');
     expect(audit.score.total).toBe(audit.findings.length);
     expect(byRequirement.get('platform-metadata')?.status).toBe('met');
-    expect(byRequirement.get('service-registration-and-scopes')?.status).toBe('partial');
+    expect(byRequirement.get('app-registration-and-scopes')?.status).toBe('partial');
     expect(byRequirement.get('canonical-docs')?.status).toBe('needs_review');
   });