@hypit/hypit 0.1.3 → 0.1.5

package/dist/public/program-space.d.ts

@@ -1,3 +1,6 @@
+/** Opaque identity for one admitted byte resource. Equal bytes may have different identities. */
+type ResourceId = `res_${string}`;
+type RecordId = string;
 type ModuleRef = {
     readonly name: string;
     readonly version: string;
@@ -11,6 +14,10 @@ type TypeRef = {
     readonly module: ModuleRef;
     readonly name: string;
 };
+type ProducerRef = {
+    readonly module: ModuleRef;
+    readonly name: string;
+};
 type CapabilityRef = {
     readonly module: ModuleRef;
     readonly name: string;
@@ -19,6 +26,17 @@ type CapabilityRef = {
 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";
 } | {
@@ -95,6 +113,166 @@ type ModuleManifest = {
     readonly producers: readonly ProducerDeclaration[];
 };
 
+type SourceRange = {
+    readonly start: number;
+    readonly end: number;
+};
+/** 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 FragmentInputRef = {
+    readonly kind: "fragment-input";
+    readonly name: string;
+};
+type FragmentOperationRef = {
+    readonly kind: "fragment-operation";
+    readonly operation: string;
+};
+type FragmentValueRef = FragmentInputRef | FragmentOperationRef;
+type FragmentOperationResult = {
+    readonly kind: "output";
+    readonly name: string;
+} | {
+    readonly kind: "need";
+    readonly name: string;
+};
+type FragmentOperation = {
+    readonly id: string;
+    readonly producer: ProducerRef;
+    readonly inputs: Readonly<Record<string, FragmentValueRef>>;
+    readonly result: FragmentOperationResult;
+};
+type FragmentExport = {
+    readonly name: string;
+    readonly type: TypeRef;
+    readonly root: FragmentOperationRef;
+};
+type GraphFragment = {
+    readonly format: "hypit.fragment@1";
+    readonly id: string;
+    readonly inputs: readonly {
+        readonly name: string;
+        readonly type: TypeRef;
+    }[];
+    readonly operations: readonly FragmentOperation[];
+    readonly exports: readonly FragmentExport[];
+};
+
+/** A reference to an authored fact that already exists in the Linked Program. */
+type AuthorRecordRef = {
+    readonly kind: "record";
+    readonly id: string;
+};
+/** A symbolic reference to one public export of another component instance. */
+type AuthorComponentOutputRef = {
+    readonly kind: "component-output";
+    readonly component: string;
+    readonly output: string;
+};
+type AuthorValueRef = AuthorRecordRef | AuthorComponentOutputRef;
+/**
+ * One author-visible component call. `outputs` binds every public Fragment export to a Logical Output.
+ */
+type AuthorComponent = {
+    readonly id: string;
+    readonly fragment: string;
+    readonly inputs: Readonly<Record<string, AuthorValueRef>>;
+    readonly outputs: Readonly<Record<string, string>>;
+};
+
+type SourceAssetRequest = {
+    readonly from: string;
+    readonly mediaType: string;
+    /** Package-owned bytes admitted by the compiler before a Workspace is consulted. */
+    readonly bytes?: Uint8Array;
+    readonly range?: SourceRange;
+};
+type ResolvedSourceAsset = {
+    readonly artifact: BlobRef;
+};
+
+/** A semantic source dependency requested by a Frontend or package-owned Surface. */
+type AuthorSourceAssetRequest = SourceAssetRequest;
+type ResolvedAuthorSourceAsset = ResolvedSourceAsset;
+/**
+ * One author-visible identity whose uniqueness is part of a domain's public
+ * contract. The Frontend only carries the declaration; the owning Surface
+ * chooses the Type namespace and the Source closure enforces it generically.
+ */
+type AuthorSourceIdentity = {
+    readonly namespace: TypeRef;
+    readonly id: string;
+};
+type Awaitable<T> = T | Promise<T>;
+
+type MarkupReference = {
+    readonly kind: "reference";
+    readonly path: string;
+};
+type MarkupAttributeValue = string | MarkupReference;
+type StructuredText = {
+    readonly kind: "text";
+    readonly value: string;
+    readonly range: SourceRange;
+};
+type StructuredElement = {
+    readonly kind: "element";
+    readonly name: string;
+    readonly attributes: Readonly<Record<string, MarkupAttributeValue>>;
+    /** Exact ranges of literal/reference values in the opening tag. */
+    readonly attributeValueRanges?: Readonly<Record<string, SourceRange>>;
+    readonly children: readonly StructuredNode[];
+    readonly range: SourceRange;
+};
+type StructuredNode = StructuredText | StructuredElement;
+type SurfaceRecordDraft = {
+    readonly id: string;
+    readonly type: TypeRef;
+    readonly value: StoredValue;
+    readonly range: SourceRange;
+};
+/** Source-local diagnostics are removed before the component enters semantic elaboration. */
+type SurfaceComponentDraft = AuthorComponent & {
+    readonly range: SourceRange;
+};
+type SurfaceDecodeOutput = {
+    readonly records: readonly SurfaceRecordDraft[];
+    readonly components: readonly SurfaceComponentDraft[];
+    readonly fragments: readonly GraphFragment[];
+    /** Domain-owned public identities that must be unique in the Source closure. */
+    readonly identities?: readonly AuthorSourceIdentity[];
+    /**
+     * Public source bindings contributed by this Surface invocation. Omit to
+     * publish every generated binding; use an explicit list to keep plumbing
+     * addressable inside the source without exposing it from the source.
+     */
+    readonly exports?: readonly string[];
+};
+type StructuredSurfaceInput = {
+    readonly sourceName: string;
+    readonly element: StructuredElement;
+    /**
+     * Resolve an explicitly written author reference. Imported record values are
+     * available because their source has already been compiled and admitted.
+     * A component output has a ref and Type but no compile-time Record value.
+     */
+    readonly resolveReference: (path: string) => SurfaceResolvedReference | undefined;
+    readonly resolveAsset: (request: AuthorSourceAssetRequest) => Awaitable<ResolvedAuthorSourceAsset>;
+};
+type SurfaceResolvedReference = {
+    readonly path: string;
+    readonly ref: AuthorValueRef;
+    readonly type: TypeRef;
+    readonly record?: TypedRecord;
+};
+type StructuredSurfaceHandler = (input: StructuredSurfaceInput) => Awaitable<SurfaceDecodeOutput>;
+
+declare const decodeClockSurface: StructuredSurfaceHandler;
+
 type ProgramClock = {
     readonly frameRate: {
         readonly numerator: number;
@@ -149,37 +327,6 @@ declare const programSpaceMarkupSurfaces: readonly [{
         };
         name: string;
     }];
-}, {
-    readonly name: "space";
-    readonly tag: "Space";
-    readonly mode: "structured";
-    readonly outputs: readonly [{
-        module: {
-            readonly name: "@hypit/program-space";
-            readonly version: "1";
-        };
-        name: string;
-    }];
-    readonly vocabulary: {
-        readonly summary: "Declares a film's frame rate and authored duration, for animation whose timing is directed without a performance.";
-        readonly attributes: readonly [{
-            readonly name: "id";
-            readonly kind: "identifier";
-            readonly required: true;
-            readonly summary: "Names the shared film time axis.";
-        }, {
-            readonly name: "frame-rate";
-            readonly kind: "literal";
-            readonly required: true;
-            readonly summary: "Frames per second, such as 30 or 30000/1001.";
-        }, {
-            readonly name: "duration";
-            readonly kind: "literal";
-            readonly required: true;
-            readonly summary: "Total duration in seconds, milliseconds or frames, such as 8s or 240f; ends on a frame boundary.";
-        }];
-        readonly example: "<time:Space id=\"animation\" frame-rate=\"30\" duration=\"8s\"/>";
-    };
 }];
 declare function sealProgramClock(value: ProgramClock): ProgramClock;
 declare function assertProgramClockIdentity(clock: ProgramClock): void;
@@ -189,5 +336,5 @@ declare function programSpaceSampleFrames(programSpace: ProgramSpace, sampleRate
 declare function programFrameSampleBoundary(programSpace: ProgramSpace, frame: number, sampleRate: number): number;
 declare function assertProgramSpaceIdentity(programSpace: ProgramSpace): void;
 
-export { assertProgramClockIdentity, assertProgramSpaceIdentity, programFrameSampleBoundary, programSpaceDependency, programSpaceFrameCount, programSpaceManifest, programSpaceMarkupSurfaces, programSpaceModuleRef, programSpaceSampleFrames, programSpaceSchema, programSpaceTypes, sealProgramClock, sealProgramSpace };
+export { assertProgramClockIdentity, assertProgramSpaceIdentity, decodeClockSurface, programFrameSampleBoundary, programSpaceDependency, programSpaceFrameCount, programSpaceManifest, programSpaceMarkupSurfaces, programSpaceModuleRef, programSpaceSampleFrames, programSpaceSchema, programSpaceTypes, sealProgramClock, sealProgramSpace };
 export type { ProgramClock, ProgramSpace };

package/dist/public/runtime-kit.d.ts

@@ -84,13 +84,6 @@ type CapacityResourceClaim = {
     readonly periodMs?: number;
 };
 
-/** One package contribution understood only by the Host that owns its ABI. */
-type HostFacet = {
-    readonly abi: string;
-    readonly offers?: readonly string[];
-    readonly implementation: unknown;
-};
-
 /** Provider-authored, non-secret acknowledgement suitable for Results and user inspection. */
 type OperationReceipt = {
     readonly id: string;
@@ -114,6 +107,20 @@ type OperationProgress = {
     readonly unit?: string;
 };
 
+/** One package contribution understood only by the Host that owns its ABI. */
+type HostFacet = {
+    readonly abi: string;
+    readonly offers?: readonly string[];
+    readonly implementation: unknown;
+};
+
+/** Provider-authored diagnostic text suitable for users; never credentials or request bodies. */
+type ExecutionDiagnostic = {
+    readonly level: "info" | "warning" | "error";
+    readonly message: string;
+    readonly stream?: "stdout" | "stderr";
+};
+
 /** Build-local byte resources. Location, retention and transport are Runtime policy. */
 type ResourceIOOptions = {
     /** Cancel the transfer, close its streams and discard unfinished writes before rejecting.
@@ -176,6 +183,10 @@ type EndpointInvocationContext = {
     readonly resources: ResourceStore;
     /** Only slots explicitly declared by this configured Endpoint instance are present. */
     readonly credentials: Readonly<Record<string, EndpointCredential>>;
+    /** Explicit non-secret diagnostic output. The Provider owns its content, never its storage. */
+    readonly reportDiagnostic?: (diagnostic: ExecutionDiagnostic) => Promise<void>;
+    /** Report non-secret activity of a long local call without creating a remote Operation. */
+    readonly reportProgress?: (progress: OperationProgress) => Promise<void>;
 };
 type ImmediateEndpointHandler = (context: EndpointInvocationContext) => Awaitable<EndpointFulfillment>;
 type EndpointCheckpoint = {
@@ -347,7 +358,9 @@ type ManagedProgramCommand = {
 type ManagedProgramInstallation = {
     /** Truthful inspection of the installed program; no installer-owned receipt. */
     probe(): Promise<ManagedProgramState>;
-    /** Commands run only when the installation probe is not ready. */
+    /** Reconcile an installed environment before a cold start, using its package manager's cache. */
+    readonly prepareBeforeStart?: boolean;
+    /** Commands run when installation is missing, or before a cold start when requested above. */
     readonly commands: readonly ManagedProgramCommand[];
 };
 type ManagedProgramState = {