@hypit/hypit 0.0.1 → 0.1.0

package/dist/public/temporal.d.ts

@@ -0,0 +1,497 @@
+/** Opaque identity for one admitted byte resource. Equal bytes may have different identities. */
+type ResourceId = `res_${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 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 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[];
+};
+
+type NarrativeSelection = {
+    readonly id: string;
+    /** The exact semantic anchors chosen by the author Surface's affinity syntax. */
+    readonly startAnchorId: string;
+    readonly endAnchorId: string;
+};
+/** One explicitly authored semantic window, independently referenceable by graph edges. */
+type NarrativeSelectionRef = NarrativeSelection & {
+    /** Author-visible `<script id>` that owns this independently exported Selection. */
+    readonly narrativeId: string;
+};
+type NarrativeMoment = {
+    readonly id: string;
+    /** The exact semantic anchor chosen by the author Surface's affinity syntax. */
+    readonly anchorId: string;
+};
+/** One explicitly authored semantic instant, independently referenceable by graph edges. */
+type NarrativeMomentRef = NarrativeMoment & {
+    /** Author-visible `<script id>` that owns this independently exported Moment. */
+    readonly narrativeId: string;
+};
+/**
+ * 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;
+};
+
+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;
+    };
+};
+
+/** 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;
+    }[];
+};
+
+type SemanticTrackItem = {
+    readonly take: SemanticTake;
+};
+/**
+ * The continuous program skeleton. Every item is a real SemanticTake and the
+ * global frame domain is exactly their prefix sum: no gap or empty item exists.
+ */
+type SemanticTrack = {
+    readonly id: string;
+    readonly narrativeId: string;
+    readonly items: readonly SemanticTrackItem[];
+};
+
+type ProgramSpace = {
+    /** Author-visible identity of this film time axis. */
+    readonly id: string;
+    readonly durationSec: number;
+    readonly frameRate: {
+        readonly numerator: number;
+        readonly denominator: number;
+    };
+};
+
+type FramePoint = {
+    readonly frame: number;
+};
+type LocatedSelection = {
+    readonly id: string;
+    readonly start: FramePoint;
+    readonly end: FramePoint;
+};
+type LocatedMoment = {
+    readonly id: string;
+    readonly cue: FramePoint;
+};
+type LocatedProgram = {
+    readonly id: "program";
+    readonly start: FramePoint;
+    readonly end: FramePoint;
+};
+type LocatedSegment = {
+    readonly id: string;
+    readonly start: FramePoint;
+    readonly end: FramePoint;
+};
+/** Exact author duration. Decimal source spelling is reduced before reaching this value. */
+type TemporalDuration = {
+    readonly unit: "frames";
+    readonly value: number;
+} | {
+    readonly unit: "milliseconds";
+    readonly value: number;
+} | {
+    readonly unit: "seconds";
+    readonly numerator: number;
+    readonly denominator: number;
+};
+/** A single projected boundary before it is resolved into ProgramSpace. */
+type TemporalInstantExpression = {
+    readonly ref: "program.start";
+    readonly offset?: TemporalDuration;
+} | {
+    readonly ref: "program.end";
+    readonly offset?: TemporalDuration;
+} | {
+    readonly ref: "selection.start";
+    readonly offset?: TemporalDuration;
+} | {
+    readonly ref: "selection.end";
+    readonly offset?: TemporalDuration;
+} | {
+    readonly ref: "segment.start";
+    readonly offset?: TemporalDuration;
+} | {
+    readonly ref: "segment.end";
+    readonly offset?: TemporalDuration;
+} | {
+    readonly ref: "moment.cue";
+    readonly offset?: TemporalDuration;
+} | {
+    readonly ref: "absolute";
+    readonly at: TemporalDuration;
+    readonly offset?: TemporalDuration;
+};
+/** Runtime dependency used to resolve an Instant. This is not its authoring authority. */
+type TemporalSource = {
+    readonly spaceId: string;
+    /** Present when the boundary originates in a Script. */
+    readonly narrativeId?: string;
+    readonly kind: "program" | "selection" | "segment" | "moment";
+    readonly id: string;
+};
+/**
+ * The author-owned inverse of one projected Instant. Runtime dependencies and
+ * author authority are deliberately separate: an expression may read an
+ * anchor while remaining writable only at its author parameter.
+ */
+type TemporalInstantAuthority = {
+    readonly kind: "semantic";
+    readonly boundary: "start" | "end" | "cue";
+} | {
+    readonly kind: "parameter";
+    readonly binding: string;
+    readonly relation: "direct" | "after-start" | "before-end";
+} | {
+    readonly kind: "fixed";
+};
+/** Input value for an Instant projection producer. */
+type TemporalInstantSpec = {
+    readonly id: string;
+    /** Author/domain entity whose timing this projection controls. */
+    readonly subjectId: string;
+    readonly projection: TemporalInstantExpression;
+    readonly authority: TemporalInstantAuthority;
+};
+/** Input value for composing two resolved Instants into a Window. */
+type TemporalWindowSpec = {
+    readonly id: string;
+    /** Author/domain entity whose timing this projection controls. */
+    readonly subjectId: string;
+};
+type FrameSpan = {
+    readonly startFrame: number;
+    readonly endFrameExclusive: number;
+};
+type ProjectedInstant = {
+    readonly id: string;
+    readonly subjectId: string;
+    readonly source: TemporalSource;
+    readonly projection: TemporalInstantExpression;
+    readonly authority: TemporalInstantAuthority;
+    readonly frame: number;
+};
+type ProjectedWindow = {
+    readonly id: string;
+    readonly subjectId: string;
+    readonly start: ProjectedInstant;
+    readonly end: ProjectedInstant;
+    readonly span: FrameSpan;
+};
+/** Public projection protocol consumed by domain programs. */
+type TemporalInstant = ProjectedInstant;
+/** Public projection protocol composed from two independently traced Instants. */
+type TemporalWindow = ProjectedWindow;
+type WindowRelation = "independent" | "disjoint";
+type TriggerPoint = {
+    readonly id: string;
+    readonly frame: number;
+};
+type TriggeredSchedule = {
+    readonly outer: FrameSpan;
+    readonly terminalFrame: number;
+    readonly cumulative: readonly FrameSpan[];
+    readonly exclusive: readonly FrameSpan[];
+};
+
+declare function locateSelection(semantic: SemanticTrack, selection: NarrativeSelectionRef): LocatedSelection;
+declare function locateMoment(semantic: SemanticTrack, moment: NarrativeMomentRef): LocatedMoment;
+declare function locateProgram(semantic: SemanticTrack): LocatedProgram;
+declare function locateSegment(semantic: SemanticTrack, segment: NarrativeExcerpt): LocatedSegment;
+
+type TemporalConsumption = {
+    readonly subjectId: string;
+    readonly space?: ProgramSpace;
+};
+/** Verify the public identity carried across a Temporal consumer boundary. */
+declare function assertTemporalInstantFor(instant: TemporalInstant, expected: TemporalConsumption): void;
+/** Verify both endpoint provenance and the materialized span consumed by a domain program. */
+declare function assertTemporalWindowFor(window: TemporalWindow, expected: TemporalConsumption): void;
+type InstantEnvironment = {
+    readonly program: LocatedProgram;
+    readonly selection?: LocatedSelection;
+    readonly moment?: LocatedMoment;
+    readonly segment?: LocatedSegment;
+};
+declare function projectTemporalInstant(projection: TemporalInstantExpression, environment: InstantEnvironment, space: ProgramSpace): number;
+declare function projectSelectionInstant(input: {
+    readonly itemId: string;
+    readonly subjectId: string;
+    readonly semantic: SemanticTrack;
+    readonly selection: NarrativeSelectionRef;
+    readonly projection: TemporalInstantExpression;
+    readonly authority: TemporalInstantSpec["authority"];
+}): ProjectedInstant;
+declare function projectMomentInstant(input: {
+    readonly itemId: string;
+    readonly subjectId: string;
+    readonly semantic: SemanticTrack;
+    readonly moment: NarrativeMomentRef;
+    readonly projection: TemporalInstantExpression;
+    readonly authority: TemporalInstantSpec["authority"];
+}): ProjectedInstant;
+declare function projectProgramInstant(input: {
+    readonly itemId: string;
+    readonly subjectId: string;
+    readonly space: ProgramSpace;
+    readonly projection: TemporalInstantExpression;
+    readonly authority: TemporalInstantSpec["authority"];
+}): ProjectedInstant;
+declare function projectSegmentInstant(input: {
+    readonly itemId: string;
+    readonly subjectId: string;
+    readonly semantic: SemanticTrack;
+    readonly segment: NarrativeExcerpt;
+    readonly projection: TemporalInstantExpression;
+    readonly authority: TemporalInstantSpec["authority"];
+}): ProjectedInstant;
+declare function composeTemporalWindow(spec: TemporalWindowSpec, start: ProjectedInstant, end: ProjectedInstant): ProjectedWindow;
+declare function assertWindowRelation(windows: readonly ProjectedWindow[], relation: WindowRelation): readonly ProjectedWindow[];
+
+declare function resolveTriggeredSchedule(input: {
+    readonly outer: FrameSpan;
+    readonly terminalFrame: number;
+    readonly triggers: readonly TriggerPoint[];
+}): TriggeredSchedule;
+
+/** Quantize one non-negative authored duration into the canonical sample domain exactly once. */
+declare function temporalDurationInSamples(duration: TemporalDuration, space: ProgramSpace, sampleRate?: number): number;
+
+declare const temporalModuleRef: {
+    readonly name: "@hypit/temporal";
+    readonly version: "1";
+};
+declare const temporalTypes: {
+    instantSpec: {
+        module: {
+            readonly name: "@hypit/temporal";
+            readonly version: "1";
+        };
+        name: string;
+    };
+    instant: {
+        module: {
+            readonly name: "@hypit/temporal";
+            readonly version: "1";
+        };
+        name: string;
+    };
+    windowSpec: {
+        module: {
+            readonly name: "@hypit/temporal";
+            readonly version: "1";
+        };
+        name: string;
+    };
+    window: {
+        module: {
+            readonly name: "@hypit/temporal";
+            readonly version: "1";
+        };
+        name: string;
+    };
+};
+declare const temporalProducers: {
+    projectProgramInstant: {
+        module: {
+            readonly name: "@hypit/temporal";
+            readonly version: "1";
+        };
+        name: string;
+    };
+    projectSelectionInstant: {
+        module: {
+            readonly name: "@hypit/temporal";
+            readonly version: "1";
+        };
+        name: string;
+    };
+    projectSegmentInstant: {
+        module: {
+            readonly name: "@hypit/temporal";
+            readonly version: "1";
+        };
+        name: string;
+    };
+    projectMomentInstant: {
+        module: {
+            readonly name: "@hypit/temporal";
+            readonly version: "1";
+        };
+        name: string;
+    };
+    composeWindow: {
+        module: {
+            readonly name: "@hypit/temporal";
+            readonly version: "1";
+        };
+        name: string;
+    };
+};
+declare const temporalManifest: ModuleManifest;
+declare const temporalDependency: {
+    readonly module: {
+        readonly name: "@hypit/temporal";
+        readonly version: "1";
+    };
+};
+declare const temporalInstantSpecSchema: ValueSchema;
+declare const temporalInstantSchema: ValueSchema;
+declare const temporalWindowSpecSchema: ValueSchema;
+declare const temporalWindowSchema: ValueSchema;
+
+export { assertTemporalInstantFor, assertTemporalWindowFor, assertWindowRelation, composeTemporalWindow, locateMoment, locateProgram, locateSegment, locateSelection, projectMomentInstant, projectProgramInstant, projectSegmentInstant, projectSelectionInstant, projectTemporalInstant, resolveTriggeredSchedule, temporalDependency, temporalDurationInSamples, temporalInstantSchema, temporalInstantSpecSchema, temporalManifest, temporalModuleRef, temporalProducers, temporalTypes, temporalWindowSchema, temporalWindowSpecSchema };
+export type { FramePoint, FrameSpan, LocatedMoment, LocatedProgram, LocatedSegment, LocatedSelection, ProjectedInstant, ProjectedWindow, TemporalConsumption, TemporalDuration, TemporalInstant, TemporalInstantAuthority, TemporalInstantExpression, TemporalInstantSpec, TemporalSource, TemporalWindow, TemporalWindowSpec, TriggerPoint, TriggeredSchedule, WindowRelation };