@semiont/core 0.2.2-build.11 → 0.2.2

package/dist/index.d.ts

@@ -1,33 +1,1373 @@
+import { components, JobId, AnnotationUri } from '@semiont/api-client';
+import { ErrorObject } from 'ajv';
+
+/**
+ * Resource creation methods - How resources are created in the system
+ */
+/**
+ * Enumeration of all possible resource creation methods
+ */
+declare const CREATION_METHODS: {
+    readonly API: "api";
+    readonly UPLOAD: "upload";
+    readonly UI: "ui";
+    readonly REFERENCE: "reference";
+    readonly CLONE: "clone";
+    readonly GENERATED: "generated";
+};
+/**
+ * Type for resource creation methods
+ */
+type CreationMethod = typeof CREATION_METHODS[keyof typeof CREATION_METHODS];
+
+/**
+ * Branded identifier types for compile-time type safety.
+ *
+ * These types prevent mixing up resource IDs, annotation IDs, and user IDs
+ * at compile time while having zero runtime overhead.
+ *
+ * URI types (ResourceUri, AnnotationUri) are in @semiont/api-client
+ * since they deal with HTTP URIs returned by the API.
+ */
+type ResourceId = string & {
+    readonly __brand: 'ResourceId';
+};
+type AnnotationId = string & {
+    readonly __brand: 'AnnotationId';
+};
+type UserId = string & {
+    readonly __brand: 'UserId';
+};
+declare function isResourceId(value: string): value is ResourceId;
+declare function isAnnotationId(value: string): value is AnnotationId;
+declare function resourceId(id: string): ResourceId;
+declare function annotationId(id: string): AnnotationId;
+declare function userId(id: string): UserId;
+
+/**
+ * Graph types - Models for graph connections and relationships
+ */
+
+type ResourceDescriptor = components['schemas']['ResourceDescriptor'];
+type Annotation$4 = components['schemas']['Annotation'];
+/**
+ * Represents a connection between resources through annotations
+ */
+interface GraphConnection {
+    targetResource: ResourceDescriptor;
+    annotations: Annotation$4[];
+    relationshipType?: string;
+    bidirectional: boolean;
+}
+/**
+ * Represents a path through the graph
+ */
+interface GraphPath {
+    resources: ResourceDescriptor[];
+    annotations: Annotation$4[];
+}
+/**
+ * Statistics about entity types in the graph
+ */
+interface EntityTypeStats {
+    type: string;
+    count: number;
+}
+
+/**
+ * Resource Event Types
+ *
+ * Event-sourced architecture for resource state management
+ * Events are stored in an append-only log (JSONL format)
+ *
+ * Federation-ready design:
+ * - resourceId uses content hashes (doc-sha256:...)
+ * - userId uses DID format (did:web:org.com:users:alice)
+ * - prevEventHash creates tamper-evident chains
+ * - Optional signatures for cross-org verification
+ */
+
+type Annotation$3 = components['schemas']['Annotation'];
+type ContentFormat = components['schemas']['ContentFormat'];
+interface BaseEvent {
+    id: string;
+    timestamp: string;
+    resourceId?: ResourceId;
+    userId: UserId;
+    version: number;
+}
+interface ResourceCreatedEvent extends BaseEvent {
+    type: 'resource.created';
+    payload: {
+        name: string;
+        format: ContentFormat;
+        contentChecksum: string;
+        contentByteSize?: number;
+        creationMethod: CreationMethod;
+        entityTypes?: string[];
+        language?: string;
+        isDraft?: boolean;
+        generatedFrom?: string;
+        generationPrompt?: string;
+    };
+}
+interface ResourceClonedEvent extends BaseEvent {
+    type: 'resource.cloned';
+    payload: {
+        name: string;
+        format: ContentFormat;
+        contentChecksum: string;
+        contentByteSize?: number;
+        parentResourceId: string;
+        creationMethod: CreationMethod;
+        entityTypes?: string[];
+        language?: string;
+    };
+}
+interface ResourceArchivedEvent extends BaseEvent {
+    type: 'resource.archived';
+    payload: {
+        reason?: string;
+    };
+}
+interface ResourceUnarchivedEvent extends BaseEvent {
+    type: 'resource.unarchived';
+    payload: Record<string, never>;
+}
+interface AnnotationAddedEvent extends BaseEvent {
+    type: 'annotation.added';
+    payload: {
+        annotation: Omit<Annotation$3, 'creator' | 'created'>;
+    };
+}
+interface AnnotationRemovedEvent extends BaseEvent {
+    type: 'annotation.removed';
+    payload: {
+        annotationId: AnnotationId;
+    };
+}
+type BodyItem = {
+    type: 'TextualBody';
+    value: string;
+    purpose: 'tagging' | 'commenting' | 'describing' | 'classifying';
+    format?: string;
+    language?: string;
+} | {
+    type: 'SpecificResource';
+    source: string;
+    purpose: 'linking';
+};
+type BodyOperation = {
+    op: 'add';
+    item: BodyItem;
+} | {
+    op: 'remove';
+    item: BodyItem;
+} | {
+    op: 'replace';
+    oldItem: BodyItem;
+    newItem: BodyItem;
+};
+interface AnnotationBodyUpdatedEvent extends BaseEvent {
+    type: 'annotation.body.updated';
+    payload: {
+        annotationId: AnnotationId;
+        operations: BodyOperation[];
+    };
+}
+interface JobStartedEvent extends BaseEvent {
+    type: 'job.started';
+    resourceId: ResourceId;
+    payload: {
+        jobId: JobId;
+        jobType: 'detection' | 'generation' | 'highlight-detection' | 'assessment-detection' | 'comment-detection' | 'tag-detection';
+        totalSteps?: number;
+    };
+}
+interface JobProgressEvent extends BaseEvent {
+    type: 'job.progress';
+    resourceId: ResourceId;
+    payload: {
+        jobId: JobId;
+        jobType: 'detection' | 'generation' | 'highlight-detection' | 'assessment-detection' | 'comment-detection' | 'tag-detection';
+        percentage: number;
+        currentStep?: string;
+        processedSteps?: number;
+        totalSteps?: number;
+        foundCount?: number;
+        message?: string;
+        progress?: any;
+    };
+}
+interface JobCompletedEvent extends BaseEvent {
+    type: 'job.completed';
+    resourceId: ResourceId;
+    payload: {
+        jobId: JobId;
+        jobType: 'detection' | 'generation' | 'highlight-detection' | 'assessment-detection' | 'comment-detection' | 'tag-detection';
+        totalSteps?: number;
+        foundCount?: number;
+        resultResourceId?: ResourceId;
+        annotationUri?: AnnotationUri;
+        message?: string;
+        result?: any;
+    };
+}
+interface JobFailedEvent extends BaseEvent {
+    type: 'job.failed';
+    resourceId: ResourceId;
+    payload: {
+        jobId: JobId;
+        jobType: 'detection' | 'generation' | 'highlight-detection' | 'assessment-detection' | 'comment-detection' | 'tag-detection';
+        error: string;
+        details?: string;
+    };
+}
+interface EntityTagAddedEvent extends BaseEvent {
+    type: 'entitytag.added';
+    resourceId: ResourceId;
+    payload: {
+        entityType: string;
+    };
+}
+interface EntityTagRemovedEvent extends BaseEvent {
+    type: 'entitytag.removed';
+    resourceId: ResourceId;
+    payload: {
+        entityType: string;
+    };
+}
+interface EntityTypeAddedEvent extends BaseEvent {
+    type: 'entitytype.added';
+    resourceId?: undefined;
+    payload: {
+        entityType: string;
+    };
+}
+type ResourceEvent = ResourceCreatedEvent | ResourceClonedEvent | ResourceArchivedEvent | ResourceUnarchivedEvent | AnnotationAddedEvent | AnnotationRemovedEvent | AnnotationBodyUpdatedEvent | JobStartedEvent | JobProgressEvent | JobCompletedEvent | JobFailedEvent | EntityTagAddedEvent | EntityTagRemovedEvent | EntityTypeAddedEvent;
+type ResourceEventType = ResourceEvent['type'];
+type SystemEvent = EntityTypeAddedEvent;
+type ResourceScopedEvent = Exclude<ResourceEvent, SystemEvent>;
+declare function isResourceEvent(event: any): event is ResourceEvent;
+/**
+ * Type guard: Check if event is system-level (no resourceId)
+ * System events affect global state, not individual resources
+ */
+declare function isSystemEvent(event: ResourceEvent): event is SystemEvent;
+/**
+ * Type guard: Check if event is resource-scoped (has resourceId)
+ * Resource events affect a specific resource's state
+ */
+declare function isResourceScopedEvent(event: ResourceEvent): event is ResourceScopedEvent;
+declare function getEventType<T extends ResourceEvent>(event: ResourceEvent): T['type'];
+interface EventMetadata {
+    sequenceNumber: number;
+    streamPosition: number;
+    timestamp: string;
+    prevEventHash?: string;
+    checksum?: string;
+}
+interface EventSignature {
+    algorithm: 'ed25519';
+    publicKey: string;
+    signature: string;
+    keyId?: string;
+}
+interface StoredEvent<T extends ResourceEvent = ResourceEvent> {
+    event: T;
+    metadata: EventMetadata;
+    signature?: EventSignature;
+}
+interface EventQuery {
+    resourceId?: ResourceId;
+    userId?: string;
+    eventTypes?: ResourceEvent['type'][];
+    fromTimestamp?: string;
+    toTimestamp?: string;
+    fromSequence?: number;
+    limit?: number;
+}
+interface ResourceAnnotations {
+    resourceId: ResourceId;
+    annotations: Annotation$3[];
+    version: number;
+    updatedAt: string;
+}
+
+/**
+ * Backend-specific annotation utility functions
+ */
+
+type Annotation$2 = components['schemas']['Annotation'];
+/**
+ * Check if two body items match (for remove/replace operations)
+ * Matches by type, value/source, and purpose fields
+ */
+declare function bodyItemsMatch(item1: BodyItem, item2: BodyItem): boolean;
+/**
+ * Find a body item in an array
+ * Returns the index of the first matching item, or -1 if not found
+ */
+declare function findBodyItem(body: Annotation$2['body'], targetItem: BodyItem): number;
+
+/**
+ * Resource input/output types
+ */
+interface UpdateResourceInput {
+    name?: string;
+    entityTypes?: string[];
+    archived?: boolean;
+}
+interface ResourceFilter {
+    entityTypes?: string[];
+    search?: string;
+    limit?: number;
+    offset?: number;
+}
+
+/**
+ * Annotation types
+ */
+
+type Annotation$1 = components['schemas']['Annotation'];
+type AnnotationCategory = 'highlight' | 'reference';
+interface CreateAnnotationInternal {
+    id: string;
+    motivation: Annotation$1['motivation'];
+    target: Annotation$1['target'];
+    body: Annotation$1['body'];
+    creator: components['schemas']['Agent'];
+}
+
+/**
+ * Auth types
+ */
+interface GoogleAuthRequest {
+    credential: string;
+    termsAccepted: boolean;
+}
+
+/**
+ * Common type guard utilities
+ */
+/**
+ * Check if value is a string
+ */
+declare function isString(value: unknown): value is string;
+/**
+ * Check if value is a number (not NaN)
+ */
+declare function isNumber(value: unknown): value is number;
+/**
+ * Check if value is an object (not null, not array)
+ */
+declare function isObject(value: unknown): value is Record<string, unknown>;
+/**
+ * Check if value is an array
+ */
+declare function isArray(value: unknown): value is unknown[];
+/**
+ * Check if value is a boolean
+ */
+declare function isBoolean(value: unknown): value is boolean;
+/**
+ * Check if value is a function
+ */
+declare function isFunction(value: unknown): value is Function;
+/**
+ * Check if value is null
+ */
+declare function isNull(value: unknown): value is null;
+/**
+ * Check if value is undefined
+ */
+declare function isUndefined(value: unknown): value is undefined;
+/**
+ * Check if value is null or undefined
+ */
+declare function isNullish(value: unknown): value is null | undefined;
+/**
+ * Check if value is defined (not null or undefined)
+ */
+declare function isDefined<T>(value: T | null | undefined): value is T;
+
+/**
+ * Cryptographic utilities
+ */
+/**
+ * Calculate SHA-256 checksum of content
+ * @param content The content to hash
+ * @returns Hex-encoded SHA-256 hash
+ */
+declare function calculateChecksum(content: string | Buffer): string;
+/**
+ * Verify content against a checksum
+ * @param content The content to verify
+ * @param checksum The expected checksum
+ * @returns True if content matches checksum
+ */
+declare function verifyChecksum(content: string | Buffer, checksum: string): boolean;
+/**
+ * Generate a random ID (12 character hex string)
+ * Similar to MongoDB ObjectId but simpler
+ */
+declare function generateId(): string;
+/**
+ * Generate a UUID v4-like ID (without dashes)
+ */
+declare function generateUuid(): string;
+/**
+ * Generate a secure random token
+ * @param bytes Number of random bytes (default 32)
+ * @returns Base64 encoded random token
+ */
+declare function generateToken(bytes?: number): string;
+
+/**
+ * Common error classes
+ */
+/**
+ * Base error class for Semiont applications
+ */
+declare class SemiontError extends Error {
+    code: string;
+    details?: Record<string, any> | undefined;
+    constructor(message: string, code: string, details?: Record<string, any> | undefined);
+}
+/**
+ * Error thrown when validation fails
+ */
+declare class ValidationError extends SemiontError {
+    constructor(message: string, details?: Record<string, any>);
+}
+/**
+ * Error thrown by scripts
+ */
+declare class ScriptError extends SemiontError {
+    constructor(message: string, code?: string, details?: Record<string, any>);
+}
+/**
+ * Error thrown when a resource is not found
+ */
+declare class NotFoundError extends SemiontError {
+    constructor(resource: string, id?: string);
+}
+/**
+ * Error thrown when user is not authorized
+ */
+declare class UnauthorizedError extends SemiontError {
+    constructor(message?: string, details?: Record<string, any>);
+}
+/**
+ * Error thrown when operation would conflict with existing data
+ */
+declare class ConflictError extends SemiontError {
+    constructor(message: string, details?: Record<string, any>);
+}
+/**
+ * API Error class for handling HTTP errors
+ * Used by API clients to represent failed HTTP requests
+ */
+declare class APIError extends Error {
+    status: number;
+    data: any;
+    constructor(status: number, data: any, message?: string);
+}
+
+/**
+ * HTTP Client Utilities
+ *
+ * Reusable fetch wrapper for making authenticated HTTP requests.
+ * Used by both frontend (via TanStack Query) and backend (direct calls).
+ */
+/**
+ * Configuration for HTTP client
+ */
+interface HttpClientConfig {
+    baseUrl: string;
+    token?: string;
+}
+/**
+ * Fetch helper with authentication and error handling
+ *
+ * @param endpoint - API endpoint (e.g., '/api/resources')
+ * @param options - Standard fetch options
+ * @param token - Optional authentication token
+ * @returns Typed response data
+ * @throws APIError on HTTP errors
+ */
+declare function fetchAPI<T>(endpoint: string, options?: RequestInit, token?: string, baseUrl?: string): Promise<T>;
+/**
+ * Create a configured fetch function with a base URL
+ * Useful for creating client-specific fetch instances
+ *
+ * @param baseUrl - Base URL for all requests (e.g., 'http://localhost:4000')
+ * @returns Configured fetch function
+ */
+declare function createFetchAPI(baseUrl: string): <T>(endpoint: string, options?: RequestInit, token?: string) => Promise<T>;
+
+/**
+ * Utility functions for AnnotationHistory component
+ * Extracted to reduce component complexity and improve testability
+ *
+ * NOTE: This file contains UI-specific logic and should eventually move to the frontend package.
+ * It has been updated to work with unified annotation events (annotation.added/removed/body.updated)
+ * instead of separate highlight/reference/assessment events.
+ */
+
+type Annotation = components['schemas']['Annotation'];
+type TranslateFn = (key: string, params?: Record<string, string | number>) => string;
+declare function formatEventType(type: ResourceEventType, t: TranslateFn): string;
+declare function getEventEmoji(type: ResourceEventType, event?: StoredEvent): string;
+declare function formatRelativeTime(timestamp: string, t: TranslateFn): string;
+declare function getEventDisplayContent(event: StoredEvent, _references: Annotation[], // underscore prefix to indicate intentionally unused for now
+_highlights: Annotation[], // underscore prefix to indicate intentionally unused for now
+allEvents: StoredEvent[]): {
+    exact: string;
+    isQuoted: boolean;
+    isTag: boolean;
+} | null;
+declare function getEventEntityTypes(event: StoredEvent): string[];
+type ResourceCreatedDetails = {
+    type: 'created';
+    userId: string;
+    method: CreationMethod;
+};
+type ResourceClonedDetails = {
+    type: 'cloned';
+    userId: string;
+    method: CreationMethod;
+    sourceDocId: string;
+};
+type ResourceCreationDetails = ResourceCreatedDetails | ResourceClonedDetails;
+declare function getResourceCreationDetails(event: StoredEvent): ResourceCreationDetails | null;
+declare function getAnnotationIdFromEvent(event: StoredEvent): string | null;
+declare function isEventRelatedToAnnotation(event: StoredEvent, annotationId: AnnotationId): boolean;
+
+/**
+ * DID (Decentralized Identifier) and W3C Agent utilities
+ *
+ * Provides utilities for working with DID:WEB identifiers and converting
+ * between user representations and W3C Web Annotation Agent objects.
+ */
+
+type Agent = components['schemas']['Agent'];
+/**
+ * Convert a user object to a DID:WEB identifier
+ *
+ * Format: did:web:domain.com:users:userId
+ * Example: did:web:example.com:users:abc123
+ *
+ * This is used for W3C Web Annotation compliance and federation readiness.
+ *
+ * @param user - User object with id and domain
+ * @returns DID:WEB identifier string
+ */
+declare function userToDid(user: {
+    id: string;
+    domain: string;
+}): string;
+/**
+ * Convert a user object to a W3C Agent object with DID:WEB identifier
+ *
+ * Creates a full Agent object for W3C Web Annotation compliance.
+ * Includes DID:WEB identifier, type, and name.
+ *
+ * @param user - User object with id, domain, name, and email
+ * @returns W3C Agent object
+ */
+declare function userToAgent(user: {
+    id: string;
+    domain: string;
+    name: string | null;
+    email: string;
+}): Agent;
+/**
+ * Convert a DID string to a minimal W3C Agent object
+ *
+ * Used when reconstructing annotations from events where only the DID is available.
+ * Creates a minimal Agent with just the required fields (id, type).
+ * Name is derived from the DID for display purposes.
+ *
+ * @param did - DID:WEB identifier string
+ * @returns Minimal W3C Agent object
+ */
+declare function didToAgent(did: string): Agent;
+
+/**
+ * This interface was referenced by `HttpsSemiontOrgSchemasConfigJson`'s JSON-Schema
+ * via the `definition` "PlatformType".
+ */
+type PlatformType$1 = 'posix' | 'container' | 'aws' | 'external';
+/**
+ * This interface was referenced by `HttpsSemiontOrgSchemasConfigJson`'s JSON-Schema
+ * via the `definition` "GraphDatabaseType".
+ */
+type GraphDatabaseType = 'neo4j' | 'janusgraph' | 'neptune' | 'memory';
+/**
+ * This interface was referenced by `HttpsSemiontOrgSchemasConfigJson`'s JSON-Schema
+ * via the `definition` "ServicePlatformConfig".
+ */
+interface ServicePlatformConfig {
+    type: PlatformType$1;
+    [k: string]: unknown;
+}
+/**
+ * This interface was referenced by `HttpsSemiontOrgSchemasConfigJson`'s JSON-Schema
+ * via the `definition` "ResourceRequirements".
+ */
+interface ResourceRequirements {
+    cpu?: string;
+    memory?: string;
+    gpu?: number;
+    gpus?: number;
+    replicas?: number;
+    ephemeralStorage?: string;
+    memoryReservation?: string;
+}
+/**
+ * This interface was referenced by `HttpsSemiontOrgSchemasConfigJson`'s JSON-Schema
+ * via the `definition` "SecurityRequirements".
+ */
+interface SecurityRequirements {
+    readOnlyRootFilesystem?: boolean;
+    runAsNonRoot?: boolean;
+    runAsUser?: number;
+    runAsGroup?: number;
+    capabilities?: string[] | {
+        add?: string[];
+        drop?: string[];
+        [k: string]: unknown;
+    };
+    privileged?: boolean;
+    allowPrivilegeEscalation?: boolean;
+}
+/**
+ * This interface was referenced by `HttpsSemiontOrgSchemasConfigJson`'s JSON-Schema
+ * via the `definition` "BuildRequirements".
+ */
+interface BuildRequirements {
+    dockerfile?: string;
+    buildContext?: string;
+    buildArgs?: {
+        [k: string]: string;
+    };
+    buildTarget?: string;
+    prebuilt?: boolean;
+    noCache?: boolean;
+}
+/**
+ * This interface was referenced by `HttpsSemiontOrgSchemasConfigJson`'s JSON-Schema
+ * via the `definition` "BackendServiceConfig".
+ */
+interface BackendServiceConfig {
+    platform: ServicePlatformConfig;
+    devMode?: boolean;
+    command?: string;
+    port: number;
+    publicURL: string;
+    corsOrigin: string;
+    image?: string;
+    cpu?: string;
+    memory?: string;
+    semiontRepo?: string;
+    databaseUrl?: string;
+    projectRoot?: string;
+    timeout?: number;
+    wait?: number;
+    logsEndpoint?: string;
+    tag?: string;
+    resources?: ResourceRequirements;
+    security?: SecurityRequirements;
+    build?: boolean | BuildRequirements;
+    dockerfile?: string;
+    buildContext?: string;
+    buildArgs?: {
+        [k: string]: string;
+    };
+    buildTarget?: string;
+    prebuilt?: boolean;
+    noCache?: boolean;
+    secrets?: string[];
+    labels?: {
+        [k: string]: string;
+    };
+    annotations?: {
+        [k: string]: string;
+    };
+    dependencies?: string[];
+    externalDependencies?: (string | {
+        name?: string;
+        url?: string;
+        required?: boolean;
+        healthCheck?: string;
+        [k: string]: unknown;
+    })[];
+    redisUrl?: string;
+    environment?: {
+        [k: string]: string;
+    };
+    env?: {
+        [k: string]: string;
+    };
+}
+/**
+ * This interface was referenced by `HttpsSemiontOrgSchemasConfigJson`'s JSON-Schema
+ * via the `definition` "FrontendServiceConfig".
+ */
+interface FrontendServiceConfig {
+    platform: ServicePlatformConfig;
+    devMode?: boolean;
+    command?: string;
+    port: number;
+    url: string;
+    siteName: string;
+    image?: string;
+    semiontRepo?: string;
+    projectRoot?: string;
+    databaseUrl?: string;
+    timeout?: number;
+    wait?: number;
+    logsEndpoint?: string;
+    tag?: string;
+    resources?: ResourceRequirements;
+    security?: SecurityRequirements;
+    build?: boolean | BuildRequirements;
+    dockerfile?: string;
+    buildContext?: string;
+    buildArgs?: {
+        [k: string]: string;
+    };
+    buildTarget?: string;
+    prebuilt?: boolean;
+    noCache?: boolean;
+    secrets?: string[];
+    labels?: {
+        [k: string]: string;
+    };
+    annotations?: {
+        [k: string]: string;
+    };
+    dependencies?: string[];
+    externalDependencies?: (string | {
+        name?: string;
+        url?: string;
+        required?: boolean;
+        healthCheck?: string;
+        [k: string]: unknown;
+    })[];
+    environment?: {
+        [k: string]: string;
+    };
+    env?: {
+        [k: string]: string;
+    };
+}
+/**
+ * This interface was referenced by `HttpsSemiontOrgSchemasConfigJson`'s JSON-Schema
+ * via the `definition` "DatabaseServiceConfig".
+ */
+interface DatabaseServiceConfig {
+    platform: ServicePlatformConfig;
+    type: string;
+    name?: string;
+    host: string;
+    port: number;
+    environment?: {
+        [k: string]: string;
+    };
+    env?: {
+        [k: string]: string;
+    };
+    description?: string;
+    command?: string;
+    image?: string;
+    user?: string;
+    username?: string;
+    password?: string;
+    database?: string;
+    storageSize?: string;
+    timeout?: number;
+    wait?: number;
+    logsEndpoint?: string;
+    tag?: string;
+    resources?: ResourceRequirements;
+    security?: SecurityRequirements;
+    build?: boolean | BuildRequirements;
+    dockerfile?: string;
+    buildContext?: string;
+    buildArgs?: {
+        [k: string]: string;
+    };
+    buildTarget?: string;
+    prebuilt?: boolean;
+    noCache?: boolean;
+    secrets?: string[];
+    labels?: {
+        [k: string]: string;
+    };
+    annotations?: {
+        [k: string]: string;
+    };
+    dependencies?: string[];
+    externalDependencies?: (string | {
+        name?: string;
+        url?: string;
+        required?: boolean;
+        healthCheck?: string;
+        [k: string]: unknown;
+    })[];
+}
+/**
+ * This interface was referenced by `HttpsSemiontOrgSchemasConfigJson`'s JSON-Schema
+ * via the `definition` "GraphServiceConfig".
+ */
+interface GraphServiceConfig {
+    platform: ServicePlatformConfig;
+    type: GraphDatabaseType;
+    name?: string;
+    uri: string;
+    url?: string;
+    username: string;
+    password: string;
+    database: string;
+    host?: string;
+    port?: number;
+    storage?: string;
+    index?: string;
+    endpoint?: string;
+    region?: string;
+    command?: string;
+    image?: string;
+    janusgraphVersion?: string;
+    javaOptions?: string;
+    heapSize?: string;
+    pageCacheSize?: string;
+    noAuth?: boolean;
+    dataPath?: string;
+    timeout?: number;
+    wait?: number;
+    logsEndpoint?: string;
+    tag?: string;
+    resources?: ResourceRequirements;
+    security?: SecurityRequirements;
+    build?: boolean | BuildRequirements;
+    dockerfile?: string;
+    buildContext?: string;
+    buildArgs?: {
+        [k: string]: string;
+    };
+    buildTarget?: string;
+    prebuilt?: boolean;
+    noCache?: boolean;
+    secrets?: string[];
+    labels?: {
+        [k: string]: string;
+    };
+    annotations?: {
+        [k: string]: string;
+    };
+    dependencies?: string[];
+    externalDependencies?: (string | {
+        name?: string;
+        url?: string;
+        required?: boolean;
+        healthCheck?: string;
+        [k: string]: unknown;
+    })[];
+    environment?: {
+        [k: string]: string;
+    };
+    env?: {
+        [k: string]: string;
+    };
+}
+/**
+ * This interface was referenced by `HttpsSemiontOrgSchemasConfigJson`'s JSON-Schema
+ * via the `definition` "FilesystemServiceConfig".
+ */
+interface FilesystemServiceConfig {
+    platform: ServicePlatformConfig;
+    path: string;
+    description?: string;
+    command?: string;
+    image?: string;
+    port?: number;
+    timeout?: number;
+    wait?: number;
+    logsEndpoint?: string;
+    tag?: string;
+    resources?: ResourceRequirements;
+    security?: SecurityRequirements;
+    build?: boolean | BuildRequirements;
+    dockerfile?: string;
+    buildContext?: string;
+    buildArgs?: {
+        [k: string]: string;
+    };
+    buildTarget?: string;
+    prebuilt?: boolean;
+    noCache?: boolean;
+    secrets?: string[];
+    labels?: {
+        [k: string]: string;
+    };
+    annotations?: {
+        [k: string]: string;
+    };
+    dependencies?: string[];
+    externalDependencies?: (string | {
+        name?: string;
+        url?: string;
+        required?: boolean;
+        healthCheck?: string;
+        [k: string]: unknown;
+    })[];
+    environment?: {
+        [k: string]: string;
+    };
+    env?: {
+        [k: string]: string;
+    };
+}
+/**
+ * This interface was referenced by `HttpsSemiontOrgSchemasConfigJson`'s JSON-Schema
+ * via the `definition` "InferenceServiceConfig".
+ */
+interface InferenceServiceConfig {
+    platform: ServicePlatformConfig;
+    type: string;
+    model?: string;
+    maxTokens?: number;
+    endpoint?: string;
+    baseURL?: string;
+    apiKey: string;
+    command?: string;
+    image?: string;
+    port?: number;
+    organization?: string;
+    timeout?: number;
+    wait?: number;
+    logsEndpoint?: string;
+    tag?: string;
+    resources?: ResourceRequirements;
+    security?: SecurityRequirements;
+    build?: boolean | BuildRequirements;
+    dockerfile?: string;
+    buildContext?: string;
+    buildArgs?: {
+        [k: string]: string;
+    };
+    buildTarget?: string;
+    prebuilt?: boolean;
+    noCache?: boolean;
+    secrets?: string[];
+    labels?: {
+        [k: string]: string;
+    };
+    annotations?: {
+        [k: string]: string;
+    };
+    dependencies?: string[];
+    externalDependencies?: (string | {
+        name?: string;
+        url?: string;
+        required?: boolean;
+        healthCheck?: string;
+        [k: string]: unknown;
+    })[];
+    environment?: {
+        [k: string]: string;
+    };
+    env?: {
+        [k: string]: string;
+    };
+}
+/**
+ * This interface was referenced by `HttpsSemiontOrgSchemasConfigJson`'s JSON-Schema
+ * via the `definition` "McpServiceConfig".
+ */
+interface McpServiceConfig {
+    platform: ServicePlatformConfig;
+    command?: string;
+    image?: string;
+    port?: number;
+    dependsOn?: string[];
+    timeout?: number;
+    wait?: number;
+    logsEndpoint?: string;
+    tag?: string;
+    resources?: ResourceRequirements;
+    security?: SecurityRequirements;
+    build?: boolean | BuildRequirements;
+    dockerfile?: string;
+    buildContext?: string;
+    buildArgs?: {
+        [k: string]: string;
+    };
+    buildTarget?: string;
+    prebuilt?: boolean;
+    noCache?: boolean;
+    secrets?: string[];
+    labels?: {
+        [k: string]: string;
+    };
+    annotations?: {
+        [k: string]: string;
+    };
+    dependencies?: string[];
+    externalDependencies?: (string | {
+        name?: string;
+        url?: string;
+        required?: boolean;
+        healthCheck?: string;
+        [k: string]: unknown;
+    })[];
+    environment?: {
+        [k: string]: string;
+    };
+    env?: {
+        [k: string]: string;
+    };
+}
+/**
+ * This interface was referenced by `HttpsSemiontOrgSchemasConfigJson`'s JSON-Schema
+ * via the `definition` "ServicesConfig".
+ */
+interface ServicesConfig {
+    backend?: BackendServiceConfig;
+    frontend?: FrontendServiceConfig;
+    database?: DatabaseServiceConfig;
+    graph?: GraphServiceConfig;
+    filesystem?: FilesystemServiceConfig;
+    inference?: InferenceServiceConfig;
+    mcp?: McpServiceConfig;
+    [k: string]: unknown;
+}
+/**
+ * This interface was referenced by `HttpsSemiontOrgSchemasConfigJson`'s JSON-Schema
+ * via the `definition` "SiteConfig".
+ */
+interface SiteConfig {
+    /**
+     * Display name for the site
+     */
+    siteName?: string;
+    /**
+     * Primary domain for the site
+     */
+    domain: string;
+    /**
+     * Administrator email address
+     */
+    adminEmail?: string;
+    /**
+     * Support email address (optional)
+     */
+    supportEmail?: string;
+    /**
+     * Email domains allowed for OAuth authentication
+     *
+     * @minItems 1
+     */
+    oauthAllowedDomains?: [string, ...string[]];
+}
+/**
+ * This interface was referenced by `HttpsSemiontOrgSchemasConfigJson`'s JSON-Schema
+ * via the `definition` "AppConfig".
+ */
+interface AppConfig {
+    features?: {
+        enableAnalytics?: boolean;
+        enableMaintenanceMode?: boolean;
+        enableDebugLogging?: boolean;
+    };
+    security?: {
+        /**
+         * Session timeout in seconds
+         */
+        sessionTimeout?: number;
+        /**
+         * Maximum failed login attempts before lockout
+         */
+        maxLoginAttempts?: number;
+        corsAllowedOrigins?: string[];
+        /**
+         * Enable local username/password authentication
+         */
+        enableLocalAuth?: boolean;
+        /**
+         * JWT signing secret (base64 encoded, 32+ bytes)
+         */
+        jwtSecret?: string;
+    };
+    performance?: {
+        enableCaching?: boolean;
+        /**
+         * Cache timeout in seconds
+         */
+        cacheTimeout?: number;
+        /**
+         * Maximum request size (e.g., '10mb')
+         */
+        maxRequestSize?: string;
+    };
+}
+/**
+ * This interface was referenced by `HttpsSemiontOrgSchemasConfigJson`'s JSON-Schema
+ * via the `definition` "EnvironmentConfig".
+ */
+interface EnvironmentConfig {
+    /**
+     * Optional comment for documentation
+     */
+    _comment?: string;
+    _metadata?: {
+        environment: string;
+        projectRoot: string;
+        [k: string]: unknown;
+    };
+    /**
+     * Environment name
+     */
+    name?: string;
+    platform?: {
+        default?: PlatformType$1;
+        [k: string]: unknown;
+    };
+    services: ServicesConfig;
+    site?: SiteConfig;
+    app?: AppConfig;
+    env?: {
+        NODE_ENV?: 'development' | 'production' | 'test';
+        [k: string]: unknown;
+    };
+    deployment?: {
+        imageTagStrategy?: 'mutable' | 'immutable' | 'git-hash';
+        [k: string]: unknown;
+    };
+}
+/**
+ * This interface was referenced by `HttpsSemiontOrgSchemasConfigJson`'s JSON-Schema
+ * via the `definition` "SemiontConfig".
+ */
+interface SemiontConfig {
+    /**
+     * Config file version (semver)
+     */
+    version: string;
+    /**
+     * Project name
+     */
+    project: string;
+    site: SiteConfig;
+    app?: AppConfig;
+    services?: ServicesConfig;
+}
+
+/**
+ * Platform Types Module
+ *
+ * Re-exports PlatformType from schema-generated types.
+ * Platforms represent WHERE services run (infrastructure targets).
+ */
+
+/**
+ * Platform type literals from JSON Schema
+ * These represent the infrastructure targets where services can be deployed
+ */
+type PlatformType = PlatformType$1;
+/**
+ * Type guard to check if a string is a valid platform type
+ *
+ * @param value - Value to check
+ * @returns True if value is a valid PlatformType
+ */
+declare function isValidPlatformType(value: string): value is PlatformType;
+/**
+ * Get all valid platform types
+ *
+ * @returns Array of all platform types
+ */
+declare function getAllPlatformTypes(): PlatformType[];
+
+/**
+ * Environment Loader Module
+ *
+ * Responsible for loading and merging environment configurations.
+ * Handles semiont.json base config and environment-specific overrides.
+ */
+
+/**
+ * Generic service configuration
+ * Platform-specific fields should be accessed through platform-specific interfaces
+ */
+interface ServiceConfig {
+    platform?: {
+        type: PlatformType;
+    };
+    port?: number;
+    name?: string;
+    [key: string]: any;
+}
+interface AWSConfig {
+    region: string;
+    accountId: string;
+    certificateArn?: string;
+    hostedZoneId?: string;
+    rootDomain?: string;
+    stacks?: {
+        data?: string;
+        app?: string;
+    };
+    database?: {
+        name?: string;
+        instanceClass?: string;
+        allocatedStorage?: number;
+        backupRetentionDays?: number;
+        multiAZ?: boolean;
+    };
+    ecs?: {
+        desiredCount?: number;
+        minCapacity?: number;
+        maxCapacity?: number;
+    };
+    monitoring?: {
+        enableDetailedMonitoring?: boolean;
+        logRetentionDays?: number;
+    };
+}
+/**
+ * Load environment configuration
+ * Merges semiont.json with environment-specific config
+ *
+ * @param projectRoot - Absolute path to project directory containing semiont.json
+ * @param environment - Environment name (must match a file in environments/)
+ * @returns Merged environment configuration
+ * @throws ConfigurationError if files are missing or invalid
+ */
+declare function loadEnvironmentConfig(projectRoot: string, environment: string): EnvironmentConfig;
+/**
+ * Get NODE_ENV value from environment config
+ *
+ * @param config - Environment configuration
+ * @returns NODE_ENV value (defaults to 'development' if not specified)
+ */
+declare function getNodeEnvForEnvironment(config: EnvironmentConfig): 'development' | 'production' | 'test';
+/**
+ * Get available environments by scanning environments directory
+ *
+ * @returns Array of environment names
+ */
+declare function getAvailableEnvironments(): string[];
+
+/**
+ * Environment validation utilities
+ */
+type Environment = string;
+/**
+ * Type guard to check if a string is a valid Environment
+ */
+declare function isValidEnvironment(value: string | undefined): value is Environment;
+/**
+ * Parse environment string to Environment type
+ * @param value - The environment string to parse
+ * @returns Valid Environment type
+ * @throws Error if environment is invalid or not provided
+ */
+declare function parseEnvironment(value: string | undefined): Environment;
+/**
+ * Validate and return environment or throw error
+ * @param value - The environment string to validate
+ * @throws Error if environment is invalid
+ */
+declare function validateEnvironment(value: string | undefined): Environment;
+
+/**
+ * Configuration Error Class
+ *
+ * Custom error class for configuration validation and loading errors.
+ * Provides structured error information with helpful suggestions.
+ */
+declare class ConfigurationError extends Error {
+    environment?: string | undefined;
+    suggestion?: string | undefined;
+    readonly cause?: Error;
+    constructor(message: string, environment?: string | undefined, suggestion?: string | undefined, cause?: Error);
+    /**
+     * Format the error nicely for CLI output
+     */
+    toString(): string;
+}
+
+/**
+ * Project Discovery Module
+ *
+ * Responsible for finding the Semiont project root directory.
+ * Looks for semiont.json or environments directory to identify a valid project.
+ */
+/**
+ * Find project root - returns SEMIONT_ROOT environment variable
+ *
+ * @returns The absolute path to the project root
+ * @throws ConfigurationError if SEMIONT_ROOT is not set or invalid
+ */
+declare function findProjectRoot(): string;
+/**
+ * Check if a path looks like a Semiont project root
+ *
+ * @param projectPath - Path to check
+ * @returns True if path contains semiont.json or environments directory
+ */
+declare function isProjectRoot(projectPath: string): boolean;
+/**
+ * Get the path to the environments directory
+ *
+ * @param projectRoot - Project root directory (optional, will find if not provided)
+ * @returns Path to environments directory
+ */
+declare function getEnvironmentsPath(projectRoot?: string): string;
+/**
+ * Get the path to semiont.json
+ *
+ * @param projectRoot - Project root directory (optional, will find if not provided)
+ * @returns Path to semiont.json
+ */
+declare function getSemiontConfigPath(projectRoot?: string): string;
+
+/**
+ * Config Schema Validator
+ *
+ * Validates configuration data against JSON Schema using Ajv (JSON Schema validator).
+ * Provides runtime validation for semiont.json and environment config files.
+ */
+
+interface ValidationResult {
+    valid: boolean;
+    errors: ErrorObject[] | null;
+    errorMessage?: string;
+}
+/**
+ * Validate semiont.json config
+ */
+declare function validateSemiontConfig(data: unknown): ValidationResult;
+/**
+ * Validate environment config (environments/*.json)
+ */
+declare function validateEnvironmentConfig(data: unknown): ValidationResult;
+/**
+ * Validate site config
+ */
+declare function validateSiteConfig(data: unknown): ValidationResult;
+
 /**
  * @semiont/core
  *
  * Core domain logic and utilities for the Semiont semantic knowledge platform.
  * For OpenAPI types, import directly from @semiont/api-client.
  */
-export { CREATION_METHODS } from './creation-methods';
-export type { CreationMethod } from './creation-methods';
-export type { ResourceId, AnnotationId, UserId } from './identifiers';
-export { resourceId, annotationId, userId, isResourceId, isAnnotationId, } from './identifiers';
-export type { GraphConnection, GraphPath, EntityTypeStats, } from './graph';
-export type { BaseEvent, ResourceEvent, ResourceEventType, SystemEvent, ResourceScopedEvent, ResourceCreatedEvent, ResourceClonedEvent, ResourceArchivedEvent, ResourceUnarchivedEvent, AnnotationAddedEvent, AnnotationRemovedEvent, AnnotationBodyUpdatedEvent, JobStartedEvent, JobProgressEvent, JobCompletedEvent, JobFailedEvent, BodyOperation, BodyItem, EntityTagAddedEvent, EntityTagRemovedEvent, EventMetadata, EventSignature, StoredEvent, EventQuery, ResourceAnnotations, } from './events';
-export { isResourceEvent, isSystemEvent, isResourceScopedEvent, getEventType, } from './events';
-export { bodyItemsMatch, findBodyItem } from './annotation-utils';
-export type { UpdateResourceInput, ResourceFilter } from './resource-types';
-export type { AnnotationCategory, CreateAnnotationInternal } from './annotation-types';
-export type { GoogleAuthRequest } from './auth-types';
-export * from './type-guards';
-export * from './crypto';
-export * from './errors';
-export * from './http-client';
-export * from './annotation-history-utils';
-export * from './did-utils';
-export { loadEnvironmentConfig, getAvailableEnvironments, getNodeEnvForEnvironment, type EnvironmentConfig, type ServiceConfig, type AWSConfig, type SiteConfig, type AppConfig, } from './config/environment-loader';
-export { isValidEnvironment, parseEnvironment, validateEnvironment, type Environment, } from './config/environment-validator';
-export { ConfigurationError } from './config/configuration-error';
-export { findProjectRoot, isProjectRoot, getEnvironmentsPath, getSemiontConfigPath, } from './config/project-discovery';
-export { type PlatformType, isValidPlatformType, getAllPlatformTypes, } from './config/platform-types';
-export type { BackendServiceConfig, FrontendServiceConfig, DatabaseServiceConfig, GraphServiceConfig, FilesystemServiceConfig, InferenceServiceConfig, McpServiceConfig, ServicesConfig, SemiontConfig, GraphDatabaseType, ServicePlatformConfig } from './config/config.types';
-export { validateSemiontConfig, validateEnvironmentConfig, validateSiteConfig, type ValidationResult, } from './config/config-validator';
-export declare const CORE_TYPES_VERSION = "0.1.0";
-export declare const SDK_VERSION = "0.1.0";
-//# sourceMappingURL=index.d.ts.map
+
+declare const CORE_TYPES_VERSION = "0.1.0";
+declare const SDK_VERSION = "0.1.0";
+
+export { APIError, type AWSConfig, type AnnotationAddedEvent, type AnnotationBodyUpdatedEvent, type AnnotationCategory, type AnnotationId, type AnnotationRemovedEvent, type AppConfig, type BackendServiceConfig, type BaseEvent, type BodyItem, type BodyOperation, CORE_TYPES_VERSION, CREATION_METHODS, ConfigurationError, ConflictError, type CreateAnnotationInternal, type CreationMethod, type DatabaseServiceConfig, type EntityTagAddedEvent, type EntityTagRemovedEvent, type EntityTypeStats, type Environment, type EnvironmentConfig, type EventMetadata, type EventQuery, type EventSignature, type FilesystemServiceConfig, type FrontendServiceConfig, type GoogleAuthRequest, type GraphConnection, type GraphDatabaseType, type GraphPath, type GraphServiceConfig, type HttpClientConfig, type InferenceServiceConfig, type JobCompletedEvent, type JobFailedEvent, type JobProgressEvent, type JobStartedEvent, type McpServiceConfig, NotFoundError, type PlatformType, type ResourceAnnotations, type ResourceArchivedEvent, type ResourceClonedEvent, type ResourceCreatedEvent, type ResourceCreationDetails, type ResourceEvent, type ResourceEventType, type ResourceFilter, type ResourceId, type ResourceScopedEvent, type ResourceUnarchivedEvent, SDK_VERSION, ScriptError, type SemiontConfig, SemiontError, type ServiceConfig, type ServicePlatformConfig, type ServicesConfig, type SiteConfig, type StoredEvent, type SystemEvent, UnauthorizedError, type UpdateResourceInput, type UserId, ValidationError, type ValidationResult, annotationId, bodyItemsMatch, calculateChecksum, createFetchAPI, didToAgent, fetchAPI, findBodyItem, findProjectRoot, formatEventType, formatRelativeTime, generateId, generateToken, generateUuid, getAllPlatformTypes, getAnnotationIdFromEvent, getAvailableEnvironments, getEnvironmentsPath, getEventDisplayContent, getEventEmoji, getEventEntityTypes, getEventType, getNodeEnvForEnvironment, getResourceCreationDetails, getSemiontConfigPath, isAnnotationId, isArray, isBoolean, isDefined, isEventRelatedToAnnotation, isFunction, isNull, isNullish, isNumber, isObject, isProjectRoot, isResourceEvent, isResourceId, isResourceScopedEvent, isString, isSystemEvent, isUndefined, isValidEnvironment, isValidPlatformType, loadEnvironmentConfig, parseEnvironment, resourceId, userId, userToAgent, userToDid, validateEnvironment, validateEnvironmentConfig, validateSemiontConfig, validateSiteConfig, verifyChecksum };