@volter/world-runtime 2.0.54 → 3.0.0

package/dist/src/init.d.ts

@@ -8,7 +8,9 @@ export type InitWiring =
  | 'app-read'
 /** no injector entry and no endpoint env: the SDK is pointed at the twin by explicit client config */
  | 'explicit-config'
-/** detected vendor with no `packages/twin/<vendor>` pack in the catalog — nothing to emit */
+/** the vendor's own open-source server runs as the World's service (VENDOR_SERVER_BACKINGS) */
+ | 'backing'
+/** detected vendor with no vendor pack in the catalog — nothing to emit */
  | 'no-pack';
 export type InitVendorPlan = {
     vendor: string;
@@ -21,17 +23,30 @@ export type InitVendorPlan = {
     service: WorldServiceConfig | null;
     /** why this wiring — printed in the report and embedded in the service's `//` note */
     note: string;
+    /** the source init chose the pack from (architecture, "The catalog: where twins come from"): where it comes from, its
+     *  protocol and its version */
+    source?: {
+        kind: 'checkout' | 'installed';
+        version?: string;
+    };
 };
 /** What `init` did with one env NAME found in the repo's example env files. */
 export type EnvDisposition = 
 /** credential-shaped → replaced by a structurally valid fake (never the committed value) */
 'faked'
+/** a credential the vendor's twin issues at boot → `$issue:<vendor>` (the twin refuses a key it did not make) */
+ | 'issued'
 /** non-credential app config → the example value copied verbatim */
  | 'kept'
 /** infra connection string → points at a World-managed infrastructure service */
  | 'compose'
 /** infra connection string → a documented placeholder the operator fills in */
  | 'placeholder'
+/** the application's own origin → `$app-url`, the address its booter records, resolved when it attaches */
+ | 'app-origin'
+/** a detected vendor's endpoint pointed at a local stand-in server (a garage or MinIO for S3) → left unset, so the SDK
+ *  addresses the vendor's own host, which the World routes to its twin */
+ | 'stand-in'
 /** neither credential-shaped nor valued: the operator has to decide */
  | 'unknown';
 export type InitEnvRow = {
@@ -114,10 +129,12 @@ export type InitPlan = {
     }>;
     /** pack `defaults/` files copied into the world dir (TWIN-PROGRAMMING-MODEL: default
      *  reasonable — visible starter seeds/handlers, ownership transfers on copy). */
+    /** `from` is copied byte for byte; `content` (a runner init writes for a protocol-3 pack's seed data) is written as given. */
     defaultsCopies: Array<{
         vendor: string;
-        kind: 'handlers' | 'seed';
-        from: string;
+        kind: 'handlers' | 'seed' | 'seed-data';
+        from?: string;
+        content?: string;
         to: string;
     }>;
     /** emitted when any pack ships a default seed: the one explicit entry point + story skeleton */
@@ -158,7 +175,7 @@ export type InitResult = {
 };
 export type InitOptions = {
     /** the WORLD root: where the emitted config boots from, and where the catalog is resolved —
-     *  this checkout's `packages/twin` when init runs here, else the `@volter/twin-<vendor>`
+     *  the sibling pack repository when init runs here, else the `@volter/twin-<vendor>`
      *  packages installed above it (docs/concepts/worlds.md#the-config-and-the-running-world). Defaults to the
      *  application repo. */
     root?: string;
@@ -173,39 +190,29 @@ export type InitOptions = {
     bare?: string;
 };
 /** The twins available at `root`, sorted — a deterministic input (catalog.ts: this checkout's
- * `packages/twin/<vendor>/` dirs, or the `@volter/twin-<vendor>` packages installed above root). */
+ * vendor directories in the pack repository, or the `@volter/twin-<vendor>` packages installed above root). */
 export declare function packCatalog(root: string): string[];
 /**
- * The REAL endpoint env names for packs the injector cannot intercept — the other half of
- * `scripts/vendor-hosts.test.ts`'s descriptor hostsNone ruling. That allowlist states WHY each pack
- * has no VENDOR_HOSTS entry; this table states WHAT to wire instead, using the env var the vendor's
- * own SDK documents. Every entry is grounded in the SDK, not invented:
- *
- *   inngest                   `INNGEST_BASE_URL` (+ `INNGEST_EVENT_API_BASE_URL` for the event API)
- *                             — inngest@4's own apiBaseUrl/eventBaseUrl getters.
- *   ai-gateway                `AI_GATEWAY_BASE_URL` — `@ai-sdk/gateway`'s baseURL env.
- *   livekit                   `LIVEKIT_URL` as a ws:// template — the media plane is a WebSocket
- *                             URL the SDK takes as its first constructor argument.
- *
- * A pack that is base-URL-configurable but has NO conventional env var (algolia, pinecone,
- * replicate, fal, twilio, sendblue, figma, notion) is deliberately ABSENT: it gets a service
- * with no endpoint env at all, and the proof reports it UNINTERCEPTABLE. Inventing a
- * `<VENDOR>_BASE_URL` for it would make `covers` call the world covered (any app-read env counts)
- * while the app, which reads no such var, still talks to the real vendor — the exact class of lie
- * the proof exists to catch.
+ * The endpoint env for a pack the injector cannot intercept and whose descriptor cannot state it as `endpointEnv`
+ * (which receives the twin's URL): a raw protocol, whose client is pointed by host and port. Every name is one a real
+ * client documents. A pack with no such env is absent: it gets a service with no endpoint env at all, and the proof
+ * reports it UNINTERCEPTABLE. Inventing a `<VENDOR>_BASE_URL` for it would make `covers` call the world covered while
+ * the app, which reads no such var, still talks to the real vendor.
  */
 export declare const APP_READ_ENDPOINT_ENV: Record<string, {
     injectEnv?: string;
     injectEnvTemplates?: Record<string, string>;
     note: string;
 }>;
+export { VENDOR_SERVER_BACKINGS } from './backings.js';
 /** Render the private managed-infrastructure definition — deterministic, with no absolute paths.
  * Only meaningful when `plan.compose` is non-empty (writeWorldInit skips it otherwise). */
 export declare function renderComposeFile(plan: InitPlan): string;
 export type ParsedEnvEntry = {
     name: string;
     value: string;
-    source: string;
+    source: string; /** several dirs define it differently: each `source=value` */
+    conflict?: string[];
 };
 /** Parse one dotenv-ish file into ordered NAME/value pairs. Deliberately conservative: the same
  * `NAME=` line shape `projectEnvNames` detects, plus quote stripping, so the two views of a repo's
@@ -224,6 +231,9 @@ export declare const STATE_GITIGNORE = "# Volter: the world's running state and
 export declare function writeWorldInit(plan: InitPlan, options?: {
     force?: boolean;
 }): void;
+/** The runner of a protocol-3 pack's default data (its `src/semantics/seed.ts`, copied beside it as `<vendor>.data.ts`):
+ *  each call, in order, against the twin at its `<VENDOR>_TWIN_URL`, a refusal stopping the seed with the twin's answer. */
+export declare function seedCallsRunner(vendor: string): string;
 /**
  * Plan, emit, and PROVE. The coverage proof runs against the just-written config (by path, so it
  * reads exactly the bytes on disk rather than the in-memory plan) — `ok` is the proof's verdict and