@canon-protocol/types 8.0.0

package/dist/ctl/models/enums.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Types of CTL validation errors.
+ */
+export declare enum CtlValidationErrorType {
+    /**
+     * The Canon URI could not be parsed.
+     */
+    InvalidUri = 0,
+    /**
+     * The referenced publisher does not exist.
+     */
+    PublisherNotFound = 1,
+    /**
+     * The referenced package does not exist.
+     */
+    PackageNotFound = 2,
+    /**
+     * The referenced package version does not exist.
+     */
+    VersionNotFound = 3,
+    /**
+     * The referenced entity does not exist in the package.
+     */
+    EntityNotFound = 4,
+    /**
+     * A path segment in a deep link could not be resolved.
+     */
+    PathNotFound = 5,
+    /**
+     * An array index in a deep link is out of bounds.
+     */
+    IndexOutOfBounds = 6,
+    /**
+     * The reference is ambiguous (multiple matches).
+     */
+    AmbiguousReference = 7,
+    /**
+     * General parse error in the CTL document.
+     */
+    ParseError = 8
+}
+/**
+ * Severity levels for CTL validation issues.
+ */
+export declare enum CtlValidationSeverity {
+    /**
+     * Error - the document is invalid.
+     */
+    Error = 0,
+    /**
+     * Warning - the document may have issues but is usable.
+     */
+    Warning = 1,
+    /**
+     * Information - advisory message.
+     */
+    Info = 2
+}

package/dist/ctl/models/enums.js

@@ -0,0 +1,64 @@
+// This file was auto-generated by Canon SDK Transpiler v1.0.0
+// Source: canon-sdk-csharp\Canon.CTL\Models\CtlValidationResult.cs
+// SourceHash: sha256-711e1203192988518a0c03dcb43f8dc38e2fecb2e71a364bad73f5acfe9ae38b
+// DO NOT EDIT - changes will be overwritten
+/**
+ * Types of CTL validation errors.
+ */
+export var CtlValidationErrorType;
+(function (CtlValidationErrorType) {
+    /**
+     * The Canon URI could not be parsed.
+     */
+    CtlValidationErrorType[CtlValidationErrorType["InvalidUri"] = 0] = "InvalidUri";
+    /**
+     * The referenced publisher does not exist.
+     */
+    CtlValidationErrorType[CtlValidationErrorType["PublisherNotFound"] = 1] = "PublisherNotFound";
+    /**
+     * The referenced package does not exist.
+     */
+    CtlValidationErrorType[CtlValidationErrorType["PackageNotFound"] = 2] = "PackageNotFound";
+    /**
+     * The referenced package version does not exist.
+     */
+    CtlValidationErrorType[CtlValidationErrorType["VersionNotFound"] = 3] = "VersionNotFound";
+    /**
+     * The referenced entity does not exist in the package.
+     */
+    CtlValidationErrorType[CtlValidationErrorType["EntityNotFound"] = 4] = "EntityNotFound";
+    /**
+     * A path segment in a deep link could not be resolved.
+     */
+    CtlValidationErrorType[CtlValidationErrorType["PathNotFound"] = 5] = "PathNotFound";
+    /**
+     * An array index in a deep link is out of bounds.
+     */
+    CtlValidationErrorType[CtlValidationErrorType["IndexOutOfBounds"] = 6] = "IndexOutOfBounds";
+    /**
+     * The reference is ambiguous (multiple matches).
+     */
+    CtlValidationErrorType[CtlValidationErrorType["AmbiguousReference"] = 7] = "AmbiguousReference";
+    /**
+     * General parse error in the CTL document.
+     */
+    CtlValidationErrorType[CtlValidationErrorType["ParseError"] = 8] = "ParseError";
+})(CtlValidationErrorType || (CtlValidationErrorType = {}));
+/**
+ * Severity levels for CTL validation issues.
+ */
+export var CtlValidationSeverity;
+(function (CtlValidationSeverity) {
+    /**
+     * Error - the document is invalid.
+     */
+    CtlValidationSeverity[CtlValidationSeverity["Error"] = 0] = "Error";
+    /**
+     * Warning - the document may have issues but is usable.
+     */
+    CtlValidationSeverity[CtlValidationSeverity["Warning"] = 1] = "Warning";
+    /**
+     * Information - advisory message.
+     */
+    CtlValidationSeverity[CtlValidationSeverity["Info"] = 2] = "Info";
+})(CtlValidationSeverity || (CtlValidationSeverity = {}));

package/dist/ctl/models/types.d.ts

@@ -0,0 +1,169 @@
+import { CtlValidationErrorType, CtlValidationSeverity } from '../../ctl/models/enums';
+import { CtlCanonUri } from '../../ctl/parsing/types';
+import { CanonMetadata } from '../../document/models/types';
+import { SubjectCanon } from '../../object/canons/types';
+/**
+ * Represents a reference to a Canon entity found in a CTL document.     Corresponds to a markdown link: [DisplayText](canon://...)
+ */
+export interface CanonReference {
+    /**
+     * The display text shown to the user (the link text).     Example: "Agent" in [Agent](canon://mycompany.com/models@1.0.0/Agent)
+     */
+    displayText: string;
+    /**
+     * The raw Canon URI string from the markdown link.     Example: "canon://mycompany.com/models@1.0.0/Agent"
+     */
+    rawUri: string;
+    /**
+     * The parsed Canon URI. Null if the URI failed to parse.
+     */
+    parsedUri?: CtlCanonUri | null | undefined;
+    /**
+     * The character offset where this reference starts in the source markdown.
+     */
+    startOffset: number;
+    /**
+     * The character offset where this reference ends in the source markdown.
+     */
+    endOffset: number;
+    /**
+     * The line number (1-based) where this reference appears.
+     */
+    line: number;
+    /**
+     * The column number (1-based) where this reference starts.
+     */
+    column: number;
+    /**
+     * Whether this reference has been successfully resolved.
+     */
+    isResolved: boolean;
+    /**
+     * The resolved entity (for entity-level URIs). Null if not resolved or not an entity URI.
+     */
+    resolvedResource?: SubjectCanon | null | undefined;
+    /**
+     * The resolved value for deep link URIs (could be a scalar, EmbeddedCanon, etc.).     Null if not resolved or not a deep link URI.
+     */
+    resolvedValue?: any | null | undefined;
+    /**
+     * Error message if parsing or resolution failed.
+     */
+    error?: string | null | undefined;
+    /**
+     * The full markdown link text: [DisplayText](RawUri)
+     */
+    readonly fullMarkdownLink: string;
+}
+/**
+ * Represents a parsed CTL document (markdown with embedded Canon URI references).     Supports two modes:     - CTL Inline: No frontmatter, full canon:// URIs (for chat/responses)     - CTL Document: Canon YAML frontmatter with import aliases (for templates)
+ */
+export interface CtlDocument {
+    /**
+     * Canon metadata from YAML frontmatter (if present).     Contains publisher/package/version and imports with aliases.     Null for CTL Inline mode (no frontmatter).
+     */
+    metadata?: CanonMetadata | null | undefined;
+    /**
+     * Whether this document has Canon frontmatter (CTL Document mode).
+     */
+    readonly hasFrontmatter: boolean;
+    /**
+     * The raw markdown content of the document (body only, without frontmatter).
+     */
+    rawMarkdown: string;
+    /**
+     * The length of the frontmatter section (including delimiters).     Used to calculate reference positions within the body.     Zero if no frontmatter.
+     */
+    frontmatterLength: number;
+    /**
+     * The file path of the document, if loaded from a file.
+     */
+    filePath?: string | null | undefined;
+    /**
+     * All Canon references found in the document.     URIs are fully resolved (alias links expanded to full canon:// URIs).
+     */
+    references: readonly CanonReference[];
+    /**
+     * The number of references in the document.
+     */
+    readonly referenceCount: number;
+    /**
+     * Whether all references have been resolved successfully.
+     */
+    readonly allReferencesResolved: boolean;
+    /**
+     * References that failed to resolve.
+     */
+    readonly unresolvedReferences: Array<CanonReference>;
+    /**
+     * References that have errors (parsing or resolution).
+     */
+    readonly errorReferences: Array<CanonReference>;
+}
+/**
+ * A validation error or warning for a CTL document.
+ */
+export interface CtlValidationError {
+    /**
+     * The type of validation error.
+     */
+    errorType: CtlValidationErrorType;
+    /**
+     * The severity of the error.
+     */
+    severity: CtlValidationSeverity;
+    /**
+     * Human-readable error message.
+     */
+    message: string;
+    /**
+     * The reference that caused the error, if applicable.
+     */
+    reference?: CanonReference | null | undefined;
+    /**
+     * Line number (1-based) where the error occurred.
+     */
+    line?: number | null | undefined;
+    /**
+     * Column number (1-based) where the error occurred.
+     */
+    column?: number | null | undefined;
+    /**
+     * Suggestion for how to fix the error.
+     */
+    suggestion?: string | null | undefined;
+    toString(): string;
+}
+/**
+ * The result of validating a CTL document.
+ */
+export interface CtlValidationResult {
+    /**
+     * Whether the document is valid (all references resolved).
+     */
+    isValid: boolean;
+    /**
+     * The validated CTL document.
+     */
+    document: CtlDocument;
+    /**
+     * Validation errors (unresolved references, parse errors, etc.).
+     */
+    errors: readonly CtlValidationError[];
+    /**
+     * Validation warnings (non-fatal issues).
+     */
+    warnings: readonly CtlValidationError[];
+    /**
+     * Total number of references in the document.
+     */
+    readonly totalReferences: number;
+    /**
+     * Number of successfully resolved references.
+     */
+    readonly resolvedReferences: number;
+    /**
+     * Summary string for display.
+     */
+    readonly summary: string;
+}

package/dist/ctl/models/types.js

@@ -0,0 +1,5 @@
+// This file was auto-generated by Canon SDK Transpiler v1.0.0
+// Source: 3 files in namespace
+// SourceHash: sha256-12c678245e1b30c4b2e7489e0afa36916b4a46f4a697b9d93aace92ed0f974a1
+// DO NOT EDIT - changes will be overwritten
+export {};

package/dist/ctl/parsing/enums.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The type of Canon URI supported in CTL.     CTL only supports resource-level references (not package or publisher).
+ */
+export declare enum CtlCanonUriType {
+    /**
+     * Publisher-level URI: canon://publisher     NOTE: Not supported in CTL - will throw during parsing.
+     */
+    Publisher = 0,
+    /**
+     * Package-level URI without version: canon://publisher/package     NOTE: Not supported in CTL - will throw during parsing.
+     */
+    Package = 1,
+    /**
+     * Package-level URI with version: canon://publisher/package@version     NOTE: Not supported in CTL - will throw during parsing.
+     */
+    VersionedPackage = 2,
+    /**
+     * Resource-level URI: canon://publisher/package[@version]/resource
+     */
+    Resource = 3,
+    /**
+     * Deep link URI with path: canon://publisher/package[@version]/resource#path.to[0].field
+     */
+    DeepLink = 4
+}
+/**
+ * The type of a path segment.
+ */
+export declare enum PathSegmentType {
+    /**
+     * A property access: .propertyName
+     */
+    Property = 0,
+    /**
+     * An array index access: [0]
+     */
+    Index = 1
+}

package/dist/ctl/parsing/enums.js

@@ -0,0 +1,44 @@
+// This file was auto-generated by Canon SDK Transpiler v1.0.0
+// Source: canon-sdk-csharp\Canon.CTL\Parsing\CtlCanonUri.cs
+// SourceHash: sha256-ba23d35173efc106f00ee6850fb7586ca9335de6df38859ad1b065bc20fcb0e3
+// DO NOT EDIT - changes will be overwritten
+/**
+ * The type of Canon URI supported in CTL.     CTL only supports resource-level references (not package or publisher).
+ */
+export var CtlCanonUriType;
+(function (CtlCanonUriType) {
+    /**
+     * Publisher-level URI: canon://publisher     NOTE: Not supported in CTL - will throw during parsing.
+     */
+    CtlCanonUriType[CtlCanonUriType["Publisher"] = 0] = "Publisher";
+    /**
+     * Package-level URI without version: canon://publisher/package     NOTE: Not supported in CTL - will throw during parsing.
+     */
+    CtlCanonUriType[CtlCanonUriType["Package"] = 1] = "Package";
+    /**
+     * Package-level URI with version: canon://publisher/package@version     NOTE: Not supported in CTL - will throw during parsing.
+     */
+    CtlCanonUriType[CtlCanonUriType["VersionedPackage"] = 2] = "VersionedPackage";
+    /**
+     * Resource-level URI: canon://publisher/package[@version]/resource
+     */
+    CtlCanonUriType[CtlCanonUriType["Resource"] = 3] = "Resource";
+    /**
+     * Deep link URI with path: canon://publisher/package[@version]/resource#path.to[0].field
+     */
+    CtlCanonUriType[CtlCanonUriType["DeepLink"] = 4] = "DeepLink";
+})(CtlCanonUriType || (CtlCanonUriType = {}));
+/**
+ * The type of a path segment.
+ */
+export var PathSegmentType;
+(function (PathSegmentType) {
+    /**
+     * A property access: .propertyName
+     */
+    PathSegmentType[PathSegmentType["Property"] = 0] = "Property";
+    /**
+     * An array index access: [0]
+     */
+    PathSegmentType[PathSegmentType["Index"] = 1] = "Index";
+})(PathSegmentType || (PathSegmentType = {}));

package/dist/ctl/parsing/types.d.ts

@@ -0,0 +1,89 @@
+import { CtlDocument } from '../../ctl/models/types';
+import { CtlCanonUriType, PathSegmentType } from '../../ctl/parsing/enums';
+import { Version } from '../../document/models/types';
+/**
+ * Represents a Canon URI used in CTL documents.     CTL supports resource-level references with optional deep linking:     - Resource: canon://publisher/package@version/resource     - Resource (latest): canon://publisher/package/resource     - Deep Link: canon://publisher/package@version/resource#path.to[0].field        Package and publisher-level URIs are NOT supported in CTL.     Use full resource URIs (canon://) or short URIs (can://) resolved via imports.
+ */
+export interface CtlCanonUri {
+    /**
+     * The URI scheme (always "canon").
+     */
+    readonly scheme: string;
+    /**
+     * The publisher/organization (e.g., "mycompany.com").
+     */
+    publisher: string;
+    /**
+     * The package name (e.g., "models"). Null for publisher-only URIs.
+     */
+    package_?: string | null | undefined;
+    /**
+     * The semantic version (e.g., "1.0.0"). Null for latest version.
+     */
+    version?: Version | null | undefined;
+    /**
+     * The resource name (e.g., "Agent"). Null for package-level URIs.
+     */
+    resourceName?: string | null | undefined;
+    /**
+     * The deep link path segments (e.g., ["address", "city"] or ["skills", "[0]", "name"]).     Empty for resource-level URIs without deep linking.
+     */
+    path: readonly PathSegment[];
+    /**
+     * The type of this URI based on its specificity.
+     */
+    readonly uriType: CtlCanonUriType;
+    /**
+     * Returns the namespace string (publisher/package[@version]) if applicable.
+     */
+    readonly namespace_?: string | null | undefined;
+    /**
+     * The original raw URI string.
+     */
+    rawUri: string;
+    /**
+     * Converts the URI to its canonical string representation.
+     */
+    toString(): string;
+    equals(obj: any | null): boolean;
+    getHashCode(): number;
+}
+/**
+ * Parses CTL documents (markdown with embedded Canon URI references).     Supports two modes:     - CTL Inline: No frontmatter, full canon:// URIs (for chat/responses)     - CTL Document: Canon YAML frontmatter with import aliases (for templates)
+ */
+export interface CtlParser {
+    /**
+     * Parses a CTL markdown string into a CtlDocument.     Auto-detects mode based on frontmatter presence.
+     */
+    parse(content: string, filePath?: string | null): CtlDocument;
+    /**
+     * Parses a CTL document from a file.
+     */
+    parseFileAsync(filePath: string): Promise<CtlDocument>;
+}
+/**
+ * A segment in a deep link path.
+ */
+export interface PathSegment {
+    /**
+     * The type of path segment.
+     */
+    type_: PathSegmentType;
+    /**
+     * The property name (for Property segments).
+     */
+    name?: string | null | undefined;
+    /**
+     * The array index (for Index segments).
+     */
+    index?: number | null | undefined;
+    toString(): string;
+}
+/**
+ * Represents a resolved import with publisher, package, and version.
+ */
+export interface ResolvedImport {
+    publisher: string;
+    package_: string;
+    version: Version;
+}

package/dist/ctl/parsing/types.js

@@ -0,0 +1,5 @@
+// This file was auto-generated by Canon SDK Transpiler v1.0.0
+// Source: 2 files in namespace
+// SourceHash: sha256-7b237096a44f2de3fb82b6b6465eade55208cdeb86fba18475ae10c2842962fb
+// DO NOT EDIT - changes will be overwritten
+export {};

package/dist/ctl/rendering/types.d.ts

@@ -0,0 +1,39 @@
+import { CtlDocument, CtlValidationResult } from '../../ctl/models/types';
+/**
+ * Renders CTL documents in various formats.     - Preview: Human-readable view with Canon references shown as display text     - Source: Original markdown (useful for display with syntax highlighting)
+ */
+export interface CtlPreviewRenderer {
+    /**
+     * Renders a CTL document as a preview (Canon links replaced with display text).
+     */
+    renderPreview(document: CtlDocument, options?: CtlRenderOptions | null): string;
+    /**
+     * Renders a CTL document as a summary showing all references.
+     */
+    renderReferenceSummary(document: CtlDocument): string;
+    /**
+     * Renders validation errors in a human-readable format.
+     */
+    renderValidationErrors(result: CtlValidationResult): string;
+    /**
+     * Exports a CTL document as JSON with resolved reference information.
+     */
+    exportAsJson(document: CtlDocument): string;
+}
+/**
+ * Options for rendering CTL documents.
+ */
+export interface CtlRenderOptions {
+    /**
+     * Whether to indicate Canon references with markers.
+     */
+    indicateReferences: boolean;
+    /**
+     * Marker format for resolved references. Use {text} as placeholder.     Default: "«{text}»"
+     */
+    resolvedMarker?: string | null | undefined;
+    /**
+     * Marker format for unresolved references. Use {text} as placeholder.     Default: "⚠{text}⚠"
+     */
+    unresolvedMarker?: string | null | undefined;
+}

package/dist/ctl/rendering/types.js

@@ -0,0 +1,5 @@
+// This file was auto-generated by Canon SDK Transpiler v1.0.0
+// Source: canon-sdk-csharp\Canon.CTL\Rendering\CtlPreviewRenderer.cs
+// SourceHash: sha256-fb0110494c5d79eb0a011bbb139a228b9e5d22175d0fdbb7b6f897790737c1b8
+// DO NOT EDIT - changes will be overwritten
+export {};

package/dist/ctl/resolution/enums.d.ts

@@ -0,0 +1,34 @@
+export declare enum EntityTier {
+    Direct = 0,
+    Inherited = 1,
+    Foundation = 2
+}
+/**
+ * Semantic type classification for resolved entities.
+ */
+export declare enum ResolvedResourceType {
+    /**
+     * An rdfs:Class or owl:Class definition.
+     */
+    Class = 0,
+    /**
+     * An owl:AnnotationProperty definition.
+     */
+    AnnotationProperty = 1,
+    /**
+     * An owl:DatatypeProperty definition.
+     */
+    DatatypeProperty = 2,
+    /**
+     * An owl:ObjectProperty definition.
+     */
+    ObjectProperty = 3,
+    /**
+     * An instance of a class (not a schema definition).
+     */
+    Instance = 4,
+    /**
+     * Unknown or unclassifiable entity type.
+     */
+    Other = 5
+}

package/dist/ctl/resolution/enums.js

@@ -0,0 +1,40 @@
+// This file was auto-generated by Canon SDK Transpiler v1.0.0
+// Source: 2 files in namespace
+// SourceHash: sha256-e8d0e7bd29c93f972dd742211e808362e50f44937f3ac3f58183c4e80ff1d915
+// DO NOT EDIT - changes will be overwritten
+export var EntityTier;
+(function (EntityTier) {
+    EntityTier[EntityTier["Direct"] = 0] = "Direct";
+    EntityTier[EntityTier["Inherited"] = 1] = "Inherited";
+    EntityTier[EntityTier["Foundation"] = 2] = "Foundation";
+})(EntityTier || (EntityTier = {}));
+/**
+ * Semantic type classification for resolved entities.
+ */
+export var ResolvedResourceType;
+(function (ResolvedResourceType) {
+    /**
+     * An rdfs:Class or owl:Class definition.
+     */
+    ResolvedResourceType[ResolvedResourceType["Class"] = 0] = "Class";
+    /**
+     * An owl:AnnotationProperty definition.
+     */
+    ResolvedResourceType[ResolvedResourceType["AnnotationProperty"] = 1] = "AnnotationProperty";
+    /**
+     * An owl:DatatypeProperty definition.
+     */
+    ResolvedResourceType[ResolvedResourceType["DatatypeProperty"] = 2] = "DatatypeProperty";
+    /**
+     * An owl:ObjectProperty definition.
+     */
+    ResolvedResourceType[ResolvedResourceType["ObjectProperty"] = 3] = "ObjectProperty";
+    /**
+     * An instance of a class (not a schema definition).
+     */
+    ResolvedResourceType[ResolvedResourceType["Instance"] = 4] = "Instance";
+    /**
+     * Unknown or unclassifiable entity type.
+     */
+    ResolvedResourceType[ResolvedResourceType["Other"] = 5] = "Other";
+})(ResolvedResourceType || (ResolvedResourceType = {}));