@hypit/hypit 0.0.1 → 0.1.1

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

@@ -0,0 +1,366 @@
+/** Opaque identity for one admitted byte resource. Equal bytes may have different identities. */
+type ResourceId = `res_${string}`;
+type RecordId = string;
+type NeedId = 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 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 Need = {
+    readonly id: NeedId;
+    readonly capability: CapabilityRef;
+    readonly returns: TypeRef;
+    readonly constraints: CanonicalValue;
+    readonly result: RecordId;
+};
+type FulfillNeedCommand = {
+    readonly kind: "fulfill-need";
+    readonly id: CommandId;
+    readonly need: Need;
+};
+
+type CredentialRef = {
+    /** CredentialStore implementation name, for example env, os or aws-default. */
+    readonly store: string;
+    /** Store-local opaque lookup key. It is configuration, never the secret value. */
+    readonly key: string;
+};
+type CredentialValue = {
+    /** Opaque secret revealed only to the selected Endpoint invocation. */
+    readonly secret: string;
+    readonly expiresAt?: number;
+};
+/** Host-facing way to acquire one credential; Provider-specific values stay in its Endpoint package. */
+type CredentialAcquisition = {
+    readonly kind: "oauth2-pkce";
+    readonly authorizationEndpoint: string;
+    readonly tokenEndpoint: string;
+    readonly clientId: string;
+    readonly scopes: readonly string[];
+    /** Maximum duration of the service-owned token exchange after browser authorization returns. */
+    readonly requestTimeoutMs: number;
+};
+
+/** A shared resource: occupancy when periodMs is absent, a replenishing rate budget otherwise. */
+type CapacityResourceClaim = {
+    readonly id: string;
+    readonly limit: number;
+    /** Number of units held by this Command; ordinary requests occupy one. */
+    readonly units?: number;
+    /** Replenish `limit` units per period, with a burst of at most `limit`. Rate units are not returned. */
+    readonly periodMs?: number;
+};
+
+/** Provider-authored, non-secret acknowledgement suitable for Results and user inspection. */
+type OperationReceipt = {
+    readonly id: string;
+    readonly url?: string;
+};
+type OperationFailure = {
+    readonly code: string;
+    readonly message: string;
+};
+/**
+ * Provider-neutral, human-observable progress for one asynchronous Operation.
+ *
+ * The opaque handle remains the Provider's private task state. This
+ * deliberately small projection is the only part Runtime tools may display;
+ * it must not carry credentials, request bodies or vendor-specific payloads.
+ */
+type OperationProgress = {
+    readonly phase: string;
+    readonly completed?: number;
+    readonly total?: number;
+    readonly unit?: string;
+};
+
+/** 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.
+     * Stream producers supplied by the caller must observe the same signal while producing chunks.
+     */
+    readonly signal?: AbortSignal;
+};
+type ResourceStore = {
+    /** Store one new resource instance. Equal bytes remain independent resources. */
+    put(bytes: Uint8Array, mediaType: string, options?: ResourceIOOptions): Promise<BlobRef>;
+    /** Write bytes for an already-declared source or historical resource. */
+    write(resource: BlobRef, bytes: Uint8Array, options?: ResourceIOOptions): Promise<void>;
+    /** Read bytes previously stored under this execution identity. */
+    get(resource: ResourceId, options?: ResourceIOOptions): Promise<Uint8Array | undefined>;
+    /** Cheap presence query. */
+    has(resource: ResourceId, options?: ResourceIOOptions): Promise<boolean>;
+};
+
+type Awaitable<T> = T | Promise<T>;
+type EndpointFulfillment = {
+    readonly value: StoredValue;
+};
+/** One future input binding whose value does not exist until an upstream graph step runs. */
+type EndpointInputSlot = {
+    readonly input: string;
+    readonly role?: string;
+};
+/**
+ * The complete support-relevant request. Execution-only ids and the result Record are deliberately
+ * absent. Before a Build, future graph values appear as semantic slots; during execution their
+ * concrete values are already present in `constraints` and `pendingInputs` is omitted.
+ */
+type EndpointRequest = {
+    readonly capability: Need["capability"];
+    readonly returns: Need["returns"];
+    readonly constraints: Need["constraints"];
+    readonly pendingInputs?: readonly EndpointInputSlot[];
+};
+type EndpointCredential = CredentialValue & {
+    /** Narrow write authority for this declared slot only, when its selected Store is writable. */
+    readonly replace?: (value: CredentialValue) => Promise<void>;
+};
+/** Provider-owned pricing material read from one exact source. Its shape remains the Provider's. */
+type EndpointPricingDocument = {
+    readonly source: string;
+    readonly data: CanonicalValue;
+    /** Optional concise rate description, including units and conditions, owned by this Provider. */
+    readonly summary?: string;
+};
+type EndpointPricingReaderContext = {
+    readonly request: EndpointRequest;
+    /** Resolve credentials only when this Provider's pricing source requires them. */
+    readonly credentials: () => Promise<Readonly<Record<string, EndpointCredential>>>;
+};
+/** Read whatever current pricing material this Provider can usefully narrow for one request. */
+type EndpointPricingReader = (context: EndpointPricingReaderContext) => Awaitable<readonly EndpointPricingDocument[]>;
+declare function verifyEndpointPricingDocument(value: EndpointPricingDocument): void;
+type EndpointInvocationContext = {
+    readonly command: FulfillNeedCommand;
+    readonly need: Need;
+    readonly resources: ResourceStore;
+    /** Only slots explicitly declared by this configured Endpoint instance are present. */
+    readonly credentials: Readonly<Record<string, EndpointCredential>>;
+};
+type ImmediateEndpointHandler = (context: EndpointInvocationContext) => Awaitable<EndpointFulfillment>;
+type EndpointCheckpoint = {
+    readonly handle: CanonicalValue;
+    readonly receipt?: OperationReceipt;
+    readonly remoteEnded?: true;
+};
+declare const endpointActions: readonly ["submit", "poll", "collect"];
+type EndpointAction = typeof endpointActions[number];
+type EndpointActionLimits = Partial<Readonly<Record<EndpointAction, {
+    readonly concurrency?: number;
+    readonly rate?: {
+        readonly limit: number;
+        readonly periodMs: number;
+    };
+}>>>;
+declare function actionResourceClaims(pool: string, limits: EndpointActionLimits): NonNullable<EndpointScheduling["actions"]>;
+type EndpointOutcome = ({
+    readonly status: "pending";
+    readonly handle: CanonicalValue;
+    readonly wakeAt?: number;
+    readonly progress?: OperationProgress;
+} | {
+    readonly status: "completed";
+    readonly result: EndpointFulfillment;
+} | {
+    readonly status: "failed";
+    readonly failure: OperationFailure;
+}
+/** Remote work ended; collect its existing artifacts in a separate short action. */
+ | {
+    readonly status: "ready";
+    readonly handle: CanonicalValue;
+}) & {
+    readonly receipt?: OperationReceipt;
+};
+type EndpointStartContext = EndpointInvocationContext & {
+    /** Runtime-local identifier used to poll or cancel this submission. */
+    readonly operation: string;
+    /** Persist acknowledgement before doing further work. Secret values never belong in a receipt. */
+    readonly checkpoint?: (checkpoint: EndpointCheckpoint) => Promise<void>;
+};
+type EndpointPollContext = EndpointStartContext & {
+    /** Provider task state returned by start(). */
+    readonly handle: CanonicalValue;
+};
+/**
+ * Provider-side acknowledgement is deliberately separate from the Operation's final state.
+ * `accepted` means the remote system accepted a request but may still finish normally; only
+ * `confirmed` proves that the work itself is cancelled.
+ */
+type EndpointCancelOutcome = {
+    readonly status: "confirmed";
+} | {
+    readonly status: "accepted";
+} | {
+    readonly status: "unsupported";
+} | {
+    readonly status: "too-late";
+};
+type AsyncEndpoint = {
+    start(context: EndpointStartContext): Awaitable<EndpointOutcome>;
+    poll(context: EndpointPollContext): Awaitable<EndpointOutcome>;
+    cancel?(context: EndpointPollContext): Awaitable<EndpointCancelOutcome>;
+    collect?(context: EndpointPollContext): Awaitable<EndpointOutcome>;
+};
+/** Endpoint scheduling. It never changes Core demand. */
+type EndpointScheduling = {
+    readonly resources: readonly CapacityResourceClaim[];
+    readonly actions?: Partial<Readonly<Record<EndpointAction, readonly CapacityResourceClaim[]>>>;
+    /** Pure request-dependent quantities for already declared resources. */
+    readonly unitsForRequest?: (request: EndpointRequest) => Readonly<Record<string, number>>;
+};
+declare function endpointResourceClaims(scheduling: EndpointScheduling, request: EndpointRequest): readonly CapacityResourceClaim[];
+/** A Provider's complete support decision for one concrete request. */
+type EndpointSupport = {
+    readonly status: "supported";
+} | {
+    readonly status: "unsupported";
+    readonly reason: string;
+};
+type EndpointRegistrationOptions = {
+    readonly pool?: string;
+    readonly supports?: (request: EndpointRequest) => EndpointSupport;
+    readonly scheduling?: EndpointScheduling;
+    readonly credentials?: Readonly<Record<string, CredentialRef>>;
+    /**
+     * This immediate capability may be evaluated by a disposable authoring session without a
+     * Build, Result or recoverable Operation. The Provider is asserting that doing so submits no
+     * paid generation and creates no externally visible side effect. It is not a byte-for-byte
+     * reproducibility claim.
+     */
+    readonly transient?: true;
+};
+/** Minimal structural port implemented by a trusted execution Host. */
+interface EndpointRegistrar {
+    registerImmediateEndpoint(id: string, capability: CapabilityRef, returns: TypeRef, handler: ImmediateEndpointHandler, options?: EndpointRegistrationOptions): void;
+    registerAsyncEndpoint(id: string, capability: CapabilityRef, returns: TypeRef, endpoint: AsyncEndpoint, options?: EndpointRegistrationOptions): void;
+}
+/**
+ * Where the Provider behind an Endpoint publishes its prices. Hypit never copies or interprets the
+ * prices themselves; it only tells the caller where the Provider's own page is, or that the work runs
+ * on this machine without a Provider charge.
+ */
+type EndpointPricing = {
+    readonly kind: "page";
+    readonly url: string;
+} | {
+    readonly kind: "local";
+};
+type EndpointPackage = {
+    readonly instance: {
+        readonly id: string;
+        readonly pool: string;
+    };
+    readonly offers: readonly EndpointOffer[];
+    /** Host-facing login material declared by this exact configured Endpoint instance. */
+    readonly credentials: readonly EndpointCredentialDescription[];
+    readonly pricing?: EndpointPricing;
+    /** Optional live pricing-material reader owned by this Provider. */
+    readonly readPricing?: EndpointPricingReader;
+    install(registry: EndpointRegistrar): Awaitable<void>;
+};
+type EndpointOffer = {
+    readonly capability: CapabilityRef;
+    readonly returns: TypeRef;
+    readonly endpoint: string;
+    readonly supports?: (request: EndpointRequest) => EndpointSupport;
+    readonly transient?: true;
+};
+type EndpointCredentialDescription = {
+    readonly endpoint: string;
+    readonly slot: string;
+    readonly label: string;
+    readonly kind: "secret" | "json";
+    readonly ref: CredentialRef;
+    readonly acquisition?: CredentialAcquisition;
+};
+type EndpointCapabilityBase = {
+    readonly resources?: readonly CapacityResourceClaim[];
+    readonly unitsForRequest?: EndpointScheduling["unitsForRequest"];
+    readonly capability: CapabilityRef;
+    readonly returns: TypeRef;
+    readonly supports?: (request: EndpointRequest) => EndpointSupport;
+    /**
+     * Also allow this capability in a disposable, non-Build authoring execution.
+     * The Provider is asserting that it needs no durable or cross-Build capacity
+     * admission; declared limits are still honored within that one session.
+     */
+    readonly transient?: true;
+    /** Stable Provider-local capacity class. Defaults to the capability name. */
+    readonly capacity?: string;
+    /** Exact-capability capacity; the Provider pool keeps its independent total capacity. */
+    readonly maxConcurrency?: number;
+};
+type ImmediateEndpointCapability = EndpointCapabilityBase & {
+    readonly lifecycle: "immediate";
+    readonly handler: ImmediateEndpointHandler;
+};
+type AsyncEndpointCapability = EndpointCapabilityBase & {
+    readonly lifecycle: "asynchronous";
+    readonly endpoint: AsyncEndpoint;
+};
+type EndpointCapability = ImmediateEndpointCapability | AsyncEndpointCapability;
+type DefineEndpointPackageOptions = {
+    readonly module: ModuleRef;
+    readonly facet: string;
+    readonly instance: string;
+    /** Explicit non-secret account, deployment or compute-pool identity. */
+    readonly pool: string;
+    readonly credentials?: Readonly<Record<string, CredentialRef>>;
+    readonly credentialInputs?: Readonly<Record<string, {
+        readonly label: string;
+        readonly kind?: "secret" | "json";
+        readonly acquisition?: CredentialAcquisition;
+    }>>;
+    /** Total capacity shared by every capability under this configured Provider pool. */
+    readonly defaultConcurrency?: number;
+    readonly actions?: EndpointScheduling["actions"];
+    readonly actionLimits?: EndpointActionLimits;
+    /** The Provider's own price page, or `local` for work that runs on this machine without a charge. */
+    readonly pricing?: EndpointPricing;
+    /** Read current Provider-owned pricing material relevant to one request. */
+    readonly readPricing?: EndpointPricingReader;
+    readonly capabilities: readonly EndpointCapability[];
+};
+/** Build every static and executable fact for one configured Endpoint from one definition. */
+declare function defineEndpointPackage(options: DefineEndpointPackageOptions): EndpointPackage;
+declare function wakeAfter(handle: CanonicalValue, delayMs: number, now?: number, progress?: OperationProgress): {
+    readonly status: "pending";
+    readonly handle: CanonicalValue;
+    readonly wakeAt: number;
+    readonly progress?: OperationProgress;
+};
+
+export { actionResourceClaims, defineEndpointPackage, endpointActions, endpointResourceClaims, verifyEndpointPricingDocument, wakeAfter };
+export type { AsyncEndpoint, AsyncEndpointCapability, Awaitable, CanonicalValue, CapabilityRef, CapacityResourceClaim, CredentialAcquisition, CredentialRef, CredentialValue, DefineEndpointPackageOptions, EndpointAction, EndpointActionLimits, EndpointCancelOutcome, EndpointCapability, EndpointCheckpoint, EndpointCredential, EndpointCredentialDescription, EndpointFulfillment, EndpointInputSlot, EndpointInvocationContext, EndpointOffer, EndpointOutcome, EndpointPackage, EndpointPollContext, EndpointPricing, EndpointPricingDocument, EndpointPricingReader, EndpointPricingReaderContext, EndpointRegistrar, EndpointRegistrationOptions, EndpointRequest, EndpointScheduling, EndpointStartContext, EndpointSupport, ImmediateEndpointCapability, ImmediateEndpointHandler, ModuleRef, OperationFailure, OperationProgress, OperationReceipt, ResourceIOOptions, ResourceStore, StoredValue, TypeRef };