semantic

package
v1.1.5 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 23, 2026 License: MIT Imports: 17 Imported by: 0

Documentation

Overview

Package semantic builds a layer-aware, Go-backend-independent model of TL schemas.

The package deliberately keeps wire identity (layer and constructor ID), wire shape, and canonical Go bindings as separate concerns. Code generators can therefore compare multiple historical schemas without changing the canonical tg package or relying on constructor IDs as shape identifiers.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func MarshalManifest 

func MarshalManifest(manifest Manifest) ([]byte, error)

MarshalManifest renders the stable checked-in representation used by the import workflow.

func RenderCanonicalSchema 

func RenderCanonicalSchema(manifest Manifest, canonicalSource []byte, overlaySources map[string][]byte) ([]byte, error)

RenderCanonicalSchema renders _schema/telegram.tl from the exact canonical manifest input plus every locked overlay. overlaySources is keyed by the overlay File value from the manifest. No network input participates.

Types

type Category 

type Category uint8

Category separates constructors from RPC methods. The same qualified name is allowed to exist in both categories without becoming one semantic family. 

const (
	CategoryType Category = iota
	CategoryFunction
)

func (Category) String 

func (c Category) String() string

type ClientRPCMethod 

type ClientRPCMethod struct {
	Definition *Definition
	Target     SemanticKey
	Renames    map[string]string
	Converters map[string]string
	Drops      []string
}

ClientRPCMethod joins one private wire definition to its current canonical semantic target and the explicit non-structural conversion rules.

type ClientRPCOverlay 

type ClientRPCOverlay struct {
	Name       string
	Repository string
	Commit     string
	File       string
	SHA256     ShapeDigest
	Sources    []ClientRPCOverlaySource
	Methods    []*ClientRPCMethod
}

ClientRPCOverlay is an audited client-private method schema compiled next to, but never merged into, the official Layer universe.

type ClientRPCOverlaySource 

type ClientRPCOverlaySource struct {
	Path string
	Blob string
}

type Condition 

type Condition struct {
	Word         string
	Bit          uint8
	PresenceOnly bool
}

Condition describes flags.N?T. PresenceOnly is true for flags.N?true, where no field body is written.

type Definition 

type Definition struct {
	Key            SemanticKey
	WireID         uint32
	GenericParams  []string
	Fields         []FieldShape
	Result         TypeRef
	Base           bool
	WireShape      WireShape
	BodyShape      ShapeDigest
	SemanticShape  ShapeDigest
	SignatureShape ShapeDigest
}

Definition is one constructor or method in one concrete layer.

type DefinitionChange 

type DefinitionChange struct {
	Key              SemanticKey
	Target           *Definition
	Canonical        *Definition
	WireIDChanged    bool
	WireShapeChanged bool
	BodyChanged      bool
	ResultChanged    bool
}

DefinitionChange compares one shared semantic definition with canonical.

func (DefinitionChange) ResultOnly 

func (c DefinitionChange) ResultOnly() bool

ResultOnly reports a method/type whose body is stable but result TypeRef is different. Such RPC methods require method-aware result encoding.

func (DefinitionChange) SameIDSemanticChanged 

func (c DefinitionChange) SameIDSemanticChanged() bool

SameIDSemanticChanged reports profile semantics that changed while the constructor/method ID remained stable. This is not a payload conflict.

func (DefinitionChange) SameWireSignatureChanged 

func (c DefinitionChange) SameWireSignatureChanged() bool

SameWireSignatureChanged is the compatibility name for SameIDSemanticChanged.

func (DefinitionChange) SignatureChanged 

func (c DefinitionChange) SignatureChanged() bool

SignatureChanged reports whether fields or result TypeRef changed. Wire ID is intentionally independent: equal IDs do not imply equal signatures.

type DefinitionKey 

type DefinitionKey = SemanticKey

DefinitionKey is kept as a source-compatible name for SemanticKey.

type Difference 

type Difference struct {
	Layer         int
	Changes       []DefinitionChange
	CanonicalOnly []*Definition
	OldOnly       []*Definition
}

Difference is a target-layer comparison against canonical.

func (Difference) ResultOnlyChanges 

func (d Difference) ResultOnlyChanges() []DefinitionChange

ResultOnlyChanges returns all body-stable/result-changing definitions.

func (Difference) SameIDSemanticChanges 

func (d Difference) SameIDSemanticChanges() []DefinitionChange

SameIDSemanticChanges returns all same-ID semantic changes.

func (Difference) SameWireSignatureChanges 

func (d Difference) SameWireSignatureChanges() []DefinitionChange

SameWireSignatureChanges returns all same-ID/different-shape changes.

func (Difference) SignatureChanges 

func (d Difference) SignatureChanges() []DefinitionChange

SignatureChanges returns changes whose fields and/or result differ.

type Family 

type Family struct {
	Key             SemanticKey
	ByLayer         map[int]*Definition
	ProfilesByLayer map[int]*ProfileVariant
	ProfileVariants []*ProfileVariant
	Variants        []*SignatureVariant
}

Family groups the same category-qualified definition across layers.

type FieldKind 

type FieldKind uint8

FieldKind distinguishes a flags word from an encoded field value. 

const (
	FieldValue FieldKind = iota
	FieldFlagsWord
)

type FieldShape 

type FieldShape struct {
	Kind      FieldKind
	Name      string
	Ordinal   int
	Type      TypeRef
	Condition *Condition
}

FieldShape is one ordered TL parameter.

type LayerArtifact 

type LayerArtifact struct {
	Layer   int
	Source  []byte
	SHA256  string
	GitBlob string
}

LayerArtifact is one locally inspected, immutable TL schema input. Layer is read from the TL source; the two digests are computed from Source rather than accepted as caller-provided metadata.

func InspectLayerArtifact 

func InspectLayerArtifact(source []byte) (LayerArtifact, error)

InspectLayerArtifact parses a local TL source and derives every piece of content-addressed metadata needed by manifest.json. GitBlob is the SHA-1 object ID used by the upstream GitHub repository ("blob <size>\x00<body>"); it is provenance metadata, not a security digest. SHA256 remains the offline integrity lock.

type Manifest 

type Manifest struct {
	CanonicalLayer    int                        `json:"canonical_layer"`
	Repository        string                     `json:"repository"`
	SourcePath        string                     `json:"source_path"`
	Overlays          []ManifestOverlay          `json:"overlays"`
	ClientRPCOverlays []ManifestClientRPCOverlay `json:"client_rpc_overlays,omitempty"`
	Layers            []ManifestLayer            `json:"layers"`
}

Manifest locks all schema inputs and their upstream provenance.

func ReadManifest 

func ReadManifest(path string) (Manifest, error)

ReadManifest parses a manifest and rejects unknown or invalid fields.

func UpdateManifestLayer 

func UpdateManifestLayer(manifest Manifest, artifact LayerArtifact, commit, file string, canonical, replace bool) (Manifest, error)

UpdateManifestLayer returns a detached manifest containing artifact. An identical import is idempotent. Replacing different bytes or provenance for an existing layer requires replace=true so a layer cannot drift silently.

type ManifestClientRPCMethod 

type ManifestClientRPCMethod struct {
	Target     string            `json:"target,omitempty"`
	Renames    map[string]string `json:"renames,omitempty"`
	Converters map[string]string `json:"converters,omitempty"`
	Drops      []string          `json:"drops,omitempty"`
}

ManifestClientRPCMethod declares the non-structural decisions which schema comparison cannot infer. Rename keys are canonical target fields and values are client-source fields. Converter keys are canonical target fields.

type ManifestClientRPCOverlay 

type ManifestClientRPCOverlay struct {
	Name       string                             `json:"name"`
	File       string                             `json:"file"`
	SHA256     string                             `json:"sha256"`
	Repository string                             `json:"repository"`
	Commit     string                             `json:"commit"`
	Sources    []ManifestClientRPCOverlaySource   `json:"sources"`
	Methods    map[string]ManifestClientRPCMethod `json:"methods"`
}

ManifestClientRPCOverlay is one explicitly audited client-private method schema. Unlike an ordinary overlay, these definitions are not merged into any official Layer profile. gotdgen compiles them into a separate static unknown-method adapter which targets the current canonical method by semantic name.

type ManifestClientRPCOverlaySource 

type ManifestClientRPCOverlaySource struct {
	Path string `json:"path"`
	Blob string `json:"blob"`
}

ManifestClientRPCOverlaySource locks one upstream source file from which the derived TL declarations were audited.

type ManifestLayer 

type ManifestLayer struct {
	Layer  int    `json:"layer"`
	File   string `json:"file"`
	Commit string `json:"commit"`
	Blob   string `json:"blob"`
	SHA256 string `json:"sha256"`
}

ManifestLayer is one immutable TDesktop schema source.

type ManifestOverlay 

type ManifestOverlay struct {
	File       string `json:"file"`
	Repository string `json:"repository"`
	Commit     string `json:"commit"`
	Blob       string `json:"blob"`
	Path       string `json:"path"`
	SHA256     string `json:"sha256"`
}

ManifestOverlay is one immutable schema overlay and its exact artifact provenance. Git tree provenance is verified by the import/sync workflow; offline generation verifies the locked local SHA256 only.

type ProfileVariant 

type ProfileVariant struct {
	Layer         int
	Definition    *Definition
	WireCodec     *WireCodec
	SemanticShape ShapeDigest
}

ProfileVariant binds one layer's semantic definition to its shared payload codec. Result types and presence-only flags remain profile semantics.

type SchemaModel 

type SchemaModel struct {
	Layer               int
	Source              SourceRef
	Definitions         []*Definition
	ByKey               map[SemanticKey]*Definition
	ByWire              map[uint32]*Definition
	ConstructorsByClass map[string][]SemanticKey
	// contains filtered or unexported fields
}

SchemaModel is a validated semantic view of one TL layer.

func BuildSchema 

func BuildSchema(schema *tl.Schema, source SourceRef) (*SchemaModel, error)

BuildSchema validates and converts a parsed TL schema into semantic IR.

type SemanticKey 

type SemanticKey struct {
	Category Category
	QName    string
}

SemanticKey is the stable semantic identity of a constructor or method. Wire IDs are deliberately not part of semantic identity.

func (SemanticKey) String 

func (k SemanticKey) String() string

type ShapeDigest 

type ShapeDigest [sha256.Size]byte

ShapeDigest is a stable SHA-256 digest of TL semantic shape.

func (ShapeDigest) String 

func (d ShapeDigest) String() string

type SignatureVariant 

type SignatureVariant struct {
	WireID         uint32
	BodyShape      ShapeDigest
	SignatureShape ShapeDigest
	Definition     *Definition
	WireCodec      *WireCodec
	Layers         []int
}

SignatureVariant is the compatibility view that groups identical semantic signatures across profiles. Layers can be non-contiguous; callers must not infer ranges from endpoints.

type SourceRef 

type SourceRef struct {
	Layer      int
	Repository string
	Commit     string
	Blob       string
	Path       string
	File       string
	SHA256     ShapeDigest
}

SourceRef records the immutable provenance of one layer schema.

type TypeKind 

type TypeKind uint8

TypeKind classifies the wire-relevant form of a TL type reference. 

const (
	// TypePrimitive is a TL primitive or built-in value.
	TypePrimitive TypeKind = iota
	// TypeNamed refers to a TL constructor class or an exact bare constructor.
	TypeNamed
	// TypeVector is a boxed Vector<T> or bare vector<T>.
	TypeVector
	// TypeGenericRef refers to a generic parameter, such as !X.
	TypeGenericRef
)

type TypeRef 

type TypeRef struct {
	Kind    TypeKind
	QName   string
	Bare    bool
	Percent bool
	Arg     *TypeRef
}

TypeRef is a recursive, lossless representation of the wire-relevant parts of tl.Type. Arg is populated for generic applications, including vectors.

func (TypeRef) Equal 

func (t TypeRef) Equal(other TypeRef) bool

Equal reports whether two references have identical TL wire semantics.

func (TypeRef) String 

func (t TypeRef) String() string

String renders a compact TL spelling for diagnostics.

type Universe 

type Universe struct {
	CanonicalLayer    int
	Schemas           map[int]*SchemaModel
	Families          map[SemanticKey]*Family
	ByWire            map[int]map[uint32]*Definition
	WireCodecs        map[uint32]*WireCodec
	ClientRPCOverlays []*ClientRPCOverlay
	SemanticDigest    ShapeDigest
}

Universe is the validated collection of all supported layer schemas.

func LoadManifestUniverse 

func LoadManifestUniverse(manifest Manifest, root string, overrides map[string][]byte) (*Universe, error)

LoadManifestUniverse validates and loads an in-memory manifest using schema files rooted at root. overrides, keyed by manifest File, replace selected filesystem inputs. The schema import workflow uses this to prove the complete future universe before changing manifest.json or any layer file.

func LoadUniverse 

func LoadUniverse(manifestPath string) (*Universe, error)

LoadUniverse reads, hashes, parses, overlays, and validates every schema in a manifest. Schema files are resolved relative to the manifest directory.

func NewUniverse 

func NewUniverse(canonicalLayer int, schemas ...*SchemaModel) (*Universe, error)

NewUniverse validates layer identity and groups definitions by semantic key.

func (*Universe) CanonicalSchema 

func (u *Universe) CanonicalSchema() *tl.Schema

CanonicalSchema returns a deep copy suitable for the existing Go backend. Mutating the returned schema cannot alter the Universe.

func (*Universe) Diff 

func (u *Universe) Diff(layer int) (Difference, error)

Diff compares a supported target layer against canonical by semantic key.

func (*Universe) Layers 

func (u *Universe) Layers() []int

Layers returns supported layers in ascending order.

func (*Universe) SortedKeys 

func (u *Universe) SortedKeys() []DefinitionKey

SortedKeys returns family keys in deterministic category/name order.

type Variant 

type Variant = SignatureVariant

Variant is kept as a source-compatible name for SignatureVariant.

type WireCodec 

type WireCodec struct {
	WireID          uint32
	Key             SemanticKey
	Shape           WireShape
	ProfileVariants []*ProfileVariant
}

WireCodec is one reusable payload codec. It contains no profile-specific field semantics, so flags.N?true changes do not duplicate codecs.

type WireShape 

type WireShape ShapeDigest

WireShape identifies the exact encoded request/constructor payload shape. It intentionally excludes result types, field names and flags.N?true fields, because none of those write bytes to the payload.

func (WireShape) String 

func (s WireShape) String() string

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.