@stndrds/schema 1.0.0-alpha.264 → 1.0.0-alpha.266

package/dist/exceptions.d.mts

@@ -0,0 +1,471 @@
+import { S as SchemaOperation } from './migrations-BXd2ZGfM.mjs';
+import './attributes-lBLiOIY3.mjs';
+import '@stndrds/constants';
+import './utils.mjs';
+
+/**
+ * Error codes for schema exceptions
+ */
+declare const SchemaErrorCode: {
+    readonly UNKNOWN: "SCHEMA_UNKNOWN_ERROR";
+    readonly OBJECT_NOT_FOUND: "SCHEMA_OBJECT_NOT_FOUND";
+    readonly ATTRIBUTE_NOT_FOUND: "SCHEMA_ATTRIBUTE_NOT_FOUND";
+    readonly RECORD_NOT_FOUND: "SCHEMA_RECORD_NOT_FOUND";
+    readonly ROLE_NOT_FOUND: "SCHEMA_ROLE_NOT_FOUND";
+    readonly MEMORY_NOT_FOUND: "SCHEMA_MEMORY_NOT_FOUND";
+    readonly SCHEMA_PLAN_NOT_FOUND: "SCHEMA_PLAN_NOT_FOUND";
+    readonly VALIDATION_FAILED: "SCHEMA_VALIDATION_FAILED";
+    readonly INVALID_ATTRIBUTE_NAME: "SCHEMA_INVALID_ATTRIBUTE_NAME";
+    readonly INVALID_OBJECT_NAME: "SCHEMA_INVALID_OBJECT_NAME";
+    readonly PROTECTED_OBJECT: "SCHEMA_PROTECTED_OBJECT";
+    readonly PROTECTED_ATTRIBUTE: "SCHEMA_PROTECTED_ATTRIBUTE";
+    readonly PROTECTED_VIEW: "SCHEMA_PROTECTED_VIEW";
+    readonly PROTECTED_ROLE: "SCHEMA_PROTECTED_ROLE";
+    readonly FORBIDDEN: "SCHEMA_FORBIDDEN";
+    readonly ACCESS_DENIED: "SCHEMA_ACCESS_DENIED";
+    readonly CONNECTOR_AUTH_FAILED: "SCHEMA_CONNECTOR_AUTH_FAILED";
+    readonly CONNECTOR_INVALID_STATE: "SCHEMA_CONNECTOR_INVALID_STATE";
+    readonly SYNC_FAILED: "SCHEMA_SYNC_FAILED";
+    readonly SYNC_CONFLICT: "SCHEMA_SYNC_CONFLICT";
+    readonly SYNC_CASCADE: "SCHEMA_SYNC_CASCADE";
+    readonly ORPHAN_SYSTEM_ATTRIBUTE: "SCHEMA_ORPHAN_SYSTEM_ATTRIBUTE";
+    readonly SYSTEM_ENTITY_IMMUTABLE: "SCHEMA_SYSTEM_ENTITY_IMMUTABLE";
+    readonly DESTRUCTIVE_NOT_ALLOWED: "SCHEMA_DESTRUCTIVE_NOT_ALLOWED";
+    readonly MIGRATION_TIMEOUT: "SCHEMA_MIGRATION_TIMEOUT";
+    readonly CHANGE_TYPE_NOT_SUPPORTED: "SCHEMA_CHANGE_TYPE_NOT_SUPPORTED";
+    readonly DUPLICATE: "SCHEMA_DUPLICATE";
+    readonly DUPLICATE_OBJECT: "SCHEMA_DUPLICATE_OBJECT";
+    readonly DUPLICATE_ATTRIBUTE: "SCHEMA_DUPLICATE_ATTRIBUTE";
+    readonly CONFLICT: "SCHEMA_CONFLICT";
+    readonly STORAGE_UPLOAD_FAILED: "SCHEMA_STORAGE_UPLOAD_FAILED";
+    readonly STORAGE_DOWNLOAD_FAILED: "SCHEMA_STORAGE_DOWNLOAD_FAILED";
+    readonly STORAGE_DELETE_FAILED: "SCHEMA_STORAGE_DELETE_FAILED";
+    readonly STORAGE_URL_FAILED: "SCHEMA_STORAGE_URL_FAILED";
+    readonly REPOSITORY_CREATE_FAILED: "SCHEMA_REPOSITORY_CREATE_FAILED";
+    readonly REPOSITORY_UPDATE_FAILED: "SCHEMA_REPOSITORY_UPDATE_FAILED";
+    readonly REPOSITORY_DELETE_FAILED: "SCHEMA_REPOSITORY_DELETE_FAILED";
+    readonly REPOSITORY_QUERY_FAILED: "SCHEMA_REPOSITORY_QUERY_FAILED";
+    readonly NOT_IMPLEMENTED: "SCHEMA_NOT_IMPLEMENTED";
+    readonly TIMEOUT: "SCHEMA_TIMEOUT";
+    readonly RECORD_REFERENCED: "SCHEMA_RECORD_REFERENCED";
+    readonly ATTRIBUTE_IN_USE: "SCHEMA_ATTRIBUTE_IN_USE";
+    readonly OBJECT_REFERENCED: "SCHEMA_OBJECT_REFERENCED";
+    readonly CONFIGURATION_REQUIRED: "CONFIGURATION_REQUIRED";
+    readonly SEARCH_ADAPTER_REQUIRED: "SEARCH_ADAPTER_REQUIRED";
+    readonly SEARCH_BACKEND_FAILED: "SEARCH_BACKEND_FAILED";
+    readonly INVARIANT_VIOLATION: "INVARIANT_VIOLATION";
+    readonly TENANT_CONTEXT_MISSING: "TENANT_CONTEXT_MISSING";
+    readonly FEATURE_FLAGS_CONTEXT: "FEATURE_FLAGS_CONTEXT";
+    readonly AGENT_UNKNOWN: "AGENT_UNKNOWN";
+    readonly AGENT_DEPTH_EXCEEDED: "AGENT_DEPTH_EXCEEDED";
+    readonly AGENT_COST_LIMIT_EXCEEDED: "AGENT_COST_LIMIT_EXCEEDED";
+    readonly AGENT_TREE_COST_LIMIT_EXCEEDED: "AGENT_TREE_COST_LIMIT_EXCEEDED";
+    readonly AGENT_SESSION_NOT_FOUND: "AGENT_SESSION_NOT_FOUND";
+    readonly AGENT_DEFINITION_NOT_FOUND: "AGENT_DEFINITION_NOT_FOUND";
+    readonly AGENT_RUN_CONFIG: "AGENT_RUN_CONFIG";
+    readonly AGENT_STREAMING: "AGENT_STREAMING";
+    readonly AGENT_MISSING_ACTOR: "AGENT_MISSING_ACTOR";
+    readonly AGENT_INVALID_STATE: "AGENT_INVALID_STATE";
+    readonly AGENT_COMPACTION_IMPOSSIBLE: "AGENT_COMPACTION_IMPOSSIBLE";
+    readonly AGENT_COMPACTION_TIMEOUT: "AGENT_COMPACTION_TIMEOUT";
+    readonly AGENT_LEASE_HELD: "AGENT_LEASE_HELD";
+    readonly AGENT_MISSION_CONFLICT: "AGENT_MISSION_CONFLICT";
+    readonly AGENT_MISSION_INCOMPLETE: "AGENT_MISSION_INCOMPLETE";
+    readonly AI_UNKNOWN: "AI_UNKNOWN";
+    readonly AI_USAGE_LIMIT_EXCEEDED: "AI_USAGE_LIMIT_EXCEEDED";
+    readonly AI_INVALID_USAGE: "AI_INVALID_USAGE";
+    readonly AI_INVALID_MODEL: "AI_INVALID_MODEL";
+    readonly AI_REPOSITORY_ERROR: "AI_REPOSITORY_ERROR";
+    readonly AI_GENERATION_FAILED: "AI_GENERATION_FAILED";
+    readonly DOCUMENT_MIME_NOT_ACCEPTED: "DOCUMENT_MIME_NOT_ACCEPTED";
+    readonly DOCUMENT_MULTIPLE_NOT_ALLOWED: "DOCUMENT_MULTIPLE_NOT_ALLOWED";
+    readonly DOCUMENT_NOT_FOUND_FOR_OPERATION: "DOCUMENT_NOT_FOUND_FOR_OPERATION";
+    readonly DOCUMENT_STORAGE_FAILED: "DOCUMENT_STORAGE_FAILED";
+    readonly DOCUMENT_SIZE_EXCEEDED: "DOCUMENT_SIZE_EXCEEDED";
+    readonly DOCUMENT_OCR_FAILED: "DOCUMENT_OCR_FAILED";
+    readonly DOCUMENT_FILE_TOO_LARGE: "DOCUMENT_FILE_TOO_LARGE";
+    readonly DOCUMENT_FILE_NOT_FOUND: "DOCUMENT_FILE_NOT_FOUND";
+    readonly DOCUMENT_RECORD_NOT_FOUND: "DOCUMENT_RECORD_NOT_FOUND";
+    readonly DOCUMENT_RECORD_OBJECT_MISMATCH: "DOCUMENT_RECORD_OBJECT_MISMATCH";
+    readonly DOCUMENT_FOLDER_SERVICE_UNAVAILABLE: "DOCUMENT_FOLDER_SERVICE_UNAVAILABLE";
+    readonly DOCUMENT_FOLDER_PATH_NOT_FOUND: "DOCUMENT_FOLDER_PATH_NOT_FOUND";
+    readonly EMAIL_IMAGE_PROXY_INVALID_TOKEN: "EMAIL_IMAGE_PROXY_INVALID_TOKEN";
+    readonly EMAIL_IMAGE_PROXY_EXPIRED_TOKEN: "EMAIL_IMAGE_PROXY_EXPIRED_TOKEN";
+    readonly EMAIL_IMAGE_PROXY_TOO_LARGE: "EMAIL_IMAGE_PROXY_TOO_LARGE";
+    readonly EMAIL_IMAGE_PROXY_UNSUPPORTED_CONTENT_TYPE: "EMAIL_IMAGE_PROXY_UNSUPPORTED_CONTENT_TYPE";
+    readonly EMAIL_IMAGE_PROXY_UNSAFE_URL: "EMAIL_IMAGE_PROXY_UNSAFE_URL";
+    readonly EMAIL_IMAGE_PROXY_UPSTREAM_FAILED: "EMAIL_IMAGE_PROXY_UPSTREAM_FAILED";
+    readonly EMAIL_PROVIDER_API_FAILED: "EMAIL_PROVIDER_API_FAILED";
+    readonly EMAIL_BATCH_ITEM_FAILED: "EMAIL_BATCH_ITEM_FAILED";
+    readonly REFLEX_INVALID_TRANSITION: "REFLEX_INVALID_TRANSITION";
+    readonly REFLEX_INVALID_TOKEN: "REFLEX_INVALID_TOKEN";
+    readonly REFLEX_CAPABILITY_DENIED: "REFLEX_CAPABILITY_DENIED";
+    readonly REFLEX_GATEWAY_UNAVAILABLE: "REFLEX_GATEWAY_UNAVAILABLE";
+    readonly REFLEX_BUNDLE_FAILED: "REFLEX_BUNDLE_FAILED";
+    readonly REFLEX_EGRESS_DENIED: "REFLEX_EGRESS_DENIED";
+    readonly REFLEX_PROTOCOL_VIOLATION: "REFLEX_PROTOCOL_VIOLATION";
+    readonly REFLEX_RUN_FAILED: "REFLEX_RUN_FAILED";
+    readonly REFLEX_RUN_TIMEOUT: "REFLEX_RUN_TIMEOUT";
+};
+type SchemaErrorCode = (typeof SchemaErrorCode)[keyof typeof SchemaErrorCode];
+/**
+ * Base error class for all schema-related errors
+ */
+declare class SchemaError extends Error {
+    readonly code: SchemaErrorCode;
+    readonly details?: Record<string, unknown>;
+    constructor(message: string, code?: SchemaErrorCode, details?: Record<string, unknown>);
+    toJSON(): {
+        name: string;
+        code: SchemaErrorCode;
+        message: string;
+        details: Record<string, unknown> | undefined;
+    };
+}
+/**
+ * Base class for "not found" errors
+ */
+declare class NotFoundError extends SchemaError {
+    readonly resourceType: string;
+    readonly resourceId: string;
+    constructor(resourceType: string, resourceId: string, code?: SchemaErrorCode, message?: string);
+}
+/**
+ * Object not found error
+ */
+declare class ObjectNotFoundError extends NotFoundError {
+    constructor(objectId: string);
+}
+/**
+ * Attribute not found error
+ */
+declare class AttributeNotFoundError extends NotFoundError {
+    constructor(attributeId: string);
+}
+/**
+ * Record not found error
+ */
+declare class RecordNotFoundError extends NotFoundError {
+    constructor(recordId: string);
+}
+/**
+ * Schema plan not found error — raised when a `planId` sent by an approver
+ * (who never receives the plan payload itself, only its id) does not match
+ * any stored plan.
+ */
+declare class SchemaPlanNotFoundError extends NotFoundError {
+    constructor(planId: string);
+}
+/**
+ * Validation error with field-level details
+ */
+interface ValidationErrorDetail {
+    path: string[];
+    message: string;
+    code?: string;
+}
+/**
+ * Validation error thrown when data fails schema validation
+ */
+declare class ValidationError extends SchemaError {
+    readonly errors: ValidationErrorDetail[];
+    constructor(message: string, errors: ValidationErrorDetail[]);
+    /**
+     * Create a validation error from Zod-style errors
+     */
+    static fromZodErrors(errors: Array<{
+        path: (string | number)[];
+        message: string;
+    }>): ValidationError;
+}
+/**
+ * Error thrown when attempting to modify a protected (system) resource
+ */
+declare class ProtectedResourceError extends SchemaError {
+    readonly resourceType: "object" | "attribute" | "view";
+    readonly resourceName: string;
+    readonly operation: "delete" | "modify";
+    constructor(resourceType: "object" | "attribute" | "view", resourceName: string, operation: "delete" | "modify");
+}
+/**
+ * Error thrown during native object synchronization
+ */
+declare class SyncError extends SchemaError {
+    readonly objectName: string;
+    readonly cause?: Error;
+    constructor(objectName: string, message: string, cause?: Error);
+}
+/**
+ * Thrown when code tries to mutate a system entity at runtime.
+ * System entities are declared in code and immutable at runtime.
+ * HTTP status: 403 Forbidden.
+ */
+declare class SystemEntityImmutableError extends SchemaError {
+    readonly entityType: string;
+    readonly entityName: string;
+    constructor(entityType: string, entityName: string);
+}
+interface SyncConflictParams {
+    objectName: string;
+    attributeName?: string;
+    reason: string;
+}
+/**
+ * Thrown at boot when an auto-promote cannot proceed due to incompatible types
+ * or constraints. The dev must resolve manually (relax constraints, migrate
+ * values, or rename).
+ */
+declare class SyncConflictError extends SchemaError {
+    readonly objectName: string;
+    readonly attributeName?: string;
+    readonly reason: string;
+    constructor(params: SyncConflictParams);
+}
+/**
+ * Thrown at boot when an object is being demoted but still has system attributes
+ * declared in code. The dev forgot to remove those attributes too, or kept the
+ * object inconsistently.
+ */
+declare class SyncCascadeError extends SchemaError {
+    readonly objectName: string;
+    readonly conflictingAttributes: string[];
+    constructor(objectName: string, conflictingAttributes: string[]);
+}
+/**
+ * Thrown at boot when an attribute is system:true but its object parent is
+ * system:false. This invariant should never be violated — if seen, it's a bug
+ * in the boot reconciliation logic or in a manual DB mutation.
+ */
+declare class OrphanSystemAttributeError extends SchemaError {
+    readonly objectName: string;
+    readonly attributeName: string;
+    constructor(objectName: string, attributeName: string);
+}
+/**
+ * Thrown when a destructive operation is detected without the explicit
+ * STANDARDS_ALLOW_DESTRUCTIVE_SYNC=1 opt-in.
+ * HTTP status: 500 (boot fail, should never surface to HTTP).
+ *
+ * Which operations the opt-in governs is decided in one place —
+ * `requiresDestructiveSyncOptIn` in the runtime's sync classifier. Today that
+ * is object removal only: attribute removal is unconditional at boot, because a
+ * system attribute is code-controlled and its disappearance from the builder is
+ * an unambiguous drop.
+ *
+ * NOTE — Wiring status: defined but not thrown by the current sync.ts, which
+ * demotes instead. Reserved for the `standards diff` CLI gate, which will throw
+ * it when CI detects an unauthorized destructive deployment.
+ */
+declare class DestructiveSyncNotAllowedError extends SchemaError {
+    readonly operations: SchemaOperation[];
+    constructor(operations: SchemaOperation[]);
+}
+/**
+ * Thrown at boot when applying a migration in batches exceeds the maximum
+ * allowed duration (default 5 min, configurable via STANDARDS_MIGRATION_MAX_DURATION_MS).
+ * HTTP status: 500 (boot fail).
+ */
+declare class MigrationTimeoutError extends SchemaError {
+    readonly objectName: string;
+    readonly migrated: number;
+    readonly total: number;
+    readonly maxDurationMs: number;
+    constructor(objectName: string, migrated: number, total: number, maxDurationMs: number);
+}
+/**
+ * Thrown when the runtime admin API is called to change an attribute's type.
+ * Type changes must be declared in code via `.migration(N, m => m.changeType(...))`.
+ * HTTP status: 400 Bad Request.
+ */
+declare class ChangeTypeNotSupportedError extends SchemaError {
+    readonly objectName: string;
+    readonly attributeName: string;
+    constructor(objectName: string, attributeName: string);
+}
+/**
+ * Error thrown when attempting to create a duplicate resource.
+ *
+ * `resourceType` is free-form: pass `"object"`/`"attribute"` for schema
+ * resources (a specific code is selected automatically), or any domain label
+ * (`"tool"`, `"background job handler"`, …) for runtime registries, which fall
+ * back to the generic `DUPLICATE` code. The default message is
+ * `'<ResourceType> "<name>" already exists'`; pass a custom message when the
+ * domain reads better with different wording (e.g. "already registered for
+ * type X").
+ */
+declare class DuplicateError extends SchemaError {
+    readonly resourceType: string;
+    readonly resourceName: string;
+    constructor(resourceType: string, resourceName: string, message?: string);
+}
+/**
+ * Check if an error is a SchemaError
+ */
+declare function isSchemaError(error: unknown): error is SchemaError;
+/**
+ * Check if an error is a NotFoundError
+ */
+declare function isNotFoundError(error: unknown): error is NotFoundError;
+/**
+ * Check if an error is a ValidationError
+ */
+declare function isValidationError(error: unknown): error is ValidationError;
+/**
+ * Check if an error is a ProtectedResourceError
+ */
+declare function isProtectedResourceError(error: unknown): error is ProtectedResourceError;
+/**
+ * Error thrown when a user lacks permission to perform an action
+ */
+declare class ForbiddenError extends SchemaError {
+    readonly objectName: string;
+    readonly action: string;
+    readonly userId?: string;
+    constructor(objectName: string, action: string, userId?: string);
+}
+/**
+ * Error thrown when trying to modify a protected role
+ */
+declare class ProtectedRoleError extends SchemaError {
+    readonly roleName: string;
+    readonly operation: "delete" | "modify";
+    constructor(roleName: string, operation: "delete" | "modify");
+}
+/**
+ * Role not found error
+ */
+declare class RoleNotFoundError extends NotFoundError {
+    constructor(roleId: string);
+}
+/**
+ * Thrown when a record has been modified by another request between read and write.
+ * Clients should retry the operation with fresh data.
+ * Maps to HTTP 409 Conflict.
+ */
+declare class ConcurrentModificationError extends SchemaError {
+    constructor(recordId: string);
+}
+/**
+ * Storage operation type for error context
+ */
+type StorageOperation = "upload" | "download" | "delete" | "signedUrl";
+/**
+ * Error thrown when a storage operation fails
+ */
+declare class StorageError extends SchemaError {
+    readonly operation: StorageOperation;
+    readonly path?: string;
+    readonly cause?: string;
+    constructor(operation: StorageOperation, message: string, path?: string, cause?: string);
+}
+/**
+ * Error thrown when access to a resource is denied (e.g., tenant path mismatch)
+ */
+declare class AccessDeniedError extends SchemaError {
+    readonly resource: string;
+    readonly reason?: string;
+    constructor(resource: string, reason?: string);
+}
+/**
+ * Repository operation type for error context
+ */
+type RepositoryOperation = "create" | "update" | "delete" | "query";
+/**
+ * Error thrown when a repository operation fails
+ */
+declare class RepositoryError extends SchemaError {
+    readonly operation: RepositoryOperation;
+    readonly entity: string;
+    readonly cause?: string;
+    constructor(operation: RepositoryOperation, entity: string, message: string, cause?: string);
+}
+/**
+ * Error thrown when a search read call fails at the transport level — e.g. the
+ * Meili client received a non-JSON body (`JSON.parse` SyntaxError) or a network
+ * failure. Translates an otherwise un-fingerprintable bare exception into a
+ * typed error with a stable `code` and a user-safe message. The original
+ * failure text is preserved in `cause`/`details`, never in the message.
+ */
+declare class SearchBackendError extends SchemaError {
+    readonly scope: string;
+    readonly cause?: string;
+    constructor(scope: string, cause?: string);
+}
+/**
+ * Error thrown when a feature or method is not yet implemented
+ */
+declare class NotImplementedError extends SchemaError {
+    readonly feature: string;
+    readonly milestone?: string;
+    constructor(feature: string, milestone?: string);
+}
+/**
+ * Memory entry not found error
+ */
+declare class MemoryNotFoundError extends NotFoundError {
+    constructor(memoryId: string);
+}
+/**
+ * Reference information for a record that is blocking deletion.
+ */
+interface RecordReference {
+    /** Technical name of the object (e.g., "contacts") */
+    objectName: string;
+    /** Display label of the object (e.g., "Contacts") */
+    objectLabel: string;
+    /** Number of records referencing the target */
+    count: number;
+}
+/**
+ * Thrown when attempting to delete a record that is referenced by other records.
+ *
+ * This implements the "Restrict" behavior: deletion is blocked and the user
+ * must first remove or update the referencing records.
+ */
+declare class RecordReferencedError extends SchemaError {
+    readonly recordId: string;
+    readonly references: RecordReference[];
+    constructor(recordId: string, references: RecordReference[]);
+}
+/**
+ * Usage context where an attribute is being used.
+ */
+type AttributeUsage = "labelExpression" | "embeddingExpression" | "view" | "filter";
+/**
+ * Thrown when attempting to delete an attribute that is in use.
+ *
+ * Attributes cannot be deleted if they are referenced in:
+ * - The object's labelExpression template
+ * - A saved view's column configuration
+ * - A saved filter condition
+ */
+declare class AttributeInUseError extends SchemaError {
+    readonly attributeName: string;
+    readonly usage: AttributeUsage;
+    constructor(attributeName: string, usage: AttributeUsage);
+}
+/**
+ * Thrown when attempting to delete an object that is a relation target.
+ *
+ * Objects cannot be deleted if other objects have relation attributes
+ * pointing to them as a target.
+ */
+declare class ObjectReferencedError extends SchemaError {
+    readonly objectName: string;
+    readonly referencingObjects: string[];
+    constructor(objectName: string, referencingObjects: string[]);
+}
+/**
+ * Check if an error is a RecordReferencedError
+ */
+declare function isRecordReferencedError(error: unknown): error is RecordReferencedError;
+/**
+ * Check if an error is an AttributeInUseError
+ */
+declare function isAttributeInUseError(error: unknown): error is AttributeInUseError;
+/**
+ * Check if an error is an ObjectReferencedError
+ */
+declare function isObjectReferencedError(error: unknown): error is ObjectReferencedError;
+
+export { AccessDeniedError, AttributeInUseError, AttributeNotFoundError, type AttributeUsage, ChangeTypeNotSupportedError, ConcurrentModificationError, DestructiveSyncNotAllowedError, DuplicateError, ForbiddenError, MemoryNotFoundError, MigrationTimeoutError, NotFoundError, NotImplementedError, ObjectNotFoundError, ObjectReferencedError, OrphanSystemAttributeError, ProtectedResourceError, ProtectedRoleError, RecordNotFoundError, type RecordReference, RecordReferencedError, RepositoryError, type RepositoryOperation, RoleNotFoundError, SchemaError, SchemaErrorCode, SchemaPlanNotFoundError, SearchBackendError, StorageError, type StorageOperation, SyncCascadeError, SyncConflictError, SyncError, SystemEntityImmutableError, ValidationError, type ValidationErrorDetail, isAttributeInUseError, isNotFoundError, isObjectReferencedError, isProtectedResourceError, isRecordReferencedError, isSchemaError, isValidationError };