@topolo/sdk 0.10.0 → 0.10.1

package/dist/index.d.cts

@@ -470,6 +470,289 @@ interface CredentialIntrospection {
     } | null;
 }
 
+/**
+ * Live application directory — resolve, enumerate, and identify platform
+ * applications from the credential-scoped live registry.
+ *
+ * The platform scales to millions of constantly-changing applications, so no
+ * compiled application map may gate behavior. The live registry
+ * (`searchServices` / `getService` on the Catalog service) is the source of
+ * truth. The bundled static snapshot (`applications-fallback.ts`) is consulted
+ * ONLY when the registry is unreachable (network failure, no credential), and
+ * as metadata enrichment for apps the registry already confirmed — it must
+ * never cause a registry-known application to be rejected.
+ */
+
+interface ApplicationDeployTarget {
+    name: string;
+    kind: string;
+    apiUrl: string | null;
+    domains: readonly string[];
+    routes: readonly string[];
+    appId: string | null;
+}
+interface ApplicationCatalogEntry {
+    id: string;
+    appDir: string;
+    name: string;
+    packageName: string | null;
+    productionUrl: string | null;
+    services: readonly string[];
+    deployTargets: readonly ApplicationDeployTarget[];
+}
+/**
+ * Application ids are open-ended — they come from the live registry, not a
+ * compiled union. Kept as a named alias for source compatibility.
+ */
+type ApplicationId = string;
+/**
+ * Derive the human-friendly application id from a live catalog entry: the
+ * canonical slug with the vendor prefix stripped (`topolo-notify` → `notify`).
+ * Falls back through name and appId (`app_topolo_notify` → `notify`). Never
+ * consults a static map, so newly registered applications get a friendly id
+ * without a client rebuild.
+ */
+declare function friendlyAppId(entry: {
+    appId: string;
+    slug?: string | null;
+    name?: string | null;
+}): string;
+/** Synthesize a catalog entry for an application known only to the live registry. */
+declare function applicationEntryFromCatalog(live: TopoloServiceCatalogEntry): ApplicationCatalogEntry;
+type ApplicationDirectorySource = 'live' | 'static_fallback';
+interface ApplicationDirectoryApplication {
+    id: string;
+    application: ApplicationCatalogEntry;
+    source: 'live' | 'static';
+    live: TopoloServiceCatalogEntry | null;
+}
+interface ApplicationDirectory {
+    source: ApplicationDirectorySource;
+    applications: ApplicationDirectoryApplication[];
+}
+/** The subset of TopoloClient the directory helpers need (test-injectable). */
+interface ApplicationDirectoryClient {
+    searchServices(options?: {
+        query?: string;
+        cursor?: string;
+        limit?: number;
+    }): Promise<{
+        services: TopoloServiceCatalogEntry[];
+        page: {
+            nextCursor: string | null;
+        };
+    }>;
+    getService(application: string): Promise<TopoloServiceCatalogEntry>;
+}
+/** Static snapshot as a directory — the registry-unreachable fallback. */
+declare function staticApplicationDirectory(): ApplicationDirectory;
+/**
+ * Enumerate every application the current credential can see in the live
+ * registry (walking the continuation cursor to exhaustion). Falls back to the
+ * bundled static snapshot only when the registry cannot be reached — pass
+ * `null` as the client to request the fallback explicitly (e.g. no credential
+ * configured).
+ */
+declare function listApplicationDirectory(client: ApplicationDirectoryClient | null): Promise<ApplicationDirectory>;
+declare function formatDirectoryApplicationIds(directory: ApplicationDirectory): string;
+/**
+ * Resolve one application by id, slug, or name against the live registry.
+ * Registry-known apps always resolve — the static snapshot can only enrich
+ * them, never reject them. When the registry is reachable and does not know
+ * the application, the error lists the live ids. When the registry is
+ * unreachable (or `client` is null), the static snapshot answers instead.
+ */
+declare function resolveApplicationDirectoryEntry(client: ApplicationDirectoryClient | null, application: string): Promise<ApplicationDirectoryApplication>;
+
+declare const APPLICATION_REQUIREMENTS_VERSION = "2026-08-11.1";
+type ApplicationRequirementScope = 'all' | 'browser' | 'api' | 'tooling' | 'agent_surface';
+interface ApplicationRequirement {
+    id: string;
+    title: string;
+    summary: string;
+    appliesTo: readonly ApplicationRequirementScope[];
+    evidence: readonly string[];
+    implementation: readonly string[];
+}
+type ApplicationRequirementStatus = 'met' | 'partial' | 'missing' | 'needs_review';
+interface ApplicationRequirementFinding {
+    requirementId: string;
+    title: string;
+    status: ApplicationRequirementStatus;
+    reason: string;
+    evidence: readonly string[];
+    nextActions: readonly string[];
+}
+interface ApplicationRequirementScore {
+    met: number;
+    partial: number;
+    missing: number;
+    needsReview: number;
+    total: number;
+    percent: number;
+}
+interface ApplicationRequirementAudit {
+    version: string;
+    application: ApplicationCatalogEntry;
+    scopes: ApplicationRequirementScope[];
+    score: ApplicationRequirementScore;
+    findings: ApplicationRequirementFinding[];
+}
+interface ApplicationRequirementMigrationItem {
+    applicationId: ApplicationId;
+    applicationName: string;
+    requirementId: string;
+    title: string;
+    status: Exclude<ApplicationRequirementStatus, 'met'>;
+    reason: string;
+    nextActions: readonly string[];
+}
+interface ApplicationRequirementsAuditReport {
+    version: string;
+    applications: ApplicationRequirementAudit[];
+    migrationQueue: ApplicationRequirementMigrationItem[];
+}
+declare const APPLICATION_REQUIREMENTS: readonly [{
+    readonly id: "platform-metadata";
+    readonly title: "Register the application in platform metadata";
+    readonly summary: "Every app must have a stable application ID, CloudControl metadata for deployed surfaces, and package metadata where code is shipped.";
+    readonly appliesTo: readonly ["all"];
+    readonly evidence: readonly ["topolo.cloudcontrol.json exists for every deployed app surface", "package.json names the package or app when the repo ships code", "The live platform registry exposes the app through topolo apps and MCP discovery"];
+    readonly implementation: readonly ["Register the app in the live platform registry (Auth service catalog) before exposing it to agents", "Keep production URLs, Worker names, Pages projects, routes, domains, and bindings current in CloudControl metadata", "Do not leave a new Topolo* app directory without an explicit application ID"];
+}, {
+    readonly id: "canonical-docs";
+    readonly title: "Update canonical docs with the code change";
+    readonly summary: "TopoloDocs is the source of truth for application behavior, ownership, deployment shape, auth boundaries, and operations.";
+    readonly appliesTo: readonly ["all"];
+    readonly evidence: readonly ["Matching system registry entry exists in TopoloDocs", "Internal handbook coverage exists for the system", "npm run validate passes in TopoloDocs when docs are touched"];
+    readonly implementation: readonly ["Read the matching TopoloDocs system entry before coding", "Update docs in the same change when behavior, API, auth, data ownership, deployment, or operations change", "Update last_verified dates on touched canonical pages"];
+}, {
+    readonly id: "shared-auth-boundary";
+    readonly title: "Use the shared Topolo auth boundary";
+    readonly summary: "Applications must derive identity, organization, scopes, and app entitlement from TopoloAuth rather than inventing parallel auth state.";
+    readonly appliesTo: readonly ["browser", "api", "tooling", "agent_surface"];
+    readonly evidence: readonly ["@topolo/auth-client or @topolo-io/worker-runtime is used where applicable", "No public command, tool, or SDK method accepts orgId", "App slug and Auth app registration are documented for protected APIs"];
+    readonly implementation: readonly ["Use shared auth/runtime packages instead of copying token parsing, gateway, or browser storage flows", "Derive organization from the credential on every request", "Route OAuth, refresh, logout, and SSO paths according to the shared Auth contract"];
+}, {
+    readonly id: "shared-shell-and-launcher";
+    readonly title: "Use the shared shell, launcher, and account menu";
+    readonly summary: "Browser applications should feel like one platform and should not create isolated navigation or account surfaces.";
+    readonly appliesTo: readonly ["browser"];
+    readonly evidence: readonly ["@topolo-io/app-shell is used for the platform shell where the app has authenticated UI", "@topolo-io/app-launcher keeps the shared launcher/app switcher reachable from authenticated app chrome", "Account menu and sign-out behavior use TopoloAppShell or the ui-kit TopoloAccountMenu primitive", "Repeated app body surfaces use shared TopoloAppLayout primitives instead of local stat cards, empty states, or status badges", "Local preview supports deterministic visual QA fixtures for overview, list, detail, settings, and empty/loading states", "Authenticated app body content stays inside the viewport on mobile and desktop widths"];
+    readonly implementation: readonly ["Use @topolo-io/app-shell TopoloAppShell for authenticated app layouts", "Use the @topolo-io/ui-kit TopoloAccountMenu primitive when a partial-shell surface still needs account chrome", "Pass app-specific account actions as additive menu items instead of forking dropdowns", "Use shared design tokens and platform UI primitives before creating local equivalents", "Use TopoloAppMetricCard, TopoloAppEmptyState, TopoloAppStatusBadge, TopoloAppGrid, and TopoloAppSection for repeated app body patterns", "Keep visual QA fixtures available through visualQa=1 or __devpreview=1 so screenshot checks do not depend on live API state", "Keep mobile and desktop shell behavior aligned with the platform UI kit", "Constrain the app workspace-view layout wrappers with min-width: 0, width: auto, and viewport-aware max-width so shell padding cannot create page-level horizontal overflow"];
+}, {
+    readonly id: "app-registration-and-scopes";
+    readonly title: "Register protected APIs as platform apps";
+    readonly summary: "Callable app APIs need a stable app ID, app slug, permissions, role bundles, and API-key scopes before agents or users rely on them.";
+    readonly appliesTo: readonly ["api"];
+    readonly evidence: readonly ["Auth app catalog contains the app ID and slug", "Permissions, role bundles, and API-key scopes exist for the app", "SDK, CLI, and MCP app discovery include the callable production API", "CloudControl production HTTP targets classify agent reachability with sdk_app_id or agent_callable:false"];
+    readonly implementation: readonly ["Add production Worker api_url metadata and sdk_app_id for every agent-callable API target", "Mark browser, documentation, and runtime-only Worker targets with agent_callable:false", "Expose stable app IDs through live catalog discovery", "Keep typed SDK/CLI/MCP surfaces in sync when an API contract stabilizes"];
+}, {
+    readonly id: "organization-scoped-data";
+    readonly title: "Keep application data organization-scoped";
+    readonly summary: "Protected data access must be scoped by the authenticated organization at the backend boundary, not by client-provided hints.";
+    readonly appliesTo: readonly ["api"];
+    readonly evidence: readonly ["Backend request handlers derive org membership from credential validation", "Queries and Durable Object keys include the authenticated organization boundary where data is tenant-owned", "MCP and CLI inputs do not include orgId overrides"];
+    readonly implementation: readonly ["Reject or ignore organization hints supplied by clients", "Bind SQL, KV, R2, queue, and Durable Object access to the authenticated organization", "Document service-local exceptions explicitly in the system security assurance record"];
+}, {
+    readonly id: "cloudflare-deployment-contract";
+    readonly title: "Keep Cloudflare deployment metadata complete";
+    readonly summary: "Workers, Pages, bindings, routes, env vars, queues, cron triggers, and deployment commands must be discoverable through CloudControl metadata.";
+    readonly appliesTo: readonly ["browser", "api"];
+    readonly evidence: readonly ["topolo.cloudcontrol.json lists production deploy targets and URLs", "Wrangler/Pages configuration matches CloudControl metadata", "Secrets and environment variables are not committed"];
+    readonly implementation: readonly ["Update CloudControl metadata whenever deployment topology changes", "Prefer Cloudflare-native runtime surfaces for new Topolo app infrastructure", "Keep Worker bindings and Pages domains explicit enough for agents to inspect before deploying"];
+}, {
+    readonly id: "agent-and-operator-surfaces";
+    readonly title: "Expose agent-safe operations through SDK, CLI, and MCP";
+    readonly summary: "Agent-accessible functionality should be discoverable, scope-gated, and write-confirmed instead of hidden behind ad hoc HTTP calls.";
+    readonly appliesTo: readonly ["api", "tooling", "agent_surface"];
+    readonly evidence: readonly ["Read operations have typed SDK/CLI/MCP surfaces once their contract stabilizes", "Mutating generic calls require --confirm or confirm:true", "MCP tools never accept orgId and advertise only appropriate scope-gated tools"];
+    readonly implementation: readonly ["Add SDK types first, then CLI commands and MCP tools for durable workflows", "Use generic API passthrough only as a temporary escape hatch", "Keep command output JSON-stable for agents and human-readable with --no-json"];
+}, {
+    readonly id: "native-dashboard-widget";
+    readonly title: "Expose a native dashboard widget contract";
+    readonly summary: "Launchable first-party applications must populate TopoloOne live workspace through an app-owned /api/widget endpoint using the SDK widget response contract.";
+    readonly appliesTo: readonly ["api"];
+    readonly evidence: readonly ["The app-owned API exposes GET /api/widget", "The endpoint returns TopoloWidgetApiResponse from @topolo/sdk", "Every returned widget includes snapshot.summary with app-owned operational prose", "The endpoint derives organization/user context from the app auth boundary"];
+    readonly implementation: readonly ["Import createTopoloWidgetResponse from @topolo/sdk in the app backend", "Return native app metrics or action widgets instead of generic launch-card fallbacks", "Populate snapshot.summary in the producing app for every widget instead of synthesizing summaries in TopoloOne", "Add a route-level test that validates the response with validateTopoloWidgetResponse"];
+}, {
+    readonly id: "observability-and-audit";
+    readonly title: "Emit platform audit and debugging signals";
+    readonly summary: "Requests, agent actions, and operational workflows need traceable IDs, client labels, and useful failure evidence.";
+    readonly appliesTo: readonly ["api", "tooling", "agent_surface"];
+    readonly evidence: readonly ["Requests carry X-Topolo-Client and X-Topolo-Request-Id where the SDK is involved", "Agent-originated calls can include X-Topolo-Agent", "Failure modes are documented with request IDs or deployment/log lookup paths"];
+    readonly implementation: readonly ["Use TopoloClient for platform API calls rather than raw fetch where practical", "Keep logs free of secrets and tokens", "Document live smoke commands and request-id correlation in canonical docs"];
+}, {
+    readonly id: "verification-gates";
+    readonly title: "Ship with build, test, docs, and smoke verification";
+    readonly summary: "A Topolo app change is not complete until the relevant code checks and docs checks have been run or explicitly reported as blocked.";
+    readonly appliesTo: readonly ["all"];
+    readonly evidence: readonly ["Relevant package build/typecheck/test commands pass", "TopoloDocs validation passes when docs are touched", "Live or local smoke evidence is captured for user-visible or API behavior"];
+    readonly implementation: readonly ["Prefer existing package scripts before adding new tooling", "Run app-specific checks and shared docs validation for behavior changes", "Report any skipped verification with the blocker and residual risk"];
+}];
+declare function applicationRequirementScopes(application: ApplicationCatalogEntry): ApplicationRequirementScope[];
+declare function requirementsForApplication(applicationOrId: ApplicationCatalogEntry | ApplicationId): ApplicationRequirement[];
+declare function auditApplicationRequirements(applicationOrId: ApplicationCatalogEntry | ApplicationId): ApplicationRequirementAudit;
+/**
+ * Build the full audit report for a set of already-resolved catalog entries.
+ * Live callers resolve entries through the application directory and pass them
+ * here; the id-based wrapper below serves only the static-fallback path.
+ */
+declare function auditApplicationEntries(applications: readonly ApplicationCatalogEntry[]): ApplicationRequirementsAuditReport;
+declare function auditAllApplicationRequirements(applicationIds?: readonly ApplicationId[]): ApplicationRequirementsAuditReport;
+
+declare function compactActionCatalogEntry(action: TopoloActionCatalogEntry): {
+    actionId: string;
+    title: string;
+    description: string;
+    method: "PUT" | "POST" | "GET" | "PATCH" | "DELETE";
+    readOnly: boolean;
+    requiresConfirmation: boolean;
+    agentAccess: "auto" | "confirm" | "off";
+    requiredPermission: string;
+    requiredInput: string[];
+    resourceType: string | null;
+    exampleInput: Record<string, unknown> | null;
+    docsUrl: string | null;
+};
+declare function compactActionValidation(actionId: string, validation: TopoloActionValidationResult): {
+    actionId: string;
+    valid: boolean;
+    errors: TopoloActionValidationIssue[];
+};
+declare function compactActionPlan(plan: TopoloActionPlan): {
+    actionId: string;
+    valid: boolean;
+    errors: TopoloActionValidationIssue[];
+    executable: boolean;
+    confirmationRequired: boolean;
+    confirmationProvided: boolean;
+    request: {
+        method: TopoloActionCatalogEntry["method"];
+        service: string;
+        apiBaseUrl: string | null;
+        path: string;
+        query?: Record<string, string | number | boolean>;
+        body?: unknown;
+        resource?: {
+            resourceType: string;
+            resourceId: string;
+        };
+    } | null;
+    verification: string[];
+    rollbackActionId: string | null;
+    nextActionIds: string[];
+};
+declare function compactApplicationAudit(report: ApplicationRequirementsAuditReport): {
+    version: string;
+    applications: {
+        applicationId: string;
+        applicationName: string;
+        score: ApplicationRequirementScore;
+    }[];
+    migrationQueueCount: number;
+};
+
 declare const ACTION_CATALOG_DIGEST_ALGORITHM: "sha256-v1";
 interface TopoloActionDigestInput {
     actionId?: string;
@@ -1755,237 +2038,6 @@ declare const APPLICATIONS: {
     };
 };
 
-/**
- * Live application directory — resolve, enumerate, and identify platform
- * applications from the credential-scoped live registry.
- *
- * The platform scales to millions of constantly-changing applications, so no
- * compiled application map may gate behavior. The live registry
- * (`searchServices` / `getService` on the Catalog service) is the source of
- * truth. The bundled static snapshot (`applications-fallback.ts`) is consulted
- * ONLY when the registry is unreachable (network failure, no credential), and
- * as metadata enrichment for apps the registry already confirmed — it must
- * never cause a registry-known application to be rejected.
- */
-
-interface ApplicationDeployTarget {
-    name: string;
-    kind: string;
-    apiUrl: string | null;
-    domains: readonly string[];
-    routes: readonly string[];
-    appId: string | null;
-}
-interface ApplicationCatalogEntry {
-    id: string;
-    appDir: string;
-    name: string;
-    packageName: string | null;
-    productionUrl: string | null;
-    services: readonly string[];
-    deployTargets: readonly ApplicationDeployTarget[];
-}
-/**
- * Application ids are open-ended — they come from the live registry, not a
- * compiled union. Kept as a named alias for source compatibility.
- */
-type ApplicationId = string;
-/**
- * Derive the human-friendly application id from a live catalog entry: the
- * canonical slug with the vendor prefix stripped (`topolo-notify` → `notify`).
- * Falls back through name and appId (`app_topolo_notify` → `notify`). Never
- * consults a static map, so newly registered applications get a friendly id
- * without a client rebuild.
- */
-declare function friendlyAppId(entry: {
-    appId: string;
-    slug?: string | null;
-    name?: string | null;
-}): string;
-/** Synthesize a catalog entry for an application known only to the live registry. */
-declare function applicationEntryFromCatalog(live: TopoloServiceCatalogEntry): ApplicationCatalogEntry;
-type ApplicationDirectorySource = 'live' | 'static_fallback';
-interface ApplicationDirectoryApplication {
-    id: string;
-    application: ApplicationCatalogEntry;
-    source: 'live' | 'static';
-    live: TopoloServiceCatalogEntry | null;
-}
-interface ApplicationDirectory {
-    source: ApplicationDirectorySource;
-    applications: ApplicationDirectoryApplication[];
-}
-/** The subset of TopoloClient the directory helpers need (test-injectable). */
-interface ApplicationDirectoryClient {
-    searchServices(options?: {
-        query?: string;
-        cursor?: string;
-        limit?: number;
-    }): Promise<{
-        services: TopoloServiceCatalogEntry[];
-        page: {
-            nextCursor: string | null;
-        };
-    }>;
-    getService(application: string): Promise<TopoloServiceCatalogEntry>;
-}
-/** Static snapshot as a directory — the registry-unreachable fallback. */
-declare function staticApplicationDirectory(): ApplicationDirectory;
-/**
- * Enumerate every application the current credential can see in the live
- * registry (walking the continuation cursor to exhaustion). Falls back to the
- * bundled static snapshot only when the registry cannot be reached — pass
- * `null` as the client to request the fallback explicitly (e.g. no credential
- * configured).
- */
-declare function listApplicationDirectory(client: ApplicationDirectoryClient | null): Promise<ApplicationDirectory>;
-declare function formatDirectoryApplicationIds(directory: ApplicationDirectory): string;
-/**
- * Resolve one application by id, slug, or name against the live registry.
- * Registry-known apps always resolve — the static snapshot can only enrich
- * them, never reject them. When the registry is reachable and does not know
- * the application, the error lists the live ids. When the registry is
- * unreachable (or `client` is null), the static snapshot answers instead.
- */
-declare function resolveApplicationDirectoryEntry(client: ApplicationDirectoryClient | null, application: string): Promise<ApplicationDirectoryApplication>;
-
-declare const APPLICATION_REQUIREMENTS_VERSION = "2026-08-11.1";
-type ApplicationRequirementScope = 'all' | 'browser' | 'api' | 'tooling' | 'agent_surface';
-interface ApplicationRequirement {
-    id: string;
-    title: string;
-    summary: string;
-    appliesTo: readonly ApplicationRequirementScope[];
-    evidence: readonly string[];
-    implementation: readonly string[];
-}
-type ApplicationRequirementStatus = 'met' | 'partial' | 'missing' | 'needs_review';
-interface ApplicationRequirementFinding {
-    requirementId: string;
-    title: string;
-    status: ApplicationRequirementStatus;
-    reason: string;
-    evidence: readonly string[];
-    nextActions: readonly string[];
-}
-interface ApplicationRequirementScore {
-    met: number;
-    partial: number;
-    missing: number;
-    needsReview: number;
-    total: number;
-    percent: number;
-}
-interface ApplicationRequirementAudit {
-    version: string;
-    application: ApplicationCatalogEntry;
-    scopes: ApplicationRequirementScope[];
-    score: ApplicationRequirementScore;
-    findings: ApplicationRequirementFinding[];
-}
-interface ApplicationRequirementMigrationItem {
-    applicationId: ApplicationId;
-    applicationName: string;
-    requirementId: string;
-    title: string;
-    status: Exclude<ApplicationRequirementStatus, 'met'>;
-    reason: string;
-    nextActions: readonly string[];
-}
-interface ApplicationRequirementsAuditReport {
-    version: string;
-    applications: ApplicationRequirementAudit[];
-    migrationQueue: ApplicationRequirementMigrationItem[];
-}
-declare const APPLICATION_REQUIREMENTS: readonly [{
-    readonly id: "platform-metadata";
-    readonly title: "Register the application in platform metadata";
-    readonly summary: "Every app must have a stable application ID, CloudControl metadata for deployed surfaces, and package metadata where code is shipped.";
-    readonly appliesTo: readonly ["all"];
-    readonly evidence: readonly ["topolo.cloudcontrol.json exists for every deployed app surface", "package.json names the package or app when the repo ships code", "The live platform registry exposes the app through topolo apps and MCP discovery"];
-    readonly implementation: readonly ["Register the app in the live platform registry (Auth service catalog) before exposing it to agents", "Keep production URLs, Worker names, Pages projects, routes, domains, and bindings current in CloudControl metadata", "Do not leave a new Topolo* app directory without an explicit application ID"];
-}, {
-    readonly id: "canonical-docs";
-    readonly title: "Update canonical docs with the code change";
-    readonly summary: "TopoloDocs is the source of truth for application behavior, ownership, deployment shape, auth boundaries, and operations.";
-    readonly appliesTo: readonly ["all"];
-    readonly evidence: readonly ["Matching system registry entry exists in TopoloDocs", "Internal handbook coverage exists for the system", "npm run validate passes in TopoloDocs when docs are touched"];
-    readonly implementation: readonly ["Read the matching TopoloDocs system entry before coding", "Update docs in the same change when behavior, API, auth, data ownership, deployment, or operations change", "Update last_verified dates on touched canonical pages"];
-}, {
-    readonly id: "shared-auth-boundary";
-    readonly title: "Use the shared Topolo auth boundary";
-    readonly summary: "Applications must derive identity, organization, scopes, and app entitlement from TopoloAuth rather than inventing parallel auth state.";
-    readonly appliesTo: readonly ["browser", "api", "tooling", "agent_surface"];
-    readonly evidence: readonly ["@topolo/auth-client or @topolo-io/worker-runtime is used where applicable", "No public command, tool, or SDK method accepts orgId", "App slug and Auth app registration are documented for protected APIs"];
-    readonly implementation: readonly ["Use shared auth/runtime packages instead of copying token parsing, gateway, or browser storage flows", "Derive organization from the credential on every request", "Route OAuth, refresh, logout, and SSO paths according to the shared Auth contract"];
-}, {
-    readonly id: "shared-shell-and-launcher";
-    readonly title: "Use the shared shell, launcher, and account menu";
-    readonly summary: "Browser applications should feel like one platform and should not create isolated navigation or account surfaces.";
-    readonly appliesTo: readonly ["browser"];
-    readonly evidence: readonly ["@topolo-io/app-shell is used for the platform shell where the app has authenticated UI", "@topolo-io/app-launcher keeps the shared launcher/app switcher reachable from authenticated app chrome", "Account menu and sign-out behavior use TopoloAppShell or the ui-kit TopoloAccountMenu primitive", "Repeated app body surfaces use shared TopoloAppLayout primitives instead of local stat cards, empty states, or status badges", "Local preview supports deterministic visual QA fixtures for overview, list, detail, settings, and empty/loading states", "Authenticated app body content stays inside the viewport on mobile and desktop widths"];
-    readonly implementation: readonly ["Use @topolo-io/app-shell TopoloAppShell for authenticated app layouts", "Use the @topolo-io/ui-kit TopoloAccountMenu primitive when a partial-shell surface still needs account chrome", "Pass app-specific account actions as additive menu items instead of forking dropdowns", "Use shared design tokens and platform UI primitives before creating local equivalents", "Use TopoloAppMetricCard, TopoloAppEmptyState, TopoloAppStatusBadge, TopoloAppGrid, and TopoloAppSection for repeated app body patterns", "Keep visual QA fixtures available through visualQa=1 or __devpreview=1 so screenshot checks do not depend on live API state", "Keep mobile and desktop shell behavior aligned with the platform UI kit", "Constrain the app workspace-view layout wrappers with min-width: 0, width: auto, and viewport-aware max-width so shell padding cannot create page-level horizontal overflow"];
-}, {
-    readonly id: "app-registration-and-scopes";
-    readonly title: "Register protected APIs as platform apps";
-    readonly summary: "Callable app APIs need a stable app ID, app slug, permissions, role bundles, and API-key scopes before agents or users rely on them.";
-    readonly appliesTo: readonly ["api"];
-    readonly evidence: readonly ["Auth app catalog contains the app ID and slug", "Permissions, role bundles, and API-key scopes exist for the app", "SDK, CLI, and MCP app discovery include the callable production API", "CloudControl production HTTP targets classify agent reachability with sdk_app_id or agent_callable:false"];
-    readonly implementation: readonly ["Add production Worker api_url metadata and sdk_app_id for every agent-callable API target", "Mark browser, documentation, and runtime-only Worker targets with agent_callable:false", "Expose stable app IDs through live catalog discovery", "Keep typed SDK/CLI/MCP surfaces in sync when an API contract stabilizes"];
-}, {
-    readonly id: "organization-scoped-data";
-    readonly title: "Keep application data organization-scoped";
-    readonly summary: "Protected data access must be scoped by the authenticated organization at the backend boundary, not by client-provided hints.";
-    readonly appliesTo: readonly ["api"];
-    readonly evidence: readonly ["Backend request handlers derive org membership from credential validation", "Queries and Durable Object keys include the authenticated organization boundary where data is tenant-owned", "MCP and CLI inputs do not include orgId overrides"];
-    readonly implementation: readonly ["Reject or ignore organization hints supplied by clients", "Bind SQL, KV, R2, queue, and Durable Object access to the authenticated organization", "Document service-local exceptions explicitly in the system security assurance record"];
-}, {
-    readonly id: "cloudflare-deployment-contract";
-    readonly title: "Keep Cloudflare deployment metadata complete";
-    readonly summary: "Workers, Pages, bindings, routes, env vars, queues, cron triggers, and deployment commands must be discoverable through CloudControl metadata.";
-    readonly appliesTo: readonly ["browser", "api"];
-    readonly evidence: readonly ["topolo.cloudcontrol.json lists production deploy targets and URLs", "Wrangler/Pages configuration matches CloudControl metadata", "Secrets and environment variables are not committed"];
-    readonly implementation: readonly ["Update CloudControl metadata whenever deployment topology changes", "Prefer Cloudflare-native runtime surfaces for new Topolo app infrastructure", "Keep Worker bindings and Pages domains explicit enough for agents to inspect before deploying"];
-}, {
-    readonly id: "agent-and-operator-surfaces";
-    readonly title: "Expose agent-safe operations through SDK, CLI, and MCP";
-    readonly summary: "Agent-accessible functionality should be discoverable, scope-gated, and write-confirmed instead of hidden behind ad hoc HTTP calls.";
-    readonly appliesTo: readonly ["api", "tooling", "agent_surface"];
-    readonly evidence: readonly ["Read operations have typed SDK/CLI/MCP surfaces once their contract stabilizes", "Mutating generic calls require --confirm or confirm:true", "MCP tools never accept orgId and advertise only appropriate scope-gated tools"];
-    readonly implementation: readonly ["Add SDK types first, then CLI commands and MCP tools for durable workflows", "Use generic API passthrough only as a temporary escape hatch", "Keep command output JSON-stable for agents and human-readable with --no-json"];
-}, {
-    readonly id: "native-dashboard-widget";
-    readonly title: "Expose a native dashboard widget contract";
-    readonly summary: "Launchable first-party applications must populate TopoloOne live workspace through an app-owned /api/widget endpoint using the SDK widget response contract.";
-    readonly appliesTo: readonly ["api"];
-    readonly evidence: readonly ["The app-owned API exposes GET /api/widget", "The endpoint returns TopoloWidgetApiResponse from @topolo/sdk", "Every returned widget includes snapshot.summary with app-owned operational prose", "The endpoint derives organization/user context from the app auth boundary"];
-    readonly implementation: readonly ["Import createTopoloWidgetResponse from @topolo/sdk in the app backend", "Return native app metrics or action widgets instead of generic launch-card fallbacks", "Populate snapshot.summary in the producing app for every widget instead of synthesizing summaries in TopoloOne", "Add a route-level test that validates the response with validateTopoloWidgetResponse"];
-}, {
-    readonly id: "observability-and-audit";
-    readonly title: "Emit platform audit and debugging signals";
-    readonly summary: "Requests, agent actions, and operational workflows need traceable IDs, client labels, and useful failure evidence.";
-    readonly appliesTo: readonly ["api", "tooling", "agent_surface"];
-    readonly evidence: readonly ["Requests carry X-Topolo-Client and X-Topolo-Request-Id where the SDK is involved", "Agent-originated calls can include X-Topolo-Agent", "Failure modes are documented with request IDs or deployment/log lookup paths"];
-    readonly implementation: readonly ["Use TopoloClient for platform API calls rather than raw fetch where practical", "Keep logs free of secrets and tokens", "Document live smoke commands and request-id correlation in canonical docs"];
-}, {
-    readonly id: "verification-gates";
-    readonly title: "Ship with build, test, docs, and smoke verification";
-    readonly summary: "A Topolo app change is not complete until the relevant code checks and docs checks have been run or explicitly reported as blocked.";
-    readonly appliesTo: readonly ["all"];
-    readonly evidence: readonly ["Relevant package build/typecheck/test commands pass", "TopoloDocs validation passes when docs are touched", "Live or local smoke evidence is captured for user-visible or API behavior"];
-    readonly implementation: readonly ["Prefer existing package scripts before adding new tooling", "Run app-specific checks and shared docs validation for behavior changes", "Report any skipped verification with the blocker and residual risk"];
-}];
-declare function applicationRequirementScopes(application: ApplicationCatalogEntry): ApplicationRequirementScope[];
-declare function requirementsForApplication(applicationOrId: ApplicationCatalogEntry | ApplicationId): ApplicationRequirement[];
-declare function auditApplicationRequirements(applicationOrId: ApplicationCatalogEntry | ApplicationId): ApplicationRequirementAudit;
-/**
- * Build the full audit report for a set of already-resolved catalog entries.
- * Live callers resolve entries through the application directory and pass them
- * here; the id-based wrapper below serves only the static-fallback path.
- */
-declare function auditApplicationEntries(applications: readonly ApplicationCatalogEntry[]): ApplicationRequirementsAuditReport;
-declare function auditAllApplicationRequirements(applicationIds?: readonly ApplicationId[]): ApplicationRequirementsAuditReport;
-
 /**
  * Service URL resolution.
  *
@@ -2609,4 +2661,4 @@ declare function createTopolo(options: TopoloClientOptions): {
 };
 type Topolo = ReturnType<typeof createTopolo>;
 
-export { ACTION_CATALOG_DIGEST_ALGORITHM, APPLICATIONS, APPLICATION_REQUIREMENTS, APPLICATION_REQUIREMENTS_VERSION, type ActionContractManifest, type ActionContractSource, type AgentIdentity, type AppApiId, type ApplicationCatalogEntry, type ApplicationDeployTarget, type ApplicationDirectory, type ApplicationDirectoryApplication, type ApplicationDirectoryClient, type ApplicationDirectorySource, type ApplicationId, type ApplicationRequirement, type ApplicationRequirementAudit, type ApplicationRequirementFinding, type ApplicationRequirementMigrationItem, type ApplicationRequirementScope, type ApplicationRequirementScore, type ApplicationRequirementStatus, type ApplicationRequirementsAuditReport, type CredentialIntrospection, type CrmContactSummary, CrmModule, DEFAULT_APP_URLS, type DeviceAuthorizationResponse, IdentityModule, type ListContactsOptions, type ListContactsResult, type OAuthHelperOptions, type P2PActionDetail, type P2PActionRequestInput, type P2PActionRequestResult, type P2PActionRow, type P2PActionRun, type P2PCapability, type P2PConnection, type P2PHold, type P2PLedgerEntry, P2PModule, type P2PPolicy, type P2PPricingModel, type P2PSettlementBatch, type P2PSettlementGroup, type PublishCapabilityInput, type RequestOptions, type ServiceCatalogUrlEntry, TOPOLO_WIDGET_ENDPOINT, TOPOLO_WIDGET_REFRESH_INTERVAL_MS, type TokenResponse, type Topolo, type TopoloActionAgentContract, type TopoloActionCatalogEntry, type TopoloActionCatalogSummary, type TopoloActionDigestInput, type TopoloActionPlan, type TopoloActionUploadOptions, type TopoloActionValidationIssue, type TopoloActionValidationResult, type TopoloApiKeyResourceMetadata, TopoloAuthError, type TopoloBindableResource, type TopoloBindableResourceCatalog, type TopoloChartWidget, TopoloClient, type TopoloClientOptions, TopoloConfirmationRequiredError, type TopoloCredential, type TopoloDebugEvent, TopoloHttpError, type TopoloInlineBase64UploadContract, type TopoloNotificationsWidget, TopoloOAuth, TopoloPermissionError, type TopoloQuickActionsWidget, type TopoloRecentActivityWidget, TopoloSdkError, type TopoloServiceCatalogEntry, type TopoloStatsWidget, type TopoloWidget, type TopoloWidgetActionItem, type TopoloWidgetActivityItem, type TopoloWidgetApiResponse, type TopoloWidgetBase, type TopoloWidgetConfig, type TopoloWidgetDraft, type TopoloWidgetMetric, type TopoloWidgetNotificationItem, type TopoloWidgetResponseOptions, type TopoloWidgetSnapshotMetadata, type TopoloWidgetSnapshotMetric, type TopoloWidgetType, type TopoloWidgetValidationResult, type TopoloWorkspace, type TopoloWorkspaceListResult, type TopoloWorkspaceMutationResult, type TopoloWorkspacePolicy, WorkspacesModule, actionContractCompleteness, applicationEntryFromCatalog, applicationRequirementScopes, auditAllApplicationRequirements, auditApplicationEntries, auditApplicationRequirements, createTopolo, createTopoloWidgetError, createTopoloWidgetResponse, defineTopoloChartWidget, defineTopoloNotificationsWidget, defineTopoloQuickActionsWidget, defineTopoloRecentActivityWidget, defineTopoloStatsWidget, digestTopoloActionCatalog, enrichActionContract, formatDirectoryApplicationIds, friendlyAppId, listApplicationDirectory, parseTopoloActionUploadContract, prepareTopoloActionBase64UploadInput, prepareTopoloActionUploadInput, requirementsForApplication, resolveApplicationDirectoryEntry, resolveCatalogServiceUrl, resolveServiceUrl, staticApplicationDirectory, validateTopoloActionInput, validateTopoloWidgetResponse };
+export { ACTION_CATALOG_DIGEST_ALGORITHM, APPLICATIONS, APPLICATION_REQUIREMENTS, APPLICATION_REQUIREMENTS_VERSION, type ActionContractManifest, type ActionContractSource, type AgentIdentity, type AppApiId, type ApplicationCatalogEntry, type ApplicationDeployTarget, type ApplicationDirectory, type ApplicationDirectoryApplication, type ApplicationDirectoryClient, type ApplicationDirectorySource, type ApplicationId, type ApplicationRequirement, type ApplicationRequirementAudit, type ApplicationRequirementFinding, type ApplicationRequirementMigrationItem, type ApplicationRequirementScope, type ApplicationRequirementScore, type ApplicationRequirementStatus, type ApplicationRequirementsAuditReport, type CredentialIntrospection, type CrmContactSummary, CrmModule, DEFAULT_APP_URLS, type DeviceAuthorizationResponse, IdentityModule, type ListContactsOptions, type ListContactsResult, type OAuthHelperOptions, type P2PActionDetail, type P2PActionRequestInput, type P2PActionRequestResult, type P2PActionRow, type P2PActionRun, type P2PCapability, type P2PConnection, type P2PHold, type P2PLedgerEntry, P2PModule, type P2PPolicy, type P2PPricingModel, type P2PSettlementBatch, type P2PSettlementGroup, type PublishCapabilityInput, type RequestOptions, type ServiceCatalogUrlEntry, TOPOLO_WIDGET_ENDPOINT, TOPOLO_WIDGET_REFRESH_INTERVAL_MS, type TokenResponse, type Topolo, type TopoloActionAgentContract, type TopoloActionCatalogEntry, type TopoloActionCatalogSummary, type TopoloActionDigestInput, type TopoloActionPlan, type TopoloActionUploadOptions, type TopoloActionValidationIssue, type TopoloActionValidationResult, type TopoloApiKeyResourceMetadata, TopoloAuthError, type TopoloBindableResource, type TopoloBindableResourceCatalog, type TopoloChartWidget, TopoloClient, type TopoloClientOptions, TopoloConfirmationRequiredError, type TopoloCredential, type TopoloDebugEvent, TopoloHttpError, type TopoloInlineBase64UploadContract, type TopoloNotificationsWidget, TopoloOAuth, TopoloPermissionError, type TopoloQuickActionsWidget, type TopoloRecentActivityWidget, TopoloSdkError, type TopoloServiceCatalogEntry, type TopoloStatsWidget, type TopoloWidget, type TopoloWidgetActionItem, type TopoloWidgetActivityItem, type TopoloWidgetApiResponse, type TopoloWidgetBase, type TopoloWidgetConfig, type TopoloWidgetDraft, type TopoloWidgetMetric, type TopoloWidgetNotificationItem, type TopoloWidgetResponseOptions, type TopoloWidgetSnapshotMetadata, type TopoloWidgetSnapshotMetric, type TopoloWidgetType, type TopoloWidgetValidationResult, type TopoloWorkspace, type TopoloWorkspaceListResult, type TopoloWorkspaceMutationResult, type TopoloWorkspacePolicy, WorkspacesModule, actionContractCompleteness, applicationEntryFromCatalog, applicationRequirementScopes, auditAllApplicationRequirements, auditApplicationEntries, auditApplicationRequirements, compactActionCatalogEntry, compactActionPlan, compactActionValidation, compactApplicationAudit, createTopolo, createTopoloWidgetError, createTopoloWidgetResponse, defineTopoloChartWidget, defineTopoloNotificationsWidget, defineTopoloQuickActionsWidget, defineTopoloRecentActivityWidget, defineTopoloStatsWidget, digestTopoloActionCatalog, enrichActionContract, formatDirectoryApplicationIds, friendlyAppId, listApplicationDirectory, parseTopoloActionUploadContract, prepareTopoloActionBase64UploadInput, prepareTopoloActionUploadInput, requirementsForApplication, resolveApplicationDirectoryEntry, resolveCatalogServiceUrl, resolveServiceUrl, staticApplicationDirectory, validateTopoloActionInput, validateTopoloWidgetResponse };