@hypit/hypit 0.0.1 → 0.1.0

package/packages/endpoint-kit/README.md

@@ -0,0 +1,111 @@
+# `@hypit/hypit/endpoint-kit`
+
+SDK for packages that fulfill exact external capabilities.
+
+External Provider packages import this public subpath from the `@hypit/hypit` Distribution. Use `@hypit/hypit` as
+a development dependency, compile the Provider to JavaScript, and ship its code plus any ordinary
+runtime dependencies. The active Distribution supplies this API when loading the package.
+No Hypit checkout is needed to develop or install the extension.
+
+```ts
+import { defineEndpointPackage } from "@hypit/hypit/endpoint-kit";
+import type { AsyncEndpoint, CredentialRef, EndpointRequest } from "@hypit/hypit/endpoint-kit";
+import { generationTypes, compileWireRequest, sealGeneratedImageSet } from "@hypit/hypit/generation";
+```
+
+For an existing model, name its exact versioned Capability and expected result Type. Map its request
+ports into the service's wire format; the Provider need not import the model's implementation.
+`@hypit/hypit/generation` supplies the common generated-media values and optional wire-mapping helpers.
+One Provider can implement multiple capabilities, and another Provider can implement those same
+capabilities. The Profile selects the implementation used by a project.
+
+An endpoint can call a vendor API, local process, Lambda function, device or human service. An
+endpoint package declares the capabilities it fulfills, its result types, credentials and scheduling
+limits, then installs handlers into a Host registrar.
+
+Immediate endpoints return a result directly. Asynchronous endpoints implement `start`, `poll` and
+optional best effort `cancel`. Provider-total and exact-capability resource limits control concurrency
+without changing Core demand. Each resource declares a `limit` and optional `units` (default 1).
+A capability may add `resources` and a pure `unitsForRequest(request)` resolver for quantities of
+already declared resources. Runtime admits all claims atomically for one `fulfill-need` Command.
+
+Asynchronous execution moves forward through `start`, `poll`, and optional `collect`. `start` returns
+a task handle; `pending` means an acknowledged task is still running. `ready` records remote completion
+and hands its artifacts to `collect`, allowing download capacity to differ from task capacity.
+An Endpoint may return `completed` directly when no separate collection is needed.
+
+A `failed` outcome or thrown error ends the local execution attempt. This does not assert that the
+remote job ended. A submission timeout with no receipt is a failure, not a pending task to reconcile.
+`context.checkpoint` saves an acknowledgement before subsequent work; public `receipt` fields contain
+non-secret task identifiers suitable for inspection and Result retention. Opaque `handle` remains
+Provider-owned execution data. Explicit cancellation is best effort; `accepted`, `unsupported` and
+`too-late` are recorded acknowledgements, not proof of remote termination.
+
+For asynchronous capabilities, `actionLimits` configures `submit`, `poll` and `collect` separately:
+
+```ts
+actionLimits: {
+  submit: { concurrency: 2, rate: { limit: 1, periodMs: 200 } },
+  poll: { concurrency: 8 },
+  collect: { concurrency: 2 },
+}
+```
+
+These are example deployment choices, not model limits. `defineEndpointPackage` scopes their resource
+identities to the declared pool; custom `actions` can instead supply explicit shared resource claims.
+`concurrency` holds units until that action returns. A rate budget starts with `limit` permits,
+replenishes `limit` permits per `periodMs`, and spends one permit per admitted action. One action may
+make several HTTP requests; Provider transport policy owns those individual requests. Whole-operation
+resources describe occupancy. Core contains neither these phases nor any Provider names.
+
+An individual immediate capability may declare `transient: true`. That permits a Runtime to use the
+same handler in a disposable authoring execution with no Build, Result or recoverable Operation. It is a
+Provider assertion that the call submits no paid generation and creates no external side effect; it is
+independent of pricing metadata and does not promise byte-identical output. The default is Build-only,
+and asynchronous capabilities cannot be transient. Its capacity limits apply within one disposable
+session; capabilities that require durable quota shared with Builds stay Build-only.
+
+Endpoint packages are selected by a Runtime Profile, never activated by author imports. This package
+depends on no Node filesystem, scheduler implementation or video domain.
+
+`pricing: { kind: "local" }` explicitly declares work on this machine without a Provider call charge.
+`pricing: { kind: "page", url }` identifies published pricing information; it does not determine an
+account's eventual bill. An absent declaration leaves pricing unknown. Callers can summarize explicit
+no-charge work while keeping unknown pricing and Endpoint selection failures visible.
+
+An Endpoint may also expose `readPricing`. It receives the same complete `EndpointRequest` used for
+support selection and resolves only that Endpoint's declared credentials when its source requires
+them. The Provider returns current pricing documents together with their source URLs. Their data shape
+belongs to the Provider: one service may return a model rate card, another a broader mixed catalogue,
+and another may expose only its declared pricing page. Hypit preserves the material instead of
+inventing a shared rate-table taxonomy, interpreting formulas, calculating totals, or turning pricing
+information into spending authority.
+
+An `EndpointPricingDocument` may add a concise `summary` for the default human view. It should retain
+the published rates, units and applicable conditions. The Provider owns this description because it
+knows its API's price fields and which fields merely describe marketing comparisons. The original
+`data` remains available in JSON and verbose output. Without a summary, the CLI displays the data.
+
+Use the Provider's execution mapping to select the upstream model and the request's known parameters
+to narrow the published material when the service supports it. Preserve applicable units and
+conditions. A future media input supplies its declared slot and role, not its eventual duration or
+other measured properties. Pricing readers receive no graph to traverse; incomplete usage still
+allows returning the model's rate information. Requests sharing a catalogue lookup can share that read
+inside the Provider, whose API determines what can be cached together.
+
+Three facts remain separate at this boundary:
+
+- the `EndpointRequest` describes the work selected by the Run;
+- an `EndpointPricingDocument` describes prices published by that Provider;
+- spending authority belongs to the user's decision about the described work and cost.
+
+The caller can place the first two beside each other for an Agent to calculate and explain. Request
+selection continues to follow the Runtime Profile and Endpoint support, while submission continues to
+follow the user's authority.
+
+`supports` receives one complete support description. For an executing Need, concrete graph values
+are already in `constraints`. During pre-Build planning, an upstream value that does not exist yet is
+represented by a semantic `pendingInputs` slot instead. A Provider may use the slot's input and
+media role to enforce support limits, but it never receives graph traversal rules or future bytes.
+It returns either `supported`, or `unsupported` with the Provider's reason. Selection infrastructure
+preserves that reason without interpreting request fields or maintaining a central limitation table.

package/packages/endpoint-kit/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "@hypit/endpoint-kit",
+  "version": "0.0.0-dev",
+  "license": "SEE LICENSE IN LICENSE",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "dependencies": {
+    "@hypit/protocol": "workspace:*",
+    "@hypit/runtime": "workspace:*"
+  }
+}

package/packages/endpoint-kit/src/index.ts

@@ -0,0 +1,488 @@
+import type {
+  CanonicalValue,
+  CapabilityRef,
+  FulfillNeedCommand,
+  ModuleRef,
+  Need,
+  StoredValue,
+  TypeRef,
+} from "@hypit/protocol";
+import { canonicalize } from "@hypit/protocol";
+import type {
+  ResourceStore,
+  CredentialAcquisition,
+  CredentialRef,
+  CredentialValue,
+  OperationFailure,
+  OperationProgress,
+  CapacityResourceClaim,
+  OperationReceipt,
+} from "@hypit/runtime";
+import { capacityUnits, verifyCredentialRef } from "@hypit/runtime";
+
+export type { CanonicalValue, CapabilityRef, ModuleRef, StoredValue, TypeRef } from "@hypit/protocol";
+export type {
+  CapacityResourceClaim,
+  CredentialAcquisition,
+  CredentialRef,
+  CredentialValue,
+  OperationFailure,
+  OperationProgress,
+  OperationReceipt,
+  ResourceIOOptions,
+  ResourceStore,
+} from "@hypit/runtime";
+
+export type Awaitable<T> = T | Promise<T>;
+
+export type EndpointFulfillment = {
+  readonly value: StoredValue;
+};
+
+/** One future input binding whose value does not exist until an upstream graph step runs. */
+export 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.
+ */
+export type EndpointRequest = {
+  readonly capability: Need["capability"];
+  readonly returns: Need["returns"];
+  readonly constraints: Need["constraints"];
+  readonly pendingInputs?: readonly EndpointInputSlot[];
+};
+
+export 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. */
+export type EndpointPricingDocument = {
+  readonly source: string;
+  readonly data: CanonicalValue;
+  /** Optional concise rate description, including units and conditions, owned by this Provider. */
+  readonly summary?: string;
+};
+
+export 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. */
+export type EndpointPricingReader = (
+  context: EndpointPricingReaderContext,
+) => Awaitable<readonly EndpointPricingDocument[]>;
+
+export function verifyEndpointPricingDocument(value: EndpointPricingDocument): void {
+  let source: URL | undefined;
+  try { source = new URL(value.source); } catch { source = undefined; }
+  assert(source?.protocol === "https:" || source?.hostname === "localhost",
+    "Endpoint pricing source must use HTTPS or localhost");
+  canonicalize(value.data);
+  assert(value.summary === undefined || typeof value.summary === "string",
+    "Endpoint pricing summary must be text");
+}
+
+export 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>>;
+};
+
+export type ImmediateEndpointHandler = (
+  context: EndpointInvocationContext,
+) => Awaitable<EndpointFulfillment>;
+
+export type EndpointCheckpoint = {
+  readonly handle: CanonicalValue;
+  readonly receipt?: OperationReceipt;
+  readonly remoteEnded?: true;
+};
+
+export const endpointActions = ["submit", "poll", "collect"] as const;
+export type EndpointAction = typeof endpointActions[number];
+export type EndpointActionLimits = Partial<Readonly<Record<EndpointAction, {
+  readonly concurrency?: number;
+  readonly rate?: { readonly limit: number; readonly periodMs: number };
+}>>>;
+
+export function actionResourceClaims(pool: string, limits: EndpointActionLimits): NonNullable<EndpointScheduling["actions"]> {
+  return Object.fromEntries(Object.entries(limits).map(([action, limit]) => {
+    if (!endpointActions.includes(action as EndpointAction)) throw new Error(`Unknown Endpoint action ${action}`);
+    const resources: CapacityResourceClaim[] = [
+      ...(limit.concurrency === undefined ? [] : [{ id: `action:${pool}/${action}`, limit: limit.concurrency }]),
+      ...(limit.rate === undefined ? [] : [{ id: `rate:${pool}/${action}`, ...limit.rate }]),
+    ];
+    resources.forEach(capacityUnits);
+    return [action, resources];
+  }));
+}
+
+export 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 };
+
+export 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>;
+};
+
+export 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.
+ */
+export type EndpointCancelOutcome =
+  | { readonly status: "confirmed" }
+  | { readonly status: "accepted" }
+  | { readonly status: "unsupported" }
+  | { readonly status: "too-late" };
+
+export 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. */
+export 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>>;
+};
+
+export function endpointResourceClaims(scheduling: EndpointScheduling, request: EndpointRequest): readonly CapacityResourceClaim[] {
+  const quantities = scheduling.unitsForRequest?.(request) ?? {};
+  for (const id of Object.keys(quantities)) {
+    if (!scheduling.resources.some((resource) => resource.id === id)) throw new Error(`Undeclared capacity resource ${id}`);
+  }
+  return scheduling.resources.map((resource) => {
+    const units = quantities[resource.id];
+    const claim = units === undefined ? resource : { ...resource, units };
+    capacityUnits(claim);
+    return claim;
+  });
+}
+
+/** A Provider's complete support decision for one concrete request. */
+export type EndpointSupport =
+  | { readonly status: "supported" }
+  | { readonly status: "unsupported"; readonly reason: string };
+
+export 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. */
+export 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.
+ */
+export type EndpointPricing =
+  | { readonly kind: "page"; readonly url: string }
+  | { readonly kind: "local" };
+
+export 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>;
+};
+
+export type EndpointOffer = {
+  readonly capability: CapabilityRef;
+  readonly returns: TypeRef;
+  readonly endpoint: string;
+  readonly supports?: (request: EndpointRequest) => EndpointSupport;
+  readonly transient?: true;
+};
+
+export 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;
+};
+
+export type ImmediateEndpointCapability = EndpointCapabilityBase & {
+  readonly lifecycle: "immediate";
+  readonly handler: ImmediateEndpointHandler;
+};
+
+export type AsyncEndpointCapability = EndpointCapabilityBase & {
+  readonly lifecycle: "asynchronous";
+  readonly endpoint: AsyncEndpoint;
+};
+
+export type EndpointCapability = ImmediateEndpointCapability | AsyncEndpointCapability;
+
+export 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[];
+};
+
+function assert(condition: unknown, message: string): asserts condition {
+  if (!condition) throw new Error(message);
+}
+
+function refKey(ref: { readonly module: ModuleRef; readonly name: string }): string {
+  return `${ref.module.name}@${ref.module.version}#${ref.name}`;
+}
+
+function positiveInteger(value: number, subject: string): number {
+  assert(Number.isSafeInteger(value) && value > 0, `${subject} must be a positive safe integer`);
+  return value;
+}
+
+/** Build every static and executable fact for one configured Endpoint from one definition. */
+export function defineEndpointPackage(options: DefineEndpointPackageOptions): EndpointPackage {
+  assert(options.module.name.trim().length > 0 && options.module.version.trim().length > 0,
+    "Endpoint module identity is invalid");
+  assert(options.facet.trim().length > 0, "Endpoint facet is empty");
+  assert(options.instance.trim().length > 0, "Endpoint instance is empty");
+  assert(options.pool.trim().length > 0, "Endpoint Provider Pool is empty");
+  assert(options.capabilities.length > 0, "Endpoint package declares no capability");
+  assert(options.actions === undefined || options.actionLimits === undefined,
+    "Endpoint package must choose actions or actionLimits, not both");
+  const keys = options.capabilities.map((item) => refKey(item.capability));
+  assert(new Set(keys).size === keys.length, "Endpoint package repeats a capability");
+  const capacities = options.capabilities.map((item) => item.capacity ?? item.capability.name);
+  assert(capacities.every((capacity) => capacity.trim().length > 0), "Endpoint package capacity class is empty");
+  if (options.pricing?.kind === "page") {
+    let url: URL | undefined;
+    try { url = new URL(options.pricing.url); } catch { url = undefined; }
+    assert(url?.protocol === "https:", "Endpoint pricing page must be an HTTPS URL");
+  }
+  const capacityConcurrency = new Map<string, number>();
+  for (const capability of options.capabilities) {
+    assert(capability.transient !== true || capability.lifecycle === "immediate",
+      `Endpoint capability ${refKey(capability.capability)} cannot be transient and asynchronous`);
+    const capacity = capability.capacity ?? capability.capability.name;
+    const concurrency = positiveInteger(
+      capability.maxConcurrency ?? options.defaultConcurrency ?? 1,
+      `${capability.capability.name} maxConcurrency`,
+    );
+    const previous = capacityConcurrency.get(capacity);
+    assert(previous === undefined || previous === concurrency,
+      `Endpoint package capacity ${capacity} has conflicting concurrency limits`);
+    capacityConcurrency.set(capacity, concurrency);
+  }
+  const credentials = Object.fromEntries(Object.entries(options.credentials ?? {})
+    .sort(([left], [right]) => left.localeCompare(right))
+    .map(([slot, ref]) => {
+      assert(slot.trim().length > 0, "Endpoint credential slot is empty");
+      verifyCredentialRef(ref);
+      return [slot, structuredClone(ref)];
+    }));
+  const credentialInputs = options.credentialInputs ?? {};
+  for (const slot of Object.keys(credentialInputs)) {
+    assert(slot in credentials, `Endpoint credential input ${slot} has no configured CredentialRef`);
+  }
+  const credentialDescriptions = Object.entries(credentials).map(([slot, ref]) => {
+    const input = credentialInputs[slot];
+    const label = input?.label ?? slot;
+    assert(label.trim().length > 0, `Endpoint credential ${slot} label is empty`);
+    const kind = input?.kind ?? "secret";
+    assert(kind === "secret" || kind === "json", `Endpoint credential ${slot} kind is invalid`);
+    return {
+      endpoint: options.instance,
+      slot,
+      label,
+      kind,
+      ref: structuredClone(ref),
+      ...(input?.acquisition === undefined ? {} : { acquisition: structuredClone(input.acquisition) }),
+    } satisfies EndpointCredentialDescription;
+  });
+  const fulfills = options.capabilities.map((item) => ({
+    capability: structuredClone(item.capability),
+    returns: structuredClone(item.returns),
+    ...(item.supports === undefined ? {} : { supports: item.supports }),
+    ...(item.transient === true ? { transient: true as const } : {}),
+  }));
+  const instance = {
+    id: options.instance,
+    pool: options.pool,
+  };
+  const actions = options.actions ?? (options.actionLimits === undefined ? undefined : actionResourceClaims(options.pool, options.actionLimits));
+  const offers: readonly EndpointOffer[] = fulfills.map((item) => ({
+    ...item,
+    endpoint: options.instance,
+  }));
+  return {
+    instance,
+    offers,
+    credentials: credentialDescriptions,
+    ...(options.pricing === undefined ? {} : { pricing: structuredClone(options.pricing) }),
+    ...(options.readPricing === undefined ? {} : { readPricing: options.readPricing }),
+    install(registry) {
+      for (const capability of options.capabilities) {
+        const capacity = capability.capacity ?? capability.capability.name;
+        const authorityConcurrency = positiveInteger(options.defaultConcurrency ?? 1, "defaultConcurrency");
+        const exactConcurrency = positiveInteger(
+          capability.maxConcurrency ?? authorityConcurrency,
+          `${capacity} maxConcurrency`,
+        );
+        const common: EndpointRegistrationOptions = {
+          pool: options.pool,
+          ...(capability.supports === undefined ? {} : { supports: capability.supports }),
+          ...(capability.transient === true ? { transient: true } : {}),
+          credentials,
+          scheduling: {
+            ...(capability.lifecycle !== "asynchronous" || actions === undefined ? {} : { actions }),
+            ...(capability.unitsForRequest === undefined ? {} : { unitsForRequest: capability.unitsForRequest }),
+            resources: [
+              {
+                id: `pool:${options.pool}`,
+                limit: authorityConcurrency,
+              },
+              {
+                id: `capacity:${options.pool}/${capacity}`,
+                limit: exactConcurrency,
+              },
+              ...(capability.resources ?? []),
+            ],
+          },
+        };
+        if (capability.lifecycle === "immediate") {
+          registry.registerImmediateEndpoint(
+            options.instance,
+            capability.capability,
+            capability.returns,
+            capability.handler,
+            common,
+          );
+        } else {
+          registry.registerAsyncEndpoint(
+            options.instance,
+            capability.capability,
+            capability.returns,
+            capability.endpoint,
+            common,
+          );
+        }
+      }
+    },
+  };
+}
+
+export function wakeAfter(
+  handle: CanonicalValue,
+  delayMs: number,
+  now = Date.now(),
+  progress?: OperationProgress,
+): {
+  readonly status: "pending";
+  readonly handle: CanonicalValue;
+  readonly wakeAt: number;
+  readonly progress?: OperationProgress;
+} {
+  assert(Number.isSafeInteger(delayMs) && delayMs >= 0, "wake delay must be a non-negative safe integer");
+  assert(Number.isSafeInteger(now) && now >= 0, "current time must be a non-negative epoch millisecond");
+  return {
+    status: "pending",
+    handle,
+    wakeAt: now + delayMs,
+    ...(progress === undefined ? {} : { progress }),
+  };
+}

package/packages/estimate/README.md

@@ -0,0 +1,32 @@
+# `@hypit/estimate`
+
+Provider-free speech-duration measurement, used at creation time.
+
+A duration is the author's decision, written as a literal on the element that needs it:
+`<seedance:TextVideo … duration="8"/>`, `<media:StillVideo … duration="6"/>`. This package is how the
+author arrives at that number before writing it. It counts pronunciation units of a Text with a
+language-aware delivery density (English dictionary words use CMUdict; unknown words use a
+deterministic spelling fallback), then applies optional padding and the selected rounding. The Text remains
+authoritative: the estimator never invents how numbers, names or acronyms are pronounced.
+
+```bash
+hypit measure main.svml --segment opening --language en --pace normal
+hypit measure --text "Video editing begins with meaning." --language en --pace normal --rounding ceil
+```
+
+The English pace presets are `slow = 4.2`, `normal = 4.6` and `fast = 5.0` syllables per second; a
+positive numeric `rate` replaces `pace`. `round` selects the nearest whole second, `ceil` a
+never-shorter one, `none` keeps the fraction.
+
+The estimate reports the time the wording needs at that delivery. Use it to decide whether a passage
+needs merging, fuller wording, tightening, or splitting, then choose the request duration with the
+selected model's supported values in mind.
+
+`SpeechEstimatePolicy` holds the language, pace or rate, rounding and optional padding used by the
+measurement API. `speechEstimatePolicyFromRecipe` reads those values from a Recipe for package authors.
+The measurement produces a duration estimate for authoring; actual word positions come from the
+performed media's semantic preparation.
+
+```ts
+import { estimateSpeechDuration, sealSpeechEstimatePolicy, speechEstimatePolicyFromRecipe } from "@hypit/estimate";
+```

package/packages/estimate/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@hypit/estimate",
+  "version": "0.0.0-dev",
+  "license": "SEE LICENSE IN LICENSE",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "hypit": {
+    "activation": "./src/activation.ts"
+  },
+  "dependencies": {
+    "@hypit/protocol": "workspace:*",
+    "@hypit/speech": "workspace:*",
+    "@hypit/svs": "workspace:*",
+    "@hypit/text": "workspace:*",
+    "cmu-pronouncing-dictionary": "3.0.0"
+  }
+}

package/packages/estimate/src/activation.ts

@@ -0,0 +1,11 @@
+import { estimateManifest } from "./index.js";
+
+/** The package declares one graph type and no Surface, Producer or Need: measuring is creation-time work. */
+export const hypitPackage = {
+  format: "hypit.node-package@1" as const,
+  modules: [{ manifest: estimateManifest }],
+  components: [],
+  hostFacets: [],
+};
+
+export default hypitPackage;