@mochabug/adaptkit/bin/genproto/mochabugapis/adapt/graph/signal_format_pb.d.ts

A cmd to create, emulate and publish Mochabug Adapt plugins

import type { GenFile, GenMessage } from "@bufbuild/protobuf/codegenv2";
import type { JTDSchema, JTDSchemaJson } from "./jtd_schema_pb";
import type { Message } from "@bufbuild/protobuf";
/**
 * Describes the file mochabugapis/adapt/graph/signal_format.proto.
 */
export declare const file_mochabugapis_adapt_graph_signal_format: GenFile;
/**
 * SignalFormat defines how signal data is structured and should be interpreted.
 * All signals are binary at the transport level; this message determines the interpretation.
 *
 * This message is designed to be reusable across both signal descriptors (which produce
 * one specific format or format family) and signal bindings (which may accept multiple formats).
 *
 * Format matching semantics:
 * - JTD schemas use structural subsumption (handled by existing JTD subsume algorithm)
 * - MIME types use pattern matching with optional wildcards
 * - JTD and MIME formats are incompatible - a JTD signal cannot bind to a MIME-accepting
 *   binding and vice versa, even if semantically similar (e.g., application/json vs JTD)
 *
 * @generated from message mochabugapis.adapt.graph.SignalFormat
 */
export type SignalFormat = Message<"mochabugapis.adapt.graph.SignalFormat"> & {
    /**
     * The format specification is mutually exclusive - a signal format is either:
     * - jtd_schema: Structured JSON with schema validation (enables automatic validation,
     *   type inference, and platform-level tooling support)
     * - mime_type: Generic binary format identification for non-JSON data
     *
     * Design note: While JSON data is technically "application/json" as a MIME type,
     * using jtd_schema instead provides platform-level schema validation, automatic
     * type checking, and better developer tooling support.
     *
     * @generated from oneof mochabugapis.adapt.graph.SignalFormat.format
     */
    format: {
        /**
         * Schema definition for JSON-structured signals.
         * Must follow the JSON Type Definition (JTD) specification: https://www.rfc-editor.org/rfc/rfc8927
         *
         * The empty schema {} validates any JSON value.
         *
         * Common JTD primitive types:
         * - "string": JSON string values
         * - "float32", "float64": JSON numbers with specific precision
         * - "int8", "int16", "int32": JSON numbers representing integers
         * - "boolean": JSON boolean values (true/false)
         * - "timestamp": ISO 8601 datetime strings (RFC 3339 format)
         *
         * JTD also supports complex types:
         * - elements: { elements: { type: "string" } } for arrays
         * - properties: { properties: { id: { type: "int32" } } } for objects
         * - discriminator: For tagged unions
         * - enum: For enumerated string values
         * - nullable: Wraps any type to allow null
         *
         * Compatibility checking:
         * JTD schemas are checked for structural compatibility using subsumption rules.
         * A producer schema is compatible with a consumer schema if every valid value
         * under the producer schema is also valid under the consumer schema.
         *
         * Example usage for text display binding (accepts primitive types):
         *   accepts = [
         *     { jtd_schema: { type: "string" } },
         *     { jtd_schema: { type: "float64" } },
         *     { jtd_schema: { type: "int32" } },
         *     { jtd_schema: { type: "boolean" } },
         *     { jtd_schema: { type: "timestamp" } }
         *   ]
         *
         * @generated from field: mochabugapis.adapt.graph.JTDSchema jtd_schema = 1;
         */
        value: JTDSchema;
        case: "jtdSchema";
    } | {
        /**
         * MIME type for binary format signals.
         * Must be a concrete MIME type or a type-family wildcard, conforming to RFC 6838
         * media type specifications (without parameters).
         *
         * Format requirements:
         * - Structure: type/subtype (e.g., "image/png", "image/*")
         * - Type must be concrete (alphanumeric start + allowed characters)
         * - Subtype can be concrete OR wildcard "*"
         * - NO parameters allowed (no semicolons or charset specifications)
         * - Case-insensitive but conventionally lowercase
         * - Maximum length: 255 characters (127 for type + "/" + 127 for subtype)
         *
         * Wildcard rules:
         * Wildcards are allowed in two forms:
         * ✅ "*\/*"           - Universal wildcard (accepts/produces any format)
         * ✅ "image/*"       - Type-family wildcard (accepts/produces any image format)
         * ✅ "text/*"        - Type-family wildcard (accepts/produces any text format)
         * ✅ "application/*" - Type-family wildcard (accepts/produces any application format)
         * ✅ "image/png"     - Concrete type (no wildcard)
         * ❌ "*\/png"         - Type wildcard with concrete subtype forbidden (semantically invalid)
         * ❌ "*\/json"        - Type wildcard with concrete subtype forbidden (semantically invalid)
         *
         * Why no parameters?
         * Parameters like charset, boundary, and encoding are transport-level concerns
         * in this system. All data is transmitted as binary/JSON, and character encoding
         * is handled at the serialization layer, not the graph validation layer.
         *
         * **Character Encoding Assumption**:
         * All text-based formats (text/*, application/json, application/xml, etc.) are
         * assumed to use UTF-8 encoding. This is a platform-wide convention that ensures
         * consistent text handling across all signal processing. When specifying text MIME
         * types, charset parameters are forbidden and UTF-8 is always assumed.
         *
         * Examples of forbidden formats:
         * ❌ "text/plain; charset=utf-8"     (redundant - UTF-8 is assumed)
         * ❌ "text/plain; charset=iso-8859-1" (non-UTF-8 encodings not supported)
         * ❌ "application/json; format=compact"
         * Instead use: "text/plain" or "application/json"
         *
         *
         * Semantic meaning for producers vs consumers:
         * - In SignalDescriptor (producer):
         *   - "*\/*" means "this signal's format is completely dynamic"
         *   - "image/*" means "this signal produces an image, format depends on runtime"
         * - In SignalBinding (consumer):
         *   - "*\/*" means "this binding accepts any format universally"
         *   - "image/*" means "this binding accepts any image format"
         *
         * MIME type compatibility checking (subsumption rules):
         * Subsumption hierarchy: Concrete ⊆ Type-family ⊆ Universal
         * Example: image/png ⊆ image/* ⊆ *\/*
         *
         * A producer format is compatible with a consumer format if:
         * - Both are concrete and equal: "image/png" ⊆ "image/png" ✅
         * - Producer is concrete, consumer is type-family: "image/png" ⊆ "image/*" ✅
         * - Producer is concrete, consumer is universal: "image/png" ⊆ "*\/*" ✅
         * - Both are type-family of same type: "image/*" ⊆ "image/*" ✅
         * - Producer is type-family, consumer is universal: "image/*" ⊆ "*\/*" ✅
         * - Both are universal: "*\/*" ⊆ "*\/*" ✅
         * - Producer is type-family, consumer is concrete: "image/*" ⊆ "image/png" ❌
         * - Producer is universal, consumer is type-family: "*\/*" ⊆ "image/*" ❌
         * - Producer is universal, consumer is concrete: "*\/*" ⊆ "image/png" ❌
         * - Different types: "image/png" ⊆ "text/*" ❌
         *
         * Common concrete examples:
         * - Images: "image/png", "image/jpeg", "image/webp", "image/gif", "image/svg+xml"
         * - Documents: "application/pdf", "text/html", "text/markdown"
         * - Binary: "application/octet-stream", "application/zip"
         * - Text: "text/plain", "text/csv"
         *
         * Common wildcard examples:
         * - "image/*": Any raster or vector image format
         * - "text/*": Any text-based format
         * - "application/*": Any application-specific binary format
         * - "audio/*": Any audio format
         * - "video/*": Any video format
         *
         * @generated from field: string mime_type = 2;
         */
        value: string;
        case: "mimeType";
    } | {
        case: undefined;
        value?: undefined;
    };
};
/**
 * SignalFormat defines how signal data is structured and should be interpreted.
 * All signals are binary at the transport level; this message determines the interpretation.
 *
 * This message is designed to be reusable across both signal descriptors (which produce
 * one specific format or format family) and signal bindings (which may accept multiple formats).
 *
 * Format matching semantics:
 * - JTD schemas use structural subsumption (handled by existing JTD subsume algorithm)
 * - MIME types use pattern matching with optional wildcards
 * - JTD and MIME formats are incompatible - a JTD signal cannot bind to a MIME-accepting
 *   binding and vice versa, even if semantically similar (e.g., application/json vs JTD)
 *
 * @generated from message mochabugapis.adapt.graph.SignalFormat
 */
export type SignalFormatJson = {
    /**
     * Schema definition for JSON-structured signals.
     * Must follow the JSON Type Definition (JTD) specification: https://www.rfc-editor.org/rfc/rfc8927
     *
     * The empty schema {} validates any JSON value.
     *
     * Common JTD primitive types:
     * - "string": JSON string values
     * - "float32", "float64": JSON numbers with specific precision
     * - "int8", "int16", "int32": JSON numbers representing integers
     * - "boolean": JSON boolean values (true/false)
     * - "timestamp": ISO 8601 datetime strings (RFC 3339 format)
     *
     * JTD also supports complex types:
     * - elements: { elements: { type: "string" } } for arrays
     * - properties: { properties: { id: { type: "int32" } } } for objects
     * - discriminator: For tagged unions
     * - enum: For enumerated string values
     * - nullable: Wraps any type to allow null
     *
     * Compatibility checking:
     * JTD schemas are checked for structural compatibility using subsumption rules.
     * A producer schema is compatible with a consumer schema if every valid value
     * under the producer schema is also valid under the consumer schema.
     *
     * Example usage for text display binding (accepts primitive types):
     *   accepts = [
     *     { jtd_schema: { type: "string" } },
     *     { jtd_schema: { type: "float64" } },
     *     { jtd_schema: { type: "int32" } },
     *     { jtd_schema: { type: "boolean" } },
     *     { jtd_schema: { type: "timestamp" } }
     *   ]
     *
     * @generated from field: mochabugapis.adapt.graph.JTDSchema jtd_schema = 1;
     */
    jtdSchema?: JTDSchemaJson;
    /**
     * MIME type for binary format signals.
     * Must be a concrete MIME type or a type-family wildcard, conforming to RFC 6838
     * media type specifications (without parameters).
     *
     * Format requirements:
     * - Structure: type/subtype (e.g., "image/png", "image/*")
     * - Type must be concrete (alphanumeric start + allowed characters)
     * - Subtype can be concrete OR wildcard "*"
     * - NO parameters allowed (no semicolons or charset specifications)
     * - Case-insensitive but conventionally lowercase
     * - Maximum length: 255 characters (127 for type + "/" + 127 for subtype)
     *
     * Wildcard rules:
     * Wildcards are allowed in two forms:
     * ✅ "*\/*"           - Universal wildcard (accepts/produces any format)
     * ✅ "image/*"       - Type-family wildcard (accepts/produces any image format)
     * ✅ "text/*"        - Type-family wildcard (accepts/produces any text format)
     * ✅ "application/*" - Type-family wildcard (accepts/produces any application format)
     * ✅ "image/png"     - Concrete type (no wildcard)
     * ❌ "*\/png"         - Type wildcard with concrete subtype forbidden (semantically invalid)
     * ❌ "*\/json"        - Type wildcard with concrete subtype forbidden (semantically invalid)
     *
     * Why no parameters?
     * Parameters like charset, boundary, and encoding are transport-level concerns
     * in this system. All data is transmitted as binary/JSON, and character encoding
     * is handled at the serialization layer, not the graph validation layer.
     *
     * **Character Encoding Assumption**:
     * All text-based formats (text/*, application/json, application/xml, etc.) are
     * assumed to use UTF-8 encoding. This is a platform-wide convention that ensures
     * consistent text handling across all signal processing. When specifying text MIME
     * types, charset parameters are forbidden and UTF-8 is always assumed.
     *
     * Examples of forbidden formats:
     * ❌ "text/plain; charset=utf-8"     (redundant - UTF-8 is assumed)
     * ❌ "text/plain; charset=iso-8859-1" (non-UTF-8 encodings not supported)
     * ❌ "application/json; format=compact"
     * Instead use: "text/plain" or "application/json"
     *
     *
     * Semantic meaning for producers vs consumers:
     * - In SignalDescriptor (producer):
     *   - "*\/*" means "this signal's format is completely dynamic"
     *   - "image/*" means "this signal produces an image, format depends on runtime"
     * - In SignalBinding (consumer):
     *   - "*\/*" means "this binding accepts any format universally"
     *   - "image/*" means "this binding accepts any image format"
     *
     * MIME type compatibility checking (subsumption rules):
     * Subsumption hierarchy: Concrete ⊆ Type-family ⊆ Universal
     * Example: image/png ⊆ image/* ⊆ *\/*
     *
     * A producer format is compatible with a consumer format if:
     * - Both are concrete and equal: "image/png" ⊆ "image/png" ✅
     * - Producer is concrete, consumer is type-family: "image/png" ⊆ "image/*" ✅
     * - Producer is concrete, consumer is universal: "image/png" ⊆ "*\/*" ✅
     * - Both are type-family of same type: "image/*" ⊆ "image/*" ✅
     * - Producer is type-family, consumer is universal: "image/*" ⊆ "*\/*" ✅
     * - Both are universal: "*\/*" ⊆ "*\/*" ✅
     * - Producer is type-family, consumer is concrete: "image/*" ⊆ "image/png" ❌
     * - Producer is universal, consumer is type-family: "*\/*" ⊆ "image/*" ❌
     * - Producer is universal, consumer is concrete: "*\/*" ⊆ "image/png" ❌
     * - Different types: "image/png" ⊆ "text/*" ❌
     *
     * Common concrete examples:
     * - Images: "image/png", "image/jpeg", "image/webp", "image/gif", "image/svg+xml"
     * - Documents: "application/pdf", "text/html", "text/markdown"
     * - Binary: "application/octet-stream", "application/zip"
     * - Text: "text/plain", "text/csv"
     *
     * Common wildcard examples:
     * - "image/*": Any raster or vector image format
     * - "text/*": Any text-based format
     * - "application/*": Any application-specific binary format
     * - "audio/*": Any audio format
     * - "video/*": Any video format
     *
     * @generated from field: string mime_type = 2;
     */
    mimeType?: string;
};
/**
 * Describes the message mochabugapis.adapt.graph.SignalFormat.
 * Use `create(SignalFormatSchema)` to create a new message.
 */
export declare const SignalFormatSchema: GenMessage<SignalFormat, {
    jsonType: SignalFormatJson;
}>;
//# sourceMappingURL=signal_format_pb.d.ts.map