@hypit/hypit 0.0.1 → 0.1.1

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

@@ -0,0 +1,427 @@
+/** 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;
+};
+type CredentialStore = {
+    resolve(ref: CredentialRef): Promise<CredentialValue | undefined>;
+};
+
+/** 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;
+};
+
+/** 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;
+    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[]>;
+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;
+    };
+}>>>;
+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>>;
+};
+/** 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;
+};
+
+/** A deadline covers headers and body consumption even when a transport ignores abort. */
+declare function requestDeadline(timeoutMs: number, error?: () => Error): {
+    signal: AbortSignal;
+    wait: <T>(work: Promise<T>) => Promise<T>;
+    finish: () => void;
+};
+
+declare const runtimeEndpointAdapterHostAbi = "hypit.runtime-endpoint-adapter-host@1";
+declare const runtimeCredentialStoreAdapterHostAbi = "hypit.runtime-credential-store-adapter-host@1";
+type RuntimeAdapterKind = "endpoint" | "credential-store";
+type RuntimeAdapterFactoryContext = {
+    /** Persistent machine/user state supplied by the Host, outside every author project. */
+    readonly hostStateRoot: string;
+    /** Runtime/Profile state belonging to this project. */
+    readonly dataRoot: string;
+    readonly instance: string;
+    readonly pool?: string;
+    readonly config: CanonicalValue;
+};
+type RuntimeDoctorDiagnostic = {
+    readonly severity: "error" | "warning" | "info";
+    readonly code: string;
+    readonly message: string;
+    readonly subject?: string;
+};
+type ManagedProgramCommand = {
+    readonly command: string;
+    readonly args: readonly string[];
+    readonly cwd?: string;
+    readonly env?: Readonly<Record<string, string>>;
+};
+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. */
+    readonly commands: readonly ManagedProgramCommand[];
+};
+type ManagedProgramState = {
+    readonly state: "ready";
+} | {
+    readonly state: "down";
+    readonly detail: string;
+} | {
+    readonly state: "mismatch";
+    readonly detail: string;
+};
+type ManagedProgram = {
+    readonly id: string;
+    /** Shared lifecycle files live here; absent means this Runtime owns them. */
+    readonly stateRoot?: string;
+    /** Installation and runtime readiness are deliberately separate states. */
+    readonly installation?: ManagedProgramInstallation;
+    probe(): Promise<ManagedProgramState>;
+    readonly start?: ManagedProgramCommand;
+};
+type RuntimeEndpointActivation = {
+    readonly endpoint: EndpointPackage;
+    readonly program?: ManagedProgram;
+    readonly diagnose?: (context: {
+        readonly credentials: Readonly<Record<string, CredentialValue>>;
+        readonly capabilities?: readonly CapabilityRef[];
+    }) => readonly RuntimeDoctorDiagnostic[] | Promise<readonly RuntimeDoctorDiagnostic[]>;
+};
+type RuntimeOpened<T> = {
+    readonly value: T;
+    readonly close?: () => void | Promise<void>;
+};
+type RuntimeEndpointAdapterImplementation = {
+    activate(context: RuntimeAdapterFactoryContext): RuntimeEndpointActivation | Promise<RuntimeEndpointActivation>;
+};
+type RuntimeStoreAdapterImplementation<T> = {
+    validate(context: RuntimeAdapterFactoryContext): void;
+    open(context: RuntimeAdapterFactoryContext): RuntimeOpened<T> | Promise<RuntimeOpened<T>>;
+    doctor?(context: RuntimeAdapterFactoryContext): readonly RuntimeDoctorDiagnostic[] | Promise<readonly RuntimeDoctorDiagnostic[]>;
+};
+type RuntimeAdapterImplementation = RuntimeEndpointAdapterImplementation | RuntimeStoreAdapterImplementation<CredentialStore>;
+type RuntimeAdapterHostFacet = HostFacet & {
+    readonly abi: typeof runtimeEndpointAdapterHostAbi | typeof runtimeCredentialStoreAdapterHostAbi;
+    readonly implementation: RuntimeAdapterImplementation;
+};
+declare function createRuntimeEndpointAdapterFacet(options: {
+    readonly use: string;
+    readonly activate: RuntimeEndpointAdapterImplementation["activate"];
+}): RuntimeAdapterHostFacet;
+declare function createRuntimeCredentialStoreAdapterFacet(options: {
+    readonly use: string;
+    readonly validate: RuntimeStoreAdapterImplementation<CredentialStore>["validate"];
+    readonly open: RuntimeStoreAdapterImplementation<CredentialStore>["open"];
+    readonly doctor?: RuntimeStoreAdapterImplementation<CredentialStore>["doctor"];
+}): RuntimeAdapterHostFacet;
+declare function isRuntimeAdapterHostFacet(value: HostFacet): value is RuntimeAdapterHostFacet;
+declare class RuntimeAdapterRegistry {
+    #private;
+    registerFacet(facet: HostFacet): void;
+    has(use: string, kind: RuntimeAdapterKind): boolean;
+    activateEndpoint(use: string, context: RuntimeAdapterFactoryContext): Promise<RuntimeEndpointActivation>;
+    createEndpoint(use: string, context: RuntimeAdapterFactoryContext): Promise<EndpointPackage>;
+    openCredentialStore(use: string, context: RuntimeAdapterFactoryContext): Promise<RuntimeOpened<CredentialStore>>;
+    validate(use: string, kind: Exclude<RuntimeAdapterKind, "endpoint">, context: RuntimeAdapterFactoryContext): readonly RuntimeDoctorDiagnostic[];
+    doctor(use: string, kind: Exclude<RuntimeAdapterKind, "endpoint">, context: RuntimeAdapterFactoryContext): Promise<readonly RuntimeDoctorDiagnostic[]>;
+}
+declare function runtimeConfigObject(value: CanonicalValue, subject: string): Record<string, CanonicalValue>;
+declare function runtimeConfigExact(value: Record<string, CanonicalValue>, allowed: readonly string[], subject: string): void;
+declare function runtimeConfigString(value: CanonicalValue | undefined, subject: string): string | undefined;
+declare function runtimeConfigPositiveInteger(value: CanonicalValue | undefined, subject: string): number | undefined;
+declare function runtimeConfigBoolean(value: CanonicalValue | undefined, subject: string): boolean | undefined;
+declare function runtimeConfigCredentialRef(value: CanonicalValue | undefined, subject: string): CredentialRef | undefined;
+/** Common Profile representation for short action occupancy and rate budgets. */
+declare function runtimeConfigActionLimits(value: CanonicalValue | undefined): EndpointActionLimits | undefined;
+
+export { RuntimeAdapterRegistry, createRuntimeCredentialStoreAdapterFacet, createRuntimeEndpointAdapterFacet, isRuntimeAdapterHostFacet, requestDeadline, runtimeConfigActionLimits, runtimeConfigBoolean, runtimeConfigCredentialRef, runtimeConfigExact, runtimeConfigObject, runtimeConfigPositiveInteger, runtimeConfigString, runtimeCredentialStoreAdapterHostAbi, runtimeEndpointAdapterHostAbi };
+export type { ManagedProgram, ManagedProgramCommand, ManagedProgramInstallation, ManagedProgramState, RuntimeAdapterFactoryContext, RuntimeAdapterHostFacet, RuntimeAdapterKind, RuntimeDoctorDiagnostic, RuntimeEndpointActivation, RuntimeEndpointAdapterImplementation, RuntimeOpened };