@hypit/hypit 0.0.1 → 0.1.0

package/dist/public/speech.d.ts

@@ -0,0 +1,391 @@
+/** Opaque identity for one admitted byte resource. Equal bytes may have different identities. */
+type ResourceId = `res_${string}`;
+type RecordId = string;
+type StepId = string;
+type CommandId = string;
+type ModuleRef = {
+    readonly name: string;
+    readonly version: string;
+};
+/**
+ * A Type is its owning Module and its name, and nothing else is compared. Two Types whose values
+ * carry identical shapes are distinct, so one is refused where the other is declared — there is no
+ * structural fallback to fall back to.
+ */
+type TypeRef = {
+    readonly module: ModuleRef;
+    readonly name: string;
+};
+type ProducerRef = {
+    readonly module: ModuleRef;
+    readonly name: string;
+};
+type CapabilityRef = {
+    readonly module: ModuleRef;
+    readonly name: string;
+};
+
+type CanonicalValue = null | boolean | number | string | readonly CanonicalValue[] | {
+    readonly [key: string]: CanonicalValue;
+};
+type BlobRef = {
+    readonly kind: "blob";
+    /** One admitted resource instance. Equal bytes admitted twice keep distinct identities. */
+    readonly resource: ResourceId;
+    readonly size: number;
+    readonly mediaType: string;
+};
+type StoredValue = {
+    readonly kind: "inline";
+    readonly value: CanonicalValue;
+} | BlobRef;
+type ValueSchema = {
+    readonly kind: "null";
+} | {
+    readonly kind: "boolean";
+} | {
+    readonly kind: "number";
+    readonly integer?: boolean;
+    readonly minimum?: number;
+    readonly maximum?: number;
+} | {
+    readonly kind: "string";
+    readonly enum?: readonly string[];
+    readonly minLength?: number;
+    readonly maxLength?: number;
+    /** UI-neutral semantic format shared by authoring, validation and tools. */
+    readonly format?: "color";
+} | {
+    readonly kind: "literal";
+    readonly value: CanonicalValue;
+} | {
+    readonly kind: "array";
+    readonly items: ValueSchema;
+    readonly minItems?: number;
+    readonly maxItems?: number;
+} | {
+    readonly kind: "object";
+    readonly fields: Readonly<Record<string, ObjectFieldSchema>>;
+    readonly allowUnknown?: boolean;
+} | {
+    readonly kind: "oneOf";
+    readonly variants: readonly ValueSchema[];
+} | {
+    readonly kind: "blob";
+    readonly mediaTypes?: readonly string[];
+    readonly maxBytes?: number;
+};
+type ObjectFieldSchema = {
+    readonly schema: ValueSchema;
+    readonly optional?: boolean;
+};
+
+type ModuleDependency = {
+    readonly module: ModuleRef;
+};
+type TypeDeclaration = {
+    readonly name: string;
+};
+type PortDeclaration = {
+    readonly name: string;
+    readonly type: TypeRef;
+};
+type NeedPortDeclaration = {
+    readonly name: string;
+    readonly capability: CapabilityRef;
+    readonly returns: TypeRef;
+};
+type CapabilityDeclaration = {
+    readonly name: string;
+    readonly returns: TypeRef;
+};
+type ProducerDeclaration = {
+    readonly name: string;
+    readonly inputs: readonly PortDeclaration[];
+    readonly outputs: readonly PortDeclaration[];
+    readonly needs: readonly NeedPortDeclaration[];
+};
+type ModuleManifest = {
+    readonly format: "hypit.module@1";
+    readonly name: string;
+    readonly version: string;
+    readonly dependencies: readonly ModuleDependency[];
+    readonly types: readonly TypeDeclaration[];
+    readonly capabilities: readonly CapabilityDeclaration[];
+    readonly producers: readonly ProducerDeclaration[];
+};
+
+/** One typed value in the graph; semantic validation happens at the Host admission boundary. */
+type TypedRecord = {
+    readonly id: RecordId;
+    readonly type: TypeRef;
+    readonly value: StoredValue;
+};
+type InvokeProducerCommand = {
+    readonly kind: "invoke-producer";
+    readonly id: CommandId;
+    readonly step: StepId;
+    readonly producer: ProducerRef;
+    readonly inputs: Readonly<Record<string, RecordId>>;
+};
+
+type TypeValidatorContext = {
+    readonly type: TypeRef;
+    readonly value: StoredValue;
+};
+/**
+ * Pure compute context. Artifact bytes, credentials, network and stores are deliberately absent;
+ * those effects must cross an explicit Need into a Provider.
+ */
+type ProducerHandlerContext = {
+    readonly command: InvokeProducerCommand;
+    readonly producer: ProducerRef;
+    readonly inputs: Readonly<Record<string, TypedRecord>>;
+};
+
+type MediaRational = {
+    readonly numerator: number;
+    readonly denominator: number;
+};
+type SynchronizedMedia = {
+    readonly timeline: {
+        readonly frameRate: MediaRational;
+        readonly frameCount: number;
+    };
+    readonly visual?: {
+        readonly artifact: BlobRef;
+        readonly width: number;
+        readonly height: number;
+    };
+    readonly audio?: {
+        readonly artifact: BlobRef;
+    };
+};
+
+/** Positive seconds. The graph port's TypeRef already carries the SpeechDuration identity. */
+type SpeechDuration = number;
+type SpeechEvidenceAudio = {
+    readonly artifact: BlobRef;
+    /** Exact 16 kHz mono PCM sample count. Format constants belong to this Type, not every value. */
+    readonly sampleFrames: number;
+};
+/** One authored Script token located in one normalized Take's local frame domain. */
+type SemanticTakeToken = {
+    readonly tokenId: string;
+    readonly segmentId: string;
+    readonly text: string;
+    readonly startAnchorId: string;
+    readonly endAnchorId: string;
+    readonly startFrame: number;
+    readonly endFrameExclusive: number;
+};
+/**
+ * A self-contained semantic media product. Media bytes remain ordinary BlobRefs
+ * inside SynchronizedMedia; the authored word surface and its local frame
+ * coordinates travel with this Take instead of requiring a second Script edge.
+ */
+type SemanticTake = {
+    /** Author-visible Script identity carried through every semantic projection. */
+    readonly narrativeId: string;
+    readonly media: SynchronizedMedia;
+    readonly segment: {
+        readonly segmentId: string;
+        readonly startAnchorId: string;
+        readonly endAnchorId: string;
+        readonly startFrame: number;
+        readonly endFrameExclusive: number;
+    };
+    readonly tokens: readonly SemanticTakeToken[];
+    readonly anchors: readonly {
+        readonly identity: string;
+        readonly frame: number;
+    }[];
+};
+/** One authored Token located in a Segment-local frame domain. */
+type SemanticTakeTimedToken = {
+    readonly tokenId: string;
+    readonly segmentId: string;
+    readonly startFrame: number;
+    readonly endFrameExclusive: number;
+};
+/** Provider measurement and preview estimation both materialize through this narrow timing waist. */
+type SemanticTakeTiming = {
+    readonly tokens: readonly SemanticTakeTimedToken[];
+    readonly anchors: readonly {
+        readonly identity: string;
+        readonly frame: number;
+    }[];
+};
+
+declare function sealSpeechDuration(value: SpeechDuration): SpeechDuration;
+declare function assertSpeechDurationIdentity(value: SpeechDuration): void;
+declare function speechEvidenceSampleBoundary(masterSampleBoundary: number): number;
+declare function sealSpeechEvidenceAudio(value: SpeechEvidenceAudio): SpeechEvidenceAudio;
+declare function sealSemanticTake(value: SemanticTake): SemanticTake;
+declare function assertSemanticTakeIdentity(take: SemanticTake): void;
+declare function assertSpeechEvidenceAudioIdentity(value: SpeechEvidenceAudio): void;
+
+declare const speechComponent: {
+    validators: {
+        type: {
+            module: {
+                readonly name: "@hypit/speech";
+                readonly version: "1";
+            };
+            name: string;
+        };
+        handler: ({ value }: TypeValidatorContext) => void;
+    }[];
+    producers: {
+        producer: {
+            module: {
+                readonly name: "@hypit/speech";
+                readonly version: "1";
+            };
+            name: string;
+        };
+        handler: ({ inputs }: ProducerHandlerContext) => {
+            outputs: {
+                take: {
+                    kind: "inline";
+                    value: CanonicalValue;
+                };
+            };
+            needs: {};
+        };
+    }[];
+};
+
+type NarrativeSegment = {
+    readonly id: string;
+    readonly startAnchorId: string;
+    readonly endAnchorId: string;
+    readonly tokenStart: number;
+    readonly tokenEndExclusive: number;
+};
+type NarrativeToken = {
+    readonly id: string;
+    readonly segmentId: string;
+    readonly startAnchorId: string;
+    readonly endAnchorId: string;
+    readonly text: string;
+    readonly normalized: string;
+};
+type NarrativeTurn = {
+    readonly id: string;
+    readonly segmentId: string;
+    readonly role?: string;
+    readonly tokenStart: number;
+    readonly tokenEndExclusive: number;
+};
+type NarrativeSelection = {
+    readonly id: string;
+    /** The exact semantic anchors chosen by the author Surface's affinity syntax. */
+    readonly startAnchorId: string;
+    readonly endAnchorId: string;
+};
+type NarrativeMoment = {
+    readonly id: string;
+    /** The exact semantic anchor chosen by the author Surface's affinity syntax. */
+    readonly anchorId: string;
+};
+type SemanticAnchor = {
+    readonly id: "program:start";
+    readonly kind: "program-start";
+    readonly segmentId?: never;
+    readonly tokenId?: never;
+} | {
+    readonly id: "program:end";
+    readonly kind: "program-end";
+    readonly segmentId?: never;
+    readonly tokenId?: never;
+} | {
+    readonly id: string;
+    readonly kind: "segment-start" | "token-start" | "token-end" | "segment-end";
+    readonly segmentId: string;
+    readonly tokenId?: string;
+};
+type Narrative = {
+    /** Author-visible `<script id>`; every exported semantic view retains it. */
+    readonly id: string;
+    readonly segments: readonly NarrativeSegment[];
+    readonly tokens: readonly NarrativeToken[];
+    readonly turns: readonly NarrativeTurn[];
+    readonly selections: readonly NarrativeSelection[];
+    readonly moments: readonly NarrativeMoment[];
+    readonly semanticIndex: {
+        readonly anchors: readonly SemanticAnchor[];
+    };
+};
+/**
+ * One author-selected contiguous excerpt. Script is one possible producer;
+ * generation and speech packages consume this shared value without importing
+ * Script's parser or source representation.
+ */
+type NarrativeExcerpt = {
+    readonly kind: "segment";
+    /** Author-visible `<script id>` that owns this Segment. */
+    readonly narrativeId: string;
+    readonly id: string;
+    readonly tokenStart: number;
+    readonly tokenEndExclusive: number;
+};
+
+/**
+ * Copy one Segment-local timing result into a self-contained semantic Take.
+ * How the timing was obtained remains the caller's explicit package meaning.
+ */
+declare function materializeSemanticTake(narrative: Narrative, excerpt: NarrativeExcerpt, media: SynchronizedMedia, timing: SemanticTakeTiming): SemanticTake;
+/** Materialize the exact media boundaries of an authored Segment that contains no Tokens. */
+declare function materializeSegmentBoundaryTake(narrative: Narrative, excerpt: NarrativeExcerpt, media: SynchronizedMedia): SemanticTake;
+
+declare const speechModuleRef: {
+    readonly name: "@hypit/speech";
+    readonly version: "1";
+};
+declare const speechTypes: {
+    duration: {
+        module: {
+            readonly name: "@hypit/speech";
+            readonly version: "1";
+        };
+        name: string;
+    };
+    evidenceAudio: {
+        module: {
+            readonly name: "@hypit/speech";
+            readonly version: "1";
+        };
+        name: string;
+    };
+    semanticTake: {
+        module: {
+            readonly name: "@hypit/speech";
+            readonly version: "1";
+        };
+        name: string;
+    };
+};
+declare const speechProducers: {
+    materializeSegmentBoundaries: {
+        module: {
+            readonly name: "@hypit/speech";
+            readonly version: "1";
+        };
+        name: string;
+    };
+};
+declare const speechManifest: ModuleManifest;
+declare const speechDependency: {
+    readonly module: {
+        readonly name: "@hypit/speech";
+        readonly version: "1";
+    };
+};
+
+declare const speechDurationSchema: ValueSchema;
+declare const speechEvidenceAudioSchema: ValueSchema;
+declare const semanticTakeSchema: ValueSchema;
+
+export { assertSemanticTakeIdentity, assertSpeechDurationIdentity, assertSpeechEvidenceAudioIdentity, materializeSegmentBoundaryTake, materializeSemanticTake, sealSemanticTake, sealSpeechDuration, sealSpeechEvidenceAudio, semanticTakeSchema, speechComponent, speechDependency, speechDurationSchema, speechEvidenceAudioSchema, speechEvidenceSampleBoundary, speechManifest, speechModuleRef, speechProducers, speechTypes };
+export type { SemanticTake, SemanticTakeTimedToken, SemanticTakeTiming, SemanticTakeToken, SpeechDuration, SpeechEvidenceAudio };