@volter/world-runtime 3.0.38 → 3.0.40

package/dist/src/runtime.d.ts

@@ -1,5 +1,7 @@
+import type { SpawnIdentity } from './process-receipt.js';
+import { type WorldNetwork } from '@volter/world-core/network-policy';
 import { type CaTrustInputs } from './ca-trust.js';
-import type { WorldInstance, WorldIsolation, WorldMode, WorldRunOutcome } from './schema.js';
+import type { WorldInstance, WorldIsolation, WorldMode, WorldRunOutcome, WorldServiceConfig } from './schema.js';
 /** The World's events file: every service's start and end, and the World's own stops, one JSON line each. */
 export declare function worldEventsPath(logs: string): string;
 export type UpWorldOptions = {
@@ -19,6 +21,8 @@ export type UpWorldOptions = {
      *  episodes survive the boot; logs and the pid file start clean. Never the default: `up` starts
      *  clean, and the world dir is the reproducible story. */
     keepState?: boolean;
+    /** A branch's base permission: intersects both the config and the launching process. */
+    networkCeiling?: WorldNetwork;
 };
 export type ShareWorldOptions = {
     root?: string;
@@ -45,6 +49,8 @@ export type WorldDoctorReport = {
     checks: WorldDoctorCheck[];
 };
 export type RunWorldOptions = UpWorldOptions & {
+    /** the command's working directory: the caller's, as `attach` runs its command (default: the World's root) */
+    cwd?: string;
     keep?: boolean;
     verbose?: boolean;
 };
@@ -78,11 +84,20 @@ export declare function sharingClaimAlive(claim: SharingClaim): boolean;
  *  run code that is not Volter's (a World's apps, a command attached to a World, a tunnel, a dependency install) are
  *  given an environment without it. */
 export declare function withoutVaultSignIn<T extends Record<string, string | undefined>>(env: T): T;
+/** The boot permission, never a fallback to a mutable config. */
+export declare function recordedWorldNetwork(instance: WorldInstance): WorldNetwork | undefined;
+/** A stopped receipt checks byte consistency before fields are read; it is not authentication. */
+export declare function readWorldBootRecord(name: string, root: string): WorldInstance;
 export declare function admittedEnv(strip: string[] | undefined, env?: NodeJS.ProcessEnv): Record<string, string>;
 /** The names a twin of this World was to issue and did not (its door failed): kept out of every command's env, so a
  *  caller's own value (a real key in their shell) never stands in for the credential the World meant to issue. */
 export declare const UNISSUED_ENV = "VOLTER_WORLD_UNISSUED";
 export declare function saveWorldInstance(instance: WorldInstance): void;
+/** The environment an external service and its replacement infrastructure hosts run in. Shared with branching,
+ *  so both use the boot's admission, service overrides, lifecycle context and control-plane egress rules. */
+export declare function externalServiceEnv(service: WorldServiceConfig, paths: {
+    logs: string;
+}, worldEnv: Record<string, string>, stripEnv?: string[]): NodeJS.ProcessEnv;
 /**
  * THE MANAGED-DATABASE BINDING (architecture.md, managed infrastructure: the data plane's declared exception): for a
  * twin whose pack declares `managedDatabase`, the URL of the World's own managed postgres — the service its
@@ -96,16 +111,20 @@ export declare function managedDatabaseFor(vendor: string, configPath: string |
     url: string;
 } | undefined;
 export declare function upWorld(configId: string, options?: UpWorldOptions, abort?: AbortSignal): Promise<WorldInstance>;
+/** The same bounded, identity-checked retirement used by World down, for provider-owned groups.
+ * No caller may release a durable receipt when inspection or signal delivery is uncertain. */
+export declare function retireOwnedProcessGroups(records: SpawnIdentity[], graceMs?: number): Promise<void>;
 export declare function downWorld(name: string, root?: string, options?: {
     graceMs?: number;
     purge?: boolean;
-    expectedCreatedAt?: string;
+    expectedInstance?: string;
 }): Promise<{
     name: string;
     stopped: number[];
     escalated: number[];
     externalStopped: string[];
     externalErrors: string[];
+    externalAbandoned?: string[];
     notSignalled?: string[];
     purged?: string;
 }>;
@@ -149,17 +168,15 @@ export declare function shareWorldServices(name: string, options?: ShareWorldSer
  * services — SIGTERM, confirm dead (escalating to SIGKILL past the grace), and only THEN erase the
  * tunnel facts/pids. A best-effort SIGTERM with no confirmation can leave a `cloudflared` that
  * ignores SIGTERM serving the public URL forever while instance.json (and the pids file) say
- * nothing is shared — the exact "half-shared" state docs/concepts/worlds.md promises cannot exist. Stays
- * synchronous (via `killSurvivorsAfterGraceSync`) to match the existing signature/call sites
- * (the CLI does not await it). Returns the instance plus the tunnel pids that needed escalating,
+ * nothing is shared — the exact "half-shared" state docs/concepts/worlds.md promises cannot exist. Retirement awaits asynchronous birth verification. Returns the instance plus the tunnel pids that needed escalating,
  * for callers that want to report it. */
 export declare function unshareWorld(name: string, options?: {
     root?: string;
     service?: string;
     graceMs?: number;
-}): WorldInstance & {
+}): Promise<WorldInstance & {
     escalated: number[];
-};
+}>;
 export declare function doctorWorld(name: string, options?: {
     root?: string;
     verifyPublic?: boolean;