@vibesdotdev/kit 0.0.0-stage → 1.0.0-rc.3

package/dist/lib/server/index.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Server-only vibeskit exports
+ *
+ * WARNING: This barrel includes server-only dependencies (Redis, ioredis, etc.)
+ * DO NOT import from this file in client-side code (Svelte components, stores, etc.)
+ *
+ * For client-safe exports, use: import { ... } from '../index.ts/client'
+ */
+export type { VibesKitLocals, VibesKitUser, VibesKitBilling, VibesKitHostname, VibesKitOrgClaim, VibesKitPreferences, KitJsonValue, VibesKitRuntimePort, KitScope } from './locals.js';
+export { requireKitRuntime, KitRuntimeUnavailableError } from './locals.js';
+export { kitLogger } from '../kit-logger.js';
+export type { KitLogger } from '../kit-logger.js';
+export { resolveActiveOrgRole } from './locals.js';
+export { createVibesServerFetch, vibesServerRequestHeaders } from './outbound.ts';
+export type { VibesServerFetch, VibesServerFetchOptions } from './outbound.ts';
+export { createVibesKit, getVibesKit, hasVibesKit } from '../instance.js';
+export type { VibesKit } from '../types/kit.js';
+export { createAppVibesKit, kitCatalogAppOrigin, kitCatalogEnvironmentId, loadKitConfig, loadKitConfigDefaults } from './app-bootstrap.js';
+export type { AppVibesKitOrigin, CreateAppVibesKitOptions } from './app-bootstrap.js';
+export { createVibesStandardServices, createVibesStandardAuth, createVibesStandardAuthHandles } from './standard.ts';
+export type { VibesStandardServicesOptions, VibesStandardAuthOptions } from './standard.ts';
+export { withResponseCache, createCachePresets, CacheConditions, CacheKeyGenerators } from './middleware/response-cache.js';
+export type { KitCachePort, ResponseCacheOptions } from './middleware/response-cache.js';
+export { createScopeHandle } from './handles/scope-context.js';
+export type { ScopeHandleOptions } from './handles/scope-context.js';
+export { createAccountBillingAdapter, setBillingRequestCookie } from './services/account-billing-adapter.js';
+export type { AccountBillingAdapterOptions, AccountServiceBinding } from './services/account-billing-adapter.js';
+export { createAuthPermissionsAdapter } from './services/auth-permissions-adapter.js';
+export type { AuthPermissionsAdapterOptions, AuthServiceBinding } from './services/auth-permissions-adapter.js';
+export { ServiceBindingSchema } from './services/service-binding-runtime.js';
+export type { ServiceBindingFetcher } from './services/service-binding-runtime.js';
+export { createIterableResponse } from './endpoint/iterable-response.ts';
+export { vibesGET, vibesPOST, vibesPUT, vibesPATCH, vibesDELETE, vibesSSE, vibesEndpoint, vibesWrapper, createVibesEndpoints, type VibesEndpointHost } from './endpoint/wrapper';
+export { endpointRedirect } from './endpoint/redirect';
+export { requireSameOriginPost, resolveExpectedOrigin } from './endpoint/same-origin';
+export { vibesPageLoad, vibesLayoutLoad, vibesAction } from './page/load';
+export { vibesFormAction } from './action';
+export type { LoadConfig, LoadHandler, ActionHandler, VibesRequestEvent } from './page/load';
+export type { FormActionConfig } from './action';
+export { vibesLayoutLoad as vibesLayout, vibesLayoutAuth, vibesLayoutFeature } from './layout/load';
+export type { VibesLayoutLoadOptions, FeatureGateOptions } from './layout/load';
+export { createVibesHandle, createBasicVibesHandle, createVibesErrorHandler, createMaintenanceHandle, createAuthHandle, createAuthWrapperHandle, createActivityHandle, applySecurityHeaders, matchSecurityProfile, applySecurityProfile, enhanceUserContext, createPreferenceLoader, shouldSkipActivityLogging, isPublicRoute, isAssetRequest, serializeError, createCacheControlHandle, applyCacheControl, createCorsHandle } from './hooks';
+export { createUserContextHandle, invalidateUserContext, createActiveProjectHandle, checkProjectAccessViaProjectsApi, invalidateActiveProjectAccess, readActiveProjectCookie, setActiveProjectCookie, ACTIVE_PROJECT_COOKIE_NAME, createActiveOrgHandle, readActiveOrgCookie, setActiveOrgCookie, ACTIVE_ORG_COOKIE_NAME, createOrgMembershipHandle, scopeFromLocals, tryScopeFromLocals, actingScopeFromLocals, matchesActingOwner, createAuthEnforcementHandle, createActiveUserGateHandle, createDemoAwareAuthEnforcementHandle, createDemoAwareActiveUserGateHandle, createDemoBannerHandle, createPermissionFetchHandle, invalidatePermissionCache } from './handles';
+export type { UserContextHandleOptions, AuthEnforcementOptions, ActiveUserGateOptions, ActiveUserStatus, PermissionFetchHandleOptions, VibesScope, ActingScope } from './handles';
+export type { VibesHandleConfig, SecurityConfig, MaintenanceConfig, AuthConfig, ActivityConfig, ActivityLogEntry, ActivityLoggerFunction, CSPConfig, SecurityHeadersConfig, SecurityPattern, ContextLoaders, UserContextConfig, ErrorHandlerConfig, CacheControlOptions } from './hooks';
+export type { VibesConfig, VibesHandler, VibesContext, AuthConfig as VibesAuthConfig, RateLimitConfig, CachingConfig, BillingConfig, ValidationConfig, MetadataConfig } from '../types';
+export { auth, permissions, roles, rateLimit, rateLimitPatterns, cache, cachePatterns, normalizePlanSlug, normalizePlanComparisonValue, normalizeTierSlug, canonicalTierPriority, planPriorityOrder, comparePlanPriority, isPlanAtLeast, isPlanOneOf, billing, billingPatterns, requireFeatures, customBilling, freeTier, premiumOnly, dynamicCredits, rateBased, tieredBilling, experimental, beta, params, query, body, headers, validation, response, isDemoMode, checkDemoMode, createDemoSessionCookie, clearDemoSessionCookie, requireServiceOrigin, type RequireServiceOriginOptions } from './helpers';
+export { applyRateLimit, globalRateLimiter, rateLimitUtils, RateLimitError, isRateLimitExemptIdentity } from './middleware/rate-limiter';
+export { assertBodyWithinLimit, validateRequestSize, ValidationError } from './middleware/validation';
+export { getClientIp, getClientIpFromHeaders } from '../utils/client-ip';
+export { VibesCacheManager, createCacheManager, invalidateCache, type CacheInvalidation, cacheUtils, cacheWarming, cacheMiddleware } from './middleware/cache-manager';
+export { globalPermissionChecker, permissionUtils, permissionMiddleware, AuthenticationError, PermissionError } from './middleware/permission-checker';
+export { quick, combine } from './api-presets';
+/** Common endpoint method names for Kit's endpoint wrapper. */
+export { vibesGET as GET, vibesPOST as POST, vibesPUT as PUT, vibesPATCH as PATCH, vibesDELETE as DELETE, vibesSSE as SSE } from './endpoint/wrapper';

package/dist/lib/server/index.js

@@ -0,0 +1,76 @@
+/**
+ * Server-only vibeskit exports
+ *
+ * WARNING: This barrel includes server-only dependencies (Redis, ioredis, etc.)
+ * DO NOT import from this file in client-side code (Svelte components, stores, etc.)
+ *
+ * For client-safe exports, use: import { ... } from '../index.ts/client'
+ */
+export { requireKitRuntime, KitRuntimeUnavailableError } from './locals.js';
+// Logger seam: the host injects `services.logger`; kit modules log through it.
+export { kitLogger } from '../kit-logger.js';
+// The generic org-role rule: prefer the verified claim, fall back to the account
+// context. Consumers enforcing org roles call this instead of carrying a copy.
+export { resolveActiveOrgRole } from './locals.js';
+export { createVibesServerFetch, vibesServerRequestHeaders } from "./outbound.js";
+// Instance management
+export { createVibesKit, getVibesKit, hasVibesKit } from '../instance.js';
+// Canonical first-party-app bootstrap preset (consumed by each app's vibeskit.ts)
+export { createAppVibesKit, kitCatalogAppOrigin, kitCatalogEnvironmentId, loadKitConfig, loadKitConfigDefaults } from './app-bootstrap.js';
+// Vibes-standard SvelteKit setup helpers
+export { createVibesStandardServices, createVibesStandardAuth, createVibesStandardAuthHandles } from "./standard.js";
+// Response caching (host supplies the cache port per request)
+export { withResponseCache, createCachePresets, CacheConditions, CacheKeyGenerators } from './middleware/response-cache.js';
+// Scope handle (host supplies the scope resolver)
+export { createScopeHandle } from './handles/scope-context.js';
+// Billing adapter
+export { createAccountBillingAdapter, setBillingRequestCookie } from './services/account-billing-adapter.js';
+// Auth permissions adapter
+export { createAuthPermissionsAdapter } from './services/auth-permissions-adapter.js';
+// Service bindings: the owning schema for `runtime.getBinding(key, schema)`
+export { ServiceBindingSchema } from './services/service-binding-runtime.js';
+export { createIterableResponse } from "./endpoint/iterable-response.js";
+// Core wrapper functions
+export { vibesGET, vibesPOST, vibesPUT, vibesPATCH, vibesDELETE, vibesSSE, vibesEndpoint, vibesWrapper, createVibesEndpoints } from './endpoint/wrapper';
+// +server.ts redirect helper — see endpoint/redirect.ts for why we
+// don't use SvelteKit's `redirect()` in endpoint handlers under bun.
+export { endpointRedirect } from './endpoint/redirect';
+export { requireSameOriginPost, resolveExpectedOrigin } from './endpoint/same-origin';
+// Server-side load function wrappers
+export { vibesPageLoad, vibesLayoutLoad, vibesAction } from './page/load';
+export { vibesFormAction } from './action';
+// Server-side layout helpers with feature gating
+export { vibesLayoutLoad as vibesLayout, vibesLayoutAuth, vibesLayoutFeature } from './layout/load';
+// Hooks integration for SvelteKit
+export { createVibesHandle, createBasicVibesHandle, createVibesErrorHandler, createMaintenanceHandle, createAuthHandle, createAuthWrapperHandle, createActivityHandle, applySecurityHeaders, matchSecurityProfile, applySecurityProfile, enhanceUserContext, createPreferenceLoader, shouldSkipActivityLogging, isPublicRoute, isAssetRequest, serializeError, createCacheControlHandle, applyCacheControl, createCorsHandle } from './hooks';
+// Composable handles for the handle chain
+export { createUserContextHandle, invalidateUserContext, createActiveProjectHandle, checkProjectAccessViaProjectsApi, invalidateActiveProjectAccess, readActiveProjectCookie, setActiveProjectCookie, ACTIVE_PROJECT_COOKIE_NAME, createActiveOrgHandle, readActiveOrgCookie, setActiveOrgCookie, ACTIVE_ORG_COOKIE_NAME, createOrgMembershipHandle, scopeFromLocals, tryScopeFromLocals, actingScopeFromLocals, matchesActingOwner, createAuthEnforcementHandle, createActiveUserGateHandle, createDemoAwareAuthEnforcementHandle, createDemoAwareActiveUserGateHandle, createDemoBannerHandle, createPermissionFetchHandle, invalidatePermissionCache } from './handles';
+// Helper functions
+export { 
+// Authentication helpers
+auth, permissions, roles, 
+// Rate limiting helpers
+rateLimit, rateLimitPatterns, 
+// Caching helpers
+cache, cachePatterns, 
+// Billing helpers
+normalizePlanSlug, normalizePlanComparisonValue, normalizeTierSlug, canonicalTierPriority, planPriorityOrder, comparePlanPriority, isPlanAtLeast, isPlanOneOf, billing, billingPatterns, requireFeatures, customBilling, freeTier, premiumOnly, dynamicCredits, rateBased, tieredBilling, experimental, beta, 
+// Validation helpers
+params, query, body, headers, validation, response, isDemoMode, checkDemoMode, createDemoSessionCookie, clearDemoSessionCookie, 
+// Service-origin resolution (catalog default, host overlay when passed)
+requireServiceOrigin } from './helpers';
+// Middleware utilities (SERVER ONLY - includes Redis dependencies)
+export { applyRateLimit, globalRateLimiter, rateLimitUtils, RateLimitError, isRateLimitExemptIdentity } from './middleware/rate-limiter';
+// Transport-agnostic request body-cap primitive (shared with plain-Worker hosts).
+export { assertBodyWithinLimit, validateRequestSize, ValidationError } from './middleware/validation';
+// Client IP extraction (SERVER ONLY - uses RequestEvent)
+export { getClientIp, getClientIpFromHeaders } from '../utils/client-ip';
+export { VibesCacheManager, createCacheManager, invalidateCache, cacheUtils, cacheWarming, cacheMiddleware } from './middleware/cache-manager';
+export { globalPermissionChecker, permissionUtils, permissionMiddleware, AuthenticationError, PermissionError } from './middleware/permission-checker';
+// API config presets (`quick`, `combine`) live in api-presets.ts so this
+// barrel stays a pure re-export shape (matches the sibling pattern of
+// helpers/index.ts, hooks/index.ts, handles/index.ts — all of which
+// emit .d.ts cleanly through svelte-package).
+export { quick, combine } from './api-presets';
+/** Common endpoint method names for Kit's endpoint wrapper. */
+export { vibesGET as GET, vibesPOST as POST, vibesPUT as PUT, vibesPATCH as PATCH, vibesDELETE as DELETE, vibesSSE as SSE } from './endpoint/wrapper';

package/dist/lib/server/layout/load.d.ts

@@ -0,0 +1,57 @@
+import { type RequestEvent } from '@sveltejs/kit';
+import { type VibesKitLocals } from '../locals.js';
+export interface FeatureGateOptions {
+    /** Feature slug to check access for */
+    feature: string;
+    /** Recommended plan tier if user needs to upgrade */
+    recommendedPlan?: 'free' | 'plus' | 'pro' | 'ultra' | 'team-standard' | 'team-plus' | 'team-ultra' | 'enterprise';
+    /** Custom redirect URL if access denied (defaults to upgrade page) */
+    redirectUrl?: string;
+}
+export interface VibesLayoutLoadOptions {
+    /** Require authentication */
+    requireAuth?: boolean;
+    /** Require specific feature access */
+    requireFeature?: FeatureGateOptions;
+    /** Custom auth redirect URL */
+    authRedirectUrl?: string;
+}
+/**
+ * What a layout's own loader returns: an object (not an array or primitive)
+ * that is merged under the wrapper's `user`. Callers choose its shape.
+ */
+export type LayoutData = object;
+/** A layout's own data loader. */
+export type LayoutLoadFunction<T extends LayoutData> = (event: RequestEvent) => T | Promise<T>;
+/** What every wrapped layout returns alongside its own data. */
+export interface LayoutUserData {
+    user: VibesKitLocals['user'] | null;
+}
+/**
+ * VibesKit wrapper for SvelteKit layout server load functions.
+ * Handles common patterns like auth checks and feature gating.
+ *
+ * @example
+ * ```ts
+ * export const load = vibesLayoutLoad({
+ *   requireAuth: true,
+ *   requireFeature: {
+ *     feature: 'workbench',
+ *     recommendedPlan: 'pro'
+ *   }
+ * }, async ({ locals }) => {
+ *   return { customData: 'value' };
+ * });
+ * ```
+ */
+export declare function vibesLayoutLoad<T extends LayoutData = LayoutData>(options: VibesLayoutLoadOptions, loadFn?: LayoutLoadFunction<T>): (event: RequestEvent) => Promise<T & LayoutUserData>;
+/**
+ * Simplified wrapper for layouts that only need auth
+ */
+export declare function vibesLayoutAuth<T extends LayoutData = LayoutData>(options: {
+    authRedirectUrl?: string;
+}, loadFn?: LayoutLoadFunction<T>): (event: RequestEvent) => Promise<T & LayoutUserData>;
+/**
+ * Simplified wrapper for feature-gated layouts
+ */
+export declare function vibesLayoutFeature<T extends LayoutData = LayoutData>(options: FeatureGateOptions, loadFn?: LayoutLoadFunction<T>): (event: RequestEvent) => Promise<T & LayoutUserData>;

package/dist/lib/server/layout/load.js

@@ -0,0 +1,59 @@
+import { error, redirect } from '@sveltejs/kit';
+import { getVibesKit } from '../../instance';
+import { asVibesKitLocals, requireKitRuntime } from '../locals.js';
+export function vibesLayoutLoad(options, loadFn) {
+    return async (event) => {
+        const { url } = event;
+        const locals = asVibesKitLocals(event.locals);
+        // Auth check. A feature gate is about a signed-in user, so it requires one too.
+        if ((options.requireAuth || options.requireFeature) && !locals.user) {
+            const redirectTo = options.authRedirectUrl || `/auth?redirect=${encodeURIComponent(url.pathname)}`;
+            throw redirect(302, redirectTo);
+        }
+        // Feature gate check
+        if (options.requireFeature && locals.user) {
+            const kit = getVibesKit();
+            const billing = kit.config.services?.billing;
+            // A gate with nobody to answer it is a refusal, never a pass.
+            if (!billing) {
+                const refusal = {
+                    message: 'Billing service unavailable',
+                    code: 'billing-service-unavailable'
+                };
+                throw error(503, refusal);
+            }
+            const { feature, recommendedPlan, redirectUrl } = options.requireFeature;
+            const runtime = requireKitRuntime(locals);
+            const hasAccess = await billing.hasFeatureAccess(runtime, locals.user.id, feature);
+            if (!hasAccess) {
+                let upgradeUrl = redirectUrl;
+                if (!upgradeUrl) {
+                    upgradeUrl = await billing.getUpgradeUrl(runtime, feature, recommendedPlan || 'pro', url.pathname, feature);
+                }
+                throw redirect(302, upgradeUrl);
+            }
+        }
+        // Call custom load function if provided
+        const customData = loadFn ? await loadFn(event) : undefined;
+        // Return merged data
+        return {
+            ...customData,
+            user: locals.user || null
+        };
+    };
+}
+/**
+ * Simplified wrapper for layouts that only need auth
+ */
+export function vibesLayoutAuth(options, loadFn) {
+    return vibesLayoutLoad({ requireAuth: true, ...options }, loadFn);
+}
+/**
+ * Simplified wrapper for feature-gated layouts
+ */
+export function vibesLayoutFeature(options, loadFn) {
+    return vibesLayoutLoad({
+        requireAuth: true,
+        requireFeature: options
+    }, loadFn);
+}

package/dist/lib/server/locals.d.ts

@@ -0,0 +1,327 @@
+/**
+ * VibesKit Locals Contract
+ *
+ * This module owns the canonical shape of `App.Locals` fields that vibeskit
+ * populates during its handle chain. Consuming apps MUST merge this interface
+ * into their `App.Locals` declaration so that TypeScript accepts the fields
+ * vibeskit writes and reads.
+ *
+ * In your app's `src/app.d.ts`:
+ *
+ * ```ts
+ * import type { VibesKitLocals } from '../index.ts/server';
+ * declare global {
+ *   namespace App {
+ *     interface Locals extends VibesKitLocals {}
+ *   }
+ * }
+ * export {};
+ * ```
+ *
+ * Internally, vibeskit modules access `event.locals` through this contract via
+ * `const locals = event.locals as VibesKitLocals` at module function boundaries.
+ * This ensures fresh-checkout compilation (where App.Locals is not yet merged)
+ * still type-checks cleanly.
+ */
+import type { ZodType } from 'zod/v4';
+import { CapabilityError } from '@vibesdotdev/kernel';
+import type { UserStatus } from './hooks/user-status.ts';
+/**
+ * Structural actor scope. Kit copies only the fields it and its apps read; the
+ * owning scope package's `Scope` is assignable to this shape, so kit imports
+ * no framework package. Fields beyond these stay on the owner's own type.
+ */
+export interface KitScope {
+    account: {
+        userId: string;
+    };
+    tier: {
+        slug: string;
+    };
+    system?: {
+        orgId: string;
+        role: string;
+    };
+    org?: {
+        orgId: string;
+        slug: string;
+        role: string;
+        tierSlug?: string;
+    };
+    team?: {
+        teamId: string;
+        orgId: string;
+        role: string;
+    };
+    project?: {
+        projectId: string;
+        role: string;
+    };
+}
+/** A value that survives JSON: what crosses a wire or sits in a stored document. */
+export type KitJsonValue = string | number | boolean | null | KitJsonValue[] | {
+    [key: string]: KitJsonValue;
+};
+/** Stored user preferences: persisted as JSON, so every value is a JSON value. */
+export interface VibesKitPreferences {
+    [key: string]: KitJsonValue;
+}
+/**
+ * The user shape vibeskit relies on across its handle chain.
+ * Apps may use a richer user type; vibeskit only requires these fields.
+ */
+/**
+ * One organization membership carried by the VERIFIED session JWT.
+ *
+ * auth-web's `definePayload` is the single seam that mints this claim
+ * (`loadOrgMembershipClaim` → `{ id, role, slug }`), and `applyJwtPayload` in
+ * `@vibesdotdev/auth` publishes it to `locals.user.orgs`. Declared structurally
+ * here — vibeskit deliberately does not depend on `@vibesdotdev/auth`; auth is a
+ * producer that writes into locals, not a dependency of the kit.
+ */
+export interface VibesKitOrgClaim {
+    id: string;
+    role: string;
+    slug?: string | null;
+}
+export interface VibesKitUser {
+    id: string;
+    email?: string | null;
+    name?: string | null;
+    /** Vibes operator staff flag — grants staff-bypass in permission checks. */
+    staff?: boolean;
+    /**
+     * Superuser flag from the verified JWT. Read this rather than
+     * `userContext.user.isSuperuser` when the check must survive a degraded
+     * account-web — the token is signed and needs no subrequest.
+     */
+    isSuperuser?: boolean;
+    /**
+     * The user's organizations, straight off the verified JWT. Authorization
+     * checks read membership HERE — auth-web's `definePayload` states consumer
+     * apps "MUST NOT fetch membership per-request". Absent/empty on tokens
+     * minted before the claim existed, so treat empty as "unknown", not "none".
+     */
+    orgs?: VibesKitOrgClaim[];
+    /** ISO-8601 timestamp used by the referral attribution handle. */
+    createdAt?: string;
+}
+/**
+ * The billing context injected by the billing middleware.
+ */
+export interface VibesKitBilling {
+    subscription?: {
+        status: string;
+    } | null;
+    planSlug: string | null;
+    planTier: string | null;
+    normalizedPlan: string | null;
+    hasActiveSubscription: boolean;
+}
+/**
+ * The hostname resolution context injected by the hostname plugin.
+ */
+export interface VibesKitHostname {
+    domain: string;
+    projectId?: string | null;
+    projectSlug?: string;
+    projectName?: string;
+    ownerId?: string;
+    ownerType?: string;
+    deployTarget?: 'kubernetes' | 'cloudflare';
+    accountSlug?: string;
+    [key: string]: string | null | undefined;
+}
+/**
+ * All `App.Locals` fields that vibeskit populates or reads during its handle
+ * chain. Apps consuming `@vibesdotdev/kit` server handles MUST extend this
+ * interface in their own `App.Locals` declaration.
+ */
+/** Structural host port; Kit does not resolve or import the runtime owner. */
+export interface VibesKitRuntimePort {
+    /**
+     * A native binding decoded by its owning schema, as `RuntimeRef.getBinding`
+     * answers it: `undefined` when absent; a present binding the schema refuses
+     * throws `binding-invalid`. Service bindings use `ServiceBindingSchema`.
+     */
+    getBinding<T>(key: string, schema: ZodType<T>): T | undefined;
+    /** Declared non-secret host value; `undefined` when not declared. */
+    getEnv(key: string): string | undefined;
+    /** Structural copy of the runtime credential resolver (no import). */
+    resolveCredential(descriptor: {
+        source: 'secret';
+        key: string;
+    }): Promise<{
+        ok: true;
+        value: string;
+    } | {
+        ok: false;
+        error: Error;
+    }>;
+    /** Environment tier qualifier; kit catalog origins read this. Hosting is the Workers-vs-local fact. */
+    scope?: {
+        qualifiers?: {
+            environmentTier?: unknown;
+            dev?: unknown;
+        };
+        hosting?: {
+            mode?: string;
+            venue?: string;
+            provider?: string;
+        };
+    };
+    /**
+     * Host facts the runtime projects. A Node/Bun adapter exposes `getPlatform`
+     * (`darwin` / `linux` / …); a workerd isolate does not.
+     */
+    localEnvironment?: {
+        getPlatform?: () => string;
+    };
+    hasKind?(kind: string): boolean;
+    query?: import('@vibesdotdev/config/manifest/config-manifest').ConfigManifestRuntime['query'];
+}
+/** Thrown when a kit seam needs the host runtime and `locals.runtime` is absent. */
+export declare class KitRuntimeUnavailableError extends CapabilityError {
+    constructor();
+}
+/**
+ * Return the request's runtime port or throw a typed `runtime-unavailable`
+ * error. There is no ambient fallback: the host must hand the runtime through
+ * `event.locals.runtime`.
+ */
+export declare function requireKitRuntime(locals: {
+    runtime?: VibesKitRuntimePort;
+}): VibesKitRuntimePort;
+export interface VibesKitLocals {
+    /** Prepared by the host before runtime-bound handles. */
+    runtime?: VibesKitRuntimePort;
+    /**
+     * Authenticated user populated by the auth session handle.
+     * null/undefined when the request is unauthenticated.
+     */
+    user?: VibesKitUser | null;
+    /** Present after createPermissionFetchHandle has run. */
+    permissions?: Array<{
+        id: string;
+        name: string;
+        resource: string;
+        action: string;
+    }>;
+    /** Present after createPermissionFetchHandle has run. */
+    roles?: Array<{
+        id: string;
+        name: string;
+    }>;
+    /**
+     * Full user context fetched from account app by createUserContextHandle.
+     * Shape is app-defined; vibeskit treats it as `unknown` but sets it.
+     */
+    userContext?: unknown;
+    /**
+     * Why `userContext` is null, when it is null because the fetch FAILED
+     * rather than because the request is unauthenticated.
+     *
+     * createUserContextHandle treats a context failure as non-fatal and leaves
+     * `userContext` null. Downstream gates cannot tell that apart from "this
+     * user genuinely has nothing", so a transient account-web 401 used to
+     * surface as a false membership DENIAL. Consult this before denying: an
+     * empty context you failed to fetch is unknown, not empty.
+     */
+    userContextError?: string | null;
+    /**
+     * The active project ID for data scoping.
+     * null = "All Projects" (show all user's data).
+     * Populated by createActiveProjectHandle.
+     */
+    activeProjectId?: string | null;
+    /**
+     * The active organization ID for data scoping.
+     * null = personal workspace / admin bypass / no org acting context.
+     * Populated by createActiveOrgHandle or createOrgMembershipHandle.
+     */
+    activeOrgId?: string | null;
+    /**
+     * The active team ID for data scoping within the current organization.
+     * null = org-level scope with no team binding.
+     * Populated by createActiveTeamHandle.
+     */
+    activeTeamId?: string | null;
+    /** Canonical request scope composed by createScopeHandle. */
+    scope?: KitScope;
+    /** User preferences. Populated by enhanceUserContext / createPreferenceLoader. */
+    preferences?: VibesKitPreferences;
+    /** Account status recorded by the user-status routing handle. */
+    userStatus?: UserStatus;
+    /** Billing context injected by the billing middleware in vibesEndpoint. */
+    billing?: VibesKitBilling | null;
+    /** Unique request ID for distributed tracing. Set by createVibesHandle. */
+    requestId?: string;
+    /** Correlation ID for distributed tracing. Set by createVibesHandle. */
+    correlationId?: string;
+    /** Session context. Shape varies by auth provider. */
+    session?: unknown;
+    /**
+     * Current verified session token for same-request outbound calls. Auth may
+     * refresh an expired cookie after request construction, so server bridges
+     * must prefer this value over the raw inbound cookie/authorization header.
+     */
+    sessionToken?: string | null;
+    /** Hostname resolution context injected by the hostname plugin. */
+    hostname?: VibesKitHostname;
+    /** Set by permission middleware when the endpoint must verify resource ownership. */
+    requiresOwnershipCheck?: boolean;
+}
+/**
+ * Cast `event.locals` to `VibesKitLocals` at a module function boundary.
+ *
+ * Use this helper at the top of handle/middleware/hook function bodies so all
+ * downstream locals accesses are typed without per-line casts.
+ *
+ * This is a zero-runtime-cost structural assertion — `event.locals` IS the
+ * same object; we are only narrowing the type seen by TypeScript.
+ *
+ * @example
+ * ```ts
+ * import { asVibesKitLocals } from '../index.ts/server/locals';
+ *
+ * async function myHandle({ event, resolve }) {
+ *   const locals = asVibesKitLocals(event.locals);
+ *   locals.requestId = generateId();
+ *   return resolve(event);
+ * }
+ * ```
+ */
+export declare function asVibesKitLocals(locals: App.Locals): VibesKitLocals;
+/**
+ * Resolve the caller's membership role in the active organization.
+ *
+ * Lives here rather than in an org app because nothing about it is
+ * org-specific: it is the generic "prefer the signed claim, fall back to the
+ * account context" rule that any consumer app enforcing org roles needs.
+ * Casework carried its own copy, which is both a doctrine violation (org apps
+ * hold preferences, not logic) and how the two ended up able to disagree.
+ *
+ * ORDER IS THE POINT. The VERIFIED JWT claim is consulted first: it is signed
+ * and needs no subrequest, so a degraded account-web cannot silently demote an
+ * admin. Reading the context alone made every WRITE only as available as
+ * account-web — a failed hop returned null, null is not a writer role, and the
+ * caller was told "you do not have permission", an authorization verdict stated
+ * on the strength of a network error.
+ *
+ * Structural inputs on purpose: vibeskit does not depend on `@vibesdotdev/auth`
+ * or on the account context types. Auth is a producer that writes into locals,
+ * not a dependency of the kit.
+ */
+export declare function resolveActiveOrgRole(input: {
+    activeOrgId?: string | null;
+    /** `locals.user.orgs` — the verified claim. */
+    orgs?: readonly VibesKitOrgClaim[] | null;
+    /** `locals.userContext.organizations` — the fallback. */
+    contextOrganizations?: readonly {
+        id?: string;
+        membership?: {
+            organizationId?: string;
+            role?: string;
+        } | null;
+    }[] | null;
+}): string | null;