cratefield-core 0.10.1

//! `cratefield-core` is the runtime-agnostic kernel of the Factory Zero harness:
//! the [`Module`] contract, the [`Harness`] builder, port traits, RFC 9457
//! problem+json errors, the request [`Scope`], an in-process [`EventBus`] and
//! a [`TemplateRegistry`] (ADR 0001, 0002, 0007).
//!
//! Core depends only on `http`, `axum` (default features off), `serde`,
//! `tracing`, `sea-query` and pure-Rust crypto. It must never depend on
//! `worker`, `wasm-bindgen`, `tokio`, `reqwest`, `sqlx` or `rusqlite`, and
//! never touches `std::fs` or `std::net` — CI enforces this with a
//! `cargo tree` check and the wasm build of `examples/venture`.

#![doc = include_str!("../README.md")]
#![forbid(unsafe_code)]

mod admin;
mod api_key;
// Outbound HTTP budgets (issue #765): the shared token bucket, daily
// quota and retry policy adapters opt into by wrapping their HttpClient.
// Private like `usage`, with the surface re-exported below.
mod budget;
mod classifier_agreement;
mod classifier_routing;
mod config;
mod cooldown;
mod cost;
mod csv;
mod email;
mod events;
mod harness;
mod http;
mod idempotency;
mod lint;
mod logging;
mod module;
mod origin;
mod outbox;
mod personal_data;
mod ports;
mod problem;
mod problems;
mod rate_limit;
mod route_policy;
mod scheduled;
mod scope;
mod sidecar;
mod signer;
// The provider-neutral billing lifecycle (issue #593): the names are
// generic, so the module is public and namespaced as `billing::`.
pub mod billing;
// The `Blob` port's presigned URLs (issue #622); pure `SigV4`, public so
// adapters and tests share one implementation.
pub mod sigv4;
// Incremental Server-Sent Events decoding (issue #859): the wire format
// streaming completions arrive in, public so adapters and routes share
// the one parser.
pub mod sse;
mod stream;
mod structured_output;
mod surface;
mod template;
mod tenant;
mod tenant_conn;
mod tenant_lifecycle;
// Chunk-and-reassemble completion on `TextModel` (issue #847): the
// paragraph- and fence-aware splitter plus the `complete_chunked` trait,
// so a caller rewrites a long document in bounded, whole-block chunks
// instead of hand-splitting one.
mod text_chunks;
mod tool_loop;
mod usage;
mod venture;
mod webhook_signature;

// `Module::router` returns an `axum::Router` and `well_known` an
// `Option<axum::Router>`, so a module author cannot implement the trait
// without axum — and an out-of-tree one has no workspace to inherit the
// version from. Picking a semver-incompatible one gives a type error
// about two `Router`s that look identical, which is a bad afternoon.
// Re-exported so there is one axum and it is this crate's.
pub use axum;

pub use admin::{bearer_token, constant_time_eq, require_admin};
pub use api_key::{
    ApiKeyError, ApiKeyMode, ApiKeyPrincipal, ApiKeys, IssuedKey, RandomBytes, RandomError,
    require_api_key,
};
pub use budget::{
    Budget, BudgetRouter, BudgetedHttpClient, DEFAULT_ALERT_TABLE, DEFAULT_BUCKET_TABLE,
    DEFAULT_QUOTA_TABLE, EVENT_QUOTA_EXHAUSTED, EVENT_QUOTA_WARNING, Idempotent, RetryPolicy,
    Sleeper,
};
pub use classifier_agreement::{
    AgreementAt, AgreementLog, AgreementReport, CalibrationPoint, CorpusItem, Disagreement,
    GroundTruth, KindAgreement, answer_margin, measure_agreement, values_agree,
};
pub use classifier_routing::{
    RouteReason, Routed, RoutingClassifier, RoutingError, RoutingMode, RoutingPolicy,
    ShadowClassifier, Thresholds,
};
pub use config::{Config, ConfigError, EmptyConfig, HarnessConfig, MapConfig, ModuleConfig};
pub use cooldown::SendCooldown;
pub use cost::{
    Accounting, AdapterId, CallOutcome, CallRecord, CallRole, Cost, CostLedger, InMemoryLedger,
    LedgerTotals, Price, PriceSheet, QuestionKind, TokenSource, Tokens,
};
pub use csv::{FORMULA_PREFIXES, MAX_EXPORT_ROWS, escape as csv_escape, row as csv_row};
pub use email::{
    MAX_EMAIL_BYTES, MAX_LOCAL_BYTES, invalid_email_problem, is_valid,
    normalize as normalize_email, validation_error,
};
pub use events::{AnyError, EventBus, EventHandler, EventName};
pub use harness::{Harness, HarnessBuilder, Runtime};
pub use http::{
    Form, Json, MAX_BODY_BYTES, RequestSummary, X_REQUEST_ID, allowance_exhausted, rate_limited,
    request_id_is_valid,
};
pub use idempotency::Inbox;
pub use lint::{CARD_DATA, card_data_hit, created_tables, lint_card_data, lint_portable_sql};
pub use logging::{
    ControlLevel, RedactingVisitor, forward_control_event, is_email_field, is_secret_field,
    redacted_value, scrub_request_url, scrub_text, set_error_forwarder, set_log_pseudonym_key,
    subject_hash,
};
pub use module::{
    BoxFuture, HARNESS_API, Migrations, Module, ModuleContext, SqlMigration, assert_migration_set,
    harness_api_mismatch, is_idempotent_sql, migration_checksum, migration_edited,
    migration_missing_guard,
};
pub use origin::{OriginError, origin_of};
pub use outbox::{DrainOptions, DrainReport, Outbox, OutboxRecord, Processed};
pub use personal_data::{
    CatalogEntry, DataKind, Disposition, PersonalDataCatalog, PersonalDataSet, SubjectVia,
    is_plain_identifier, migration_tables, undeclared_tables, unlisted_tables,
};
pub use ports::{
    ACTOR_CALL_TIMEOUT, ActorContext, ActorError, ActorHandler, ActorHandlers, ActorStore,
    ActorWrites, Actors, Answer, AnswerValue, Auth, AuthError, Blob, BlobError, BlobObject,
    BoundedHttpClient, ByteStream, Calibration, Caller, Capability, Captcha, CaptchaBinding,
    CaptchaError, CertificateStatus, Charge, CheckoutRequest, CheckoutSession, Classifier,
    ClassifierError, ClassifierProfile, Clock, Completion, CompletionBuilder, ConnectAccountLink,
    ConnectAccountLinkRequest, Credential, CustomHostname, CustomHostnameError, CustomHostnames,
    DEFAULT_MAX_STATE_CHARS, DEFAULT_MAX_TOKENS, DEFAULT_RESPONSE_TIMEOUT,
    DEFAULT_STREAM_IDLE_TIMEOUT, DEFAULT_STREAM_TOTAL_TIMEOUT, Database, DbError, Decision, Defer,
    Destination, DispatchError, Dispatcher, DnsRecordType, EmbedError, Embedder, Embeddings,
    ExactVectorIndex, Filed, FinishReason, HostnameClaim, HostnameRefusal, HttpClient, HttpError,
    HttpPolicy, IdGen, ImageLimit, ImageMediaType, InboundStatusError, KeyValue, Kid, KvError,
    LineItem, LocKeys, MAX_ACTOR_KEY_BYTES, MAX_ACTOR_KIND_BYTES, MAX_ACTOR_MESSAGE_BYTES,
    MAX_ACTOR_REPLY_BYTES, MAX_ACTOR_VALUE_BYTES, MAX_BLOB_BYTES, MAX_CONCURRENT_REQUESTS,
    MAX_IMAGE_ENCODED_BYTES, MAX_KID_NAME, MAX_NAMESPACE_BYTES, MAX_PROMPT_IMAGE_ENCODED_BYTES,
    MAX_PROMPT_IMAGES, MAX_RESPONSE_BYTES, MAX_RESPONSE_TIMEOUT, MAX_STREAM_BYTES,
    MAX_STREAM_IDLE_TIMEOUT, MAX_STREAM_TOTAL_TIMEOUT, MailError, MailProvider, Mailer, Member,
    Message, ModelTier, Money, NoopDefer, Notification, Part, Payload, Payments, PaymentsError,
    Platform, Port, Ports, Priority, Prompt, ProviderStatus, Push, PushError, PushOutcome,
    Question, Quota, RateLimitError, RateLimiter, Realtime, RealtimeError, Recipient, Refund,
    RefundRequest, Role, RoomContext, RoomHandler, RoutingPush, RoutingTextModel, RoutingTracker,
    Row, Rows, ScopedActors, ScopedBlob, SendOutcome, Severity, SignatureError, Signer, Statement,
    StatusOnly, StatusUpdate, StatusWebhook, StreamPolicy, Subject, SubscriptionCheckoutRequest,
    SystemClock, TextDelta, TextModel, TextModelError, TicketComment, TicketDraft, TicketState,
    TicketStatus, ToolCall, ToolChoice, ToolResult, ToolSpec, Tracker, TrackerError,
    TransferCharge, TryFromValue, Turn, UlidIdGen, Unconfigured, UsageReport, UsageReported,
    Validation, ValidationMethod, VectorFilter, VectorIndex, VectorIndexError, VectorMatch,
    VectorNamespace, VectorRecord, Verdict, WebhookEvent, check_actor_call, check_blob_size,
    check_hostname, completion_deltas, declared_content_length, encode_image, encoded_image_len,
    receive_status, retry_after, run_actor_alarm, run_actor_message, stream_owned, timeout,
    ttl_secs, validate_actor_key, validate_actor_kind, validate_questions,
};
// The dispute, portal and subscription types on `Payments` (issues #589,
// #602, #690).
pub use ports::{
    Dispute, DisputeListRequest, DisputePage, DisputePhase, DisputeStatus, PortalSession,
    PortalSessionRequest, Subscription, SubscriptionStatus,
};
// The `Speech` port (issue #861), kept out of the wholesale block above
// so that block stays untouched.
pub use ports::{
    AudioFormat, DEFAULT_MAX_AUDIO_BYTES, DEFAULT_MAX_AUDIO_SECONDS, DEFAULT_MAX_SYNTHESIS_CHARS,
    NotConfiguredSpeech, Speech, SpeechCapabilities, SpeechError, SpeechLimit, SpeechLimits,
    SpeechUsage, Synthesis, SynthesizeRequest, TranscribeRequest, Transcript, Voice, WordTiming,
    check_synthesize, check_transcribe, primary_subtag, wav_duration,
};
// The `UrlSafety` port (issue #857), kept out of the wholesale block
// above so that block stays untouched.
pub use ports::{
    CachedUrlSafety, DEFAULT_CACHE_CAPACITY, DEFAULT_MAX_BATCH, DEFAULT_MAX_URL_LEN,
    DEFAULT_NEGATIVE_TTL, ThreatType, UrlSafety, UrlSafetyError, UrlSafetyLimit, UrlSafetyLimits,
    UrlSafetySource, UrlVerdict, check_batch, check_url,
};
// The Blob presign API (issue #622), kept out of the wholesale block above.
pub use ports::{DEFAULT_PRESIGN_TTL, MAX_PRESIGN_TTL, PresignedPut};
// The inbound mail source (issue #563), kept out of the wholesale block
// above so that block stays untouched.
pub use ports::{InboundMailError, InboundMailSource, InboundMessage, receive_mail};
// The Blob streamed reads/writes and multipart API (issue #586), kept out
// of the wholesale block above for the same reason.
pub use ports::{
    BlobMeta, BlobPage, BlobStream, MAX_LARGE_BLOB_BYTES, MAX_LIST_LIMIT, MAX_MULTIPART_PARTS,
    MIN_MULTIPART_PART_BYTES, PartReceipt, PendingUpload, UploadId, blob_error_from_stream,
    check_part_number, limit_stream,
};
pub use problem::{ABOUT_BLANK, Problem};
// `Slugs` is exported beside the `SLUGS` value it types. Without it a
// caller can read `SLUGS.validation_failed` and cannot write a function
// that takes the table — the value was reachable and its type was not
// nameable, which `unnameable_types` is what noticed.
pub use problems::{ProblemDef, SLUGS, Slugs, registry as problem_registry};
pub use rate_limit::{RateLimit, RateLimitFailure, check_rate_limit, client_ip, rate_limit_keys};
pub use route_policy::{
    ALLOW_UNLIMITED_PUBLIC_ROUTES, ALLOW_UNPROTECTED_WRITES, RoutePolicy, SignatureVerification,
    WriteGuards, captcha_effective, deployed_env, env_disagreement, payments_effective,
    production_readiness, rate_limiter_effective, signer_effective, stated_reason,
    unlimited_public_routes_override, unprotected_writes_override, verify_human_form,
    webhook_secret_readiness,
};
pub use scheduled::{ScheduledBudget, ScheduledLimits, ScheduledSplit};
pub use scope::Scope;
pub use sidecar::{
    GATEWAY_ADMIN_PURPOSE, GATEWAY_PURPOSE, GATEWAY_TOKEN_TTL_SECS, HARNESS_ONE_WORKER,
    HARNESS_SIDECARS, SIDECAR_GATEWAY_SECRET, SIDECAR_REQUIRE_GATEWAY, SidecarMount, SidecarMounts,
    X_HARNESS_API, X_HARNESS_GATEWAY, X_HARNESS_MODULE,
};
pub use signer::{
    CONFIRM_TOKEN_MAX_TTL_SECS, DEFAULT_TOKEN_MAX_TTL_SECS, HmacSigner, KeyRing, KeyState,
    MIN_SECRET_BYTES, RingKey, STATUS_TOKEN_MAX_TTL_SECS, SignerError, TokenPolicy,
    UNSUBSCRIBE_ACTION,
};
pub use stream::{BoxStream, RequestStream, ResponseStream, StreamError, StreamRoute};
pub use structured_output::TextModelExt;
pub use surface::{
    Action, Audience, Column, HINT_KEYWORDS, MAX_SIDECAR_ACTIONS, MAX_SIDECAR_SURFACE_BYTES,
    MAX_SIDECAR_VIEWS, ModuleSurface, Outcome, RenderedSurface, SURFACE_API, Surface,
    SurfaceDocument, SurfaceSource, UiContext, UiMount, VentureSurface, View, hint_field,
    schema_for,
};
pub use template::{Rendered, Template, TemplateError, TemplateRegistry};
pub use tenant::{
    IMPLICIT_TENANT, ImplicitTenant, Resolution, ResolveTenant, Tenancy, Tenant, TenantDatabases,
    TenantDbError, TenantId, TenantRouting, TenantStatus,
};
pub use tenant_conn::TenantConn;
pub use tenant_lifecycle::{
    ErasureStep, TenantLifecycle, TenantLifecycleError, TenantSummary, remaining_erasure,
};
// The chunk-and-reassemble companion to `TextModelExt` (issue #847).
pub use text_chunks::{TextModelChunkedExt, reassemble_text_chunks, split_text_chunks};
pub use tool_loop::{
    StepUsage, ToolBudget, ToolExecutor, ToolLoopError, ToolLoopEvent, ToolLoopOutcome,
    run_tool_loop, run_tool_loop_stream,
};
pub use usage::{Consumed, Consumption, Exhausted, Months, Period, PeriodWindow, Usage};
pub use venture::{Brand, Venture, VentureEnv};
pub use webhook_signature::{
    DEFAULT_TOLERANCE_SECS, Digest, Github, Gitlab, ProviderScheme, SharedTokenScheme,
    SignatureEncoding, SignatureScheme, SignedDelivery, StripeStyle, Svix, Vercel, WebhookVerifier,
    svix_secret_key,
};