@volter/twin-world 0.1.0 → 0.1.2

package/src/fixture-env.ts

@@ -0,0 +1,207 @@
+// World fixture env — STRUCTURALLY VALID fake credentials for the env a world hands the app
+// under test.
+//
+// The failure this fixes (feature-sweep): fake env values in a world config are hand-authored
+// scalars (`sk_test_fake_…`), which is exactly right for credentials an SDK treats as an opaque
+// bearer token — the twin accepts anything, the value's SHAPE never matters. But some
+// credentials are PARSED AND USED CLIENT-SIDE before any request leaves the process: a Google
+// service-account JSON is loaded by google-auth-library, which signs a JWT assertion with its
+// `private_key` locally and only then calls the (twin-served) token endpoint. A faked
+// `GOOGLE_VERTEX_JSON` lacking `private_key` therefore throws inside the app and blocks every
+// Google-auth path — no twin ever sees a request. The fix is not a smarter twin; it is a
+// STRUCTURALLY VALID fake: all required fields, and a REAL throwaway RSA key the client library
+// can genuinely sign with. The signature is verified by nothing (the twin's token endpoint
+// accepts any well-formed assertion), so a throwaway key is safe by construction — it
+// corresponds to no real account anywhere.
+//
+// THE PATTERN (document + reuse for any future structurally-parsed credential):
+//   1. find what the CLIENT SDK does with the value before the first network call;
+//   2. fake every field it reads, with material that genuinely works (a real keypair, a
+//      well-formed JWT, …) — never placeholder strings in cryptographic positions;
+//   3. keep the fake obviously fake in the IDENTIFYING fields (project id, email) so it can
+//      never be mistaken for a real credential;
+//   4. mint keys per process (throwaway), never commit them — a committed key looks real to
+//      scanners and to attackers alike.
+// Precedents in-repo: gcs-sdk.integration.test.ts (throwaway RSA key lets the unmodified
+// @google-cloud/storage SDK sign V4 URLs offline), clerk-jwt.ts / fal-webhooks.ts (generated
+// signing keypairs).
+import { generateKeyPairSync } from 'node:crypto';
+
+export type FakeServiceAccountOptions = {
+  /** identifying project id — defaults to an unmistakably fake twin project. */
+  projectId?: string;
+  /** client_email — defaults to a twin address under the fake project. */
+  clientEmail?: string;
+};
+
+// RSA-2048 generation costs ~100ms — mint ONCE per process and reuse (the clerk-worker
+// baked-key history is the cautionary precedent for per-call generation cost). Throwaway by
+// design: never persisted, never committed, corresponds to no real account.
+let cachedPrivateKeyPem: string | undefined;
+function throwawayPrivateKeyPem(): string {
+  if (!cachedPrivateKeyPem) {
+    const { privateKey } = generateKeyPairSync('rsa', { modulusLength: 2048 });
+    cachedPrivateKeyPem = privateKey.export({ type: 'pkcs8', format: 'pem' }).toString();
+  }
+  return cachedPrivateKeyPem;
+}
+
+/**
+ * A STRUCTURALLY VALID fake Google service-account JSON: every field a real
+ * `service_account` key file carries, with a REAL throwaway RSA private key — so
+ * google-auth-library (and every SDK built on it: Vertex, GCS, @ai-sdk/google-vertex, …)
+ * loads it, signs its JWT assertion locally, and proceeds to the twin-served token
+ * endpoint instead of throwing before the first request.
+ */
+export function fakeGoogleServiceAccountJson(opts: FakeServiceAccountOptions = {}): string {
+  const projectId = opts.projectId ?? 'twin-project';
+  const clientEmail = opts.clientEmail ?? `twin-fake@${projectId}.iam.gserviceaccount.com`;
+  return JSON.stringify(
+    {
+      type: 'service_account',
+      project_id: projectId,
+      private_key_id: 'twinfake0000000000000000000000000000dead',
+      private_key: throwawayPrivateKeyPem(),
+      client_email: clientEmail,
+      client_id: '000000000000000000000',
+      auth_uri: 'https://accounts.google.com/o/oauth2/auth',
+      token_uri: 'https://oauth2.googleapis.com/token',
+      auth_provider_x509_cert_url: 'https://www.googleapis.com/oauth2/v1/certs',
+      client_x509_cert_url: `https://www.googleapis.com/robot/v1/metadata/x509/${encodeURIComponent(clientEmail)}`,
+      universe_domain: 'googleapis.com',
+    },
+    null,
+    2,
+  );
+}
+
+/**
+ * A STRUCTURALLY VALID fake Google OAUTH WEB-CLIENT JSON — the `{"web":{...}}` shape a
+ * Google-Cloud-console "OAuth client" download has, which is what OAuth-APP consumers parse
+ * (cal.com: `JSON.parse(GOOGLE_API_CREDENTIALS)?.web`, then a zod schema over
+ * client_id/client_secret/redirect_uris). This is a DIFFERENT credential species from the
+ * service-account JSON above: faking the SA shape for these names passes the consumer's
+ * "valid JSON" check and then yields `?.web === undefined`, so the integration silently
+ * degrades instead of erroring — the worst failure mode for a fake credential (Cal.com blind
+ * run, friction #4). No cryptographic material is needed: the client secret is an opaque
+ * bearer the twin accepts; identifying fields are unmistakably fake.
+ */
+export function fakeGoogleOAuthClientJson(): string {
+  return JSON.stringify(
+    {
+      web: {
+        client_id: '000000000000-twinfake.apps.googleusercontent.com',
+        project_id: 'twin-project',
+        auth_uri: 'https://accounts.google.com/o/oauth2/auth',
+        token_uri: 'https://oauth2.googleapis.com/token',
+        auth_provider_x509_cert_url: 'https://www.googleapis.com/oauth2/v1/certs',
+        client_secret: 'twin-fake-google-oauth-client-secret',
+        redirect_uris: ['http://localhost:3000/api/auth/callback/google'],
+      },
+    },
+    null,
+    2,
+  );
+}
+
+/** Does this env NAME carry an INLINE Google OAUTH-CLIENT JSON (the `{"web":{...}}` shape)?
+ *  Matches a GOOGLE stem combined with an OAuth-app marker: `API_CREDENTIALS` (cal.com's
+ *  GOOGLE_API_CREDENTIALS — the name that motivated this), `OAUTH_*`, or `*_CLIENT_JSON` /
+ *  `CLIENT_CREDENTIALS` forms. Deliberately NOT the SERVICE_ACCOUNT-marked names, NOT the
+ *  GCP/GCLOUD/VERTEX stems (cloud-platform credentials are service accounts), and NOT bare
+ *  GOOGLE_CREDENTIALS (ambiguous; historically ADC, i.e. SA-shaped — kept on the SA fake). */
+export function isGoogleOAuthClientEnvName(name: string): boolean {
+  const n = name.toUpperCase();
+  if (!/(^|_)GOOGLE(_|$)/.test(n)) return false;
+  if (n === 'GOOGLE_APPLICATION_CREDENTIALS') return false; // a path, not inline JSON
+  if (/SERVICE_ACCOUNT/.test(n)) return false; // explicitly SA-shaped
+  return /(API_CREDENTIALS|OAUTH_(CLIENT|CREDENTIALS|JSON)|CLIENT_(JSON|CREDENTIALS))/.test(n);
+}
+
+/** Does this env NAME carry an INLINE Google service-account JSON (the structurally-parsed
+ *  kind)? Matches a Google-ish stem (GOOGLE/GCP/GCLOUD/VERTEX) combined with a JSON/
+ *  credentials/service-account marker — e.g. GOOGLE_VERTEX_JSON, GCP_SERVICE_ACCOUNT_JSON,
+ *  GOOGLE_APPLICATION_CREDENTIALS_JSON. Deliberately NOT GOOGLE_MAPS_API_KEY (opaque scalar),
+ *  NOT GOOGLE_APPLICATION_CREDENTIALS (a FILE PATH — point it at a file whose contents
+ *  come from fakeGoogleServiceAccountJson instead), and NOT the OAuth-client names above —
+ *  those need the `{"web":{...}}` shape, not SA JSON. */
+export function isGoogleServiceAccountEnvName(name: string): boolean {
+  const n = name.toUpperCase();
+  if (!/(^|_)(GOOGLE|GCP|GCLOUD|VERTEX)(_|$)/.test(n)) return false;
+  if (n === 'GOOGLE_APPLICATION_CREDENTIALS') return false; // a path, not inline JSON
+  if (isGoogleOAuthClientEnvName(name)) return false; // OAuth-client shape, handled separately
+  return /(_JSON$|_JSON_|CREDENTIALS|SERVICE_ACCOUNT)/.test(n);
+}
+
+/**
+ * A structurally valid fake value for one env NAME. Google OAuth-client-shaped names get the
+ * `{"web":{...}}` client JSON; Google service-account-shaped names get the full SA JSON (real
+ * throwaway key); endpoint-shaped names get a parseable vendor-host URL that the injector can
+ * claim; everything else gets an unmistakably fake opaque scalar (`twin-fake-<name>`), which is
+ * sufficient for bearer-token credentials because the twin accepts any value — shape only
+ * matters when the CLIENT parses it (rule of thumb: if a blind adoption run shows an SDK throwing
+ * on a fake before any request is made, that env var needs a structural fake; add its rule here).
+ */
+/** Endpoint values whose SHAPE is consumed before the first network call.
+ *
+ * `new URL(value)` runs inside each client SDK before the injector can see a request, so an opaque
+ * `twin-fake-*` scalar fails even though the vendor is otherwise perfectly intercepted. These
+ * values are deliberately real-vendor-HOST-SHAPED but credential-free: the injector claims the
+ * hostname and sends the request to the local twin, while the slug remains unmistakably fake.
+ *
+ * Like CREDENTIAL_SHAPES below, this is duplicated kernel data with an explicit canonical source:
+ * world-runtime must not import a pack, and the tests pin every value against the injector's actual
+ * VENDOR_HOSTS predicate so either side changing makes the contract fail loudly. */
+const ENDPOINT_SHAPES: Array<{ match: RegExp; value: string; source: string }> = [
+  {
+    match: /(^|_)UPSTASH_REDIS_REST_URL$/,
+    value: 'https://twin-fake.upstash.io',
+    source: 'packages/twin/control-plane/inject.cjs VENDOR_HOSTS.upstashredis',
+  },
+  {
+    match: /(^|_)UPSTASH_VECTOR_REST_URL$/,
+    value: 'https://twin-fake-us1-vector.upstash.io',
+    source: 'packages/twin/control-plane/inject.cjs VENDOR_HOSTS.upstashvector',
+  },
+  {
+    match: /(^|_)TINYBIRD_API_URL$/,
+    value: 'https://api.tinybird.co',
+    source: 'packages/twin/control-plane/inject.cjs VENDOR_HOSTS.tinybird',
+  },
+];
+
+/** Credentials whose SHAPE the receiving twin actually checks.
+ *
+ * The generic `twin-fake-<name>` value is inert everywhere it lands — except at a twin that
+ * validates its own vendor's key format. Then the world is fully covered and the app still gets a
+ * 401, which reads as "the twin doesn't work" and is the most confusing failure this system can
+ * produce (measured: it cost two of four subjects a clean boot in PROOF-2026-08-20.md, finding F3).
+ * A minted fake must satisfy the twin that will receive it — the minter and the twin are two halves
+ * of one contract.
+ *
+ * These literals are DUPLICATED from the packs on purpose: the kernel must not import a pack
+ * (ARCHITECTURE.md). Each entry names its source so the pair can be re-checked by hand. */
+const CREDENTIAL_SHAPES: Array<{ match: RegExp; value: (name: string) => string; source: string }> = [
+  // A Discord bot token is three dot-separated base64 segments; a library parses the first for the
+  // application id, so a structurally wrong fake breaks before any call reaches the twin.
+  { match: /(^|_)DISCORD_[A-Z0-9_]*(TOKEN|SECRET)$/, value: () => `${btoa('1'.repeat(18)).replace(/=+$/, '')}.Gtwinf.${'t'.repeat(38)}`, source: 'a Discord bot token: three dot-separated base64 segments, the first the application id' },
+  // resend-twin.ts enforces bearer auth of the form `re_<...>` whenever a key is presented.
+  { match: /(^|_)RESEND_[A-Z0-9_]*(KEY|TOKEN|SECRET)$/, value: (name) => `re_twinfake_${name.toLowerCase().replace(/_/g, '')}`, source: 'packages/twin/resend/src/resend-twin.ts' },
+  // tinybird-twin.ts accepts exactly one admin token, TINYBIRD_ADMIN_TOKEN = 'p.twin_admin_token'.
+  { match: /(^|_)TINYBIRD_[A-Z0-9_]*(KEY|TOKEN)$/, value: () => 'p.twin_admin_token', source: 'packages/twin/tinybird/src/tinybird-twin.ts' },
+];
+
+export function fakeEnvValue(name: string): string {
+  if (isGoogleOAuthClientEnvName(name)) return fakeGoogleOAuthClientJson();
+  if (isGoogleServiceAccountEnvName(name)) return fakeGoogleServiceAccountJson();
+  for (const shape of ENDPOINT_SHAPES) if (shape.match.test(name)) return shape.value;
+  for (const shape of CREDENTIAL_SHAPES) if (shape.match.test(name)) return shape.value(name);
+  const slug = name.toLowerCase().replace(/_/g, '-');
+  // A URL-shaped name must be faked as a URL (F4). An SDK handed `twin-fake-x` where it expects an
+  // endpoint throws while CONSTRUCTING its client — before it ever issues the request the world
+  // could have intercepted, so the failure looks like a twin bug and no ledger entry exists to
+  // contradict that. `.invalid` is reserved (RFC 2606) and never resolves, so an untwinned vendor
+  // still fails — but as an unreachable HOST, which the diagnostics can name.
+  if (/(^|_)(URL|URI|ENDPOINT|HOST)$/.test(name)) return `https://${slug}.invalid`;
+  return `twin-fake-${slug}`;
+}

package/src/host-cli.ts

@@ -1,4 +1,5 @@
 #!/usr/bin/env bun
+import { keepProcessAlive } from '@volter/twin/lifecycle';
 // volter-world-host: run a set of twins co-located in this single process. The world
 // runtime spawns ONE of these (instead of one bin per twin) when a world selects
 // 'colocated'/'worker' isolation. Each twin is named by a module specifier + export so
@@ -83,4 +84,4 @@ process.stdout.write(`host ready (${specs.length} twins, isolation=${isolation})
 const shutdown = async () => { await host.stop(); process.exit(0); };
 process.on('SIGTERM', shutdown);
 process.on('SIGINT', shutdown);
-await new Promise(() => {});
+await keepProcessAlive();

package/src/host-worker.ts

@@ -7,8 +7,8 @@ import type { ColocatedTwinSpec } from './host.ts';
 
 const spec = workerData as ColocatedTwinSpec;
 
-type TwinServer = { port: number; stop: () => void };
-type TwinServerFactory = (opts: { port?: number; root?: string; readOnly?: boolean }) => TwinServer;
+type TwinServer = { port: number; stop: () => void | Promise<void> };
+type TwinServerFactory = (opts: { port?: number; root?: string; readOnly?: boolean }) => TwinServer | Promise<TwinServer>;
 
 const mod = (await import(spec.module)) as Record<string, unknown>;
 const factory = mod[spec.export] as TwinServerFactory | undefined;
@@ -16,7 +16,8 @@ if (typeof factory !== 'function') {
   throw new Error(`Twin "${spec.id}": ${spec.module} has no factory export "${spec.export}"`);
 }
 
-const server = factory({ port: spec.port, root: spec.root, readOnly: spec.readOnly });
+// Awaited: an async factory (fly) must post `ready` only once its listener is bound.
+const server = await factory({ port: spec.port, root: spec.root, readOnly: spec.readOnly });
 parentPort?.postMessage({ type: 'ready', port: server.port });
 
 // The Bun.serve listener keeps this worker's event loop alive; nothing else to do.

package/src/host.ts

@@ -42,8 +42,14 @@ export type ColocatedHost = {
   stop: () => Promise<void>;
 };
 
-type TwinServer = { port: number; stop: () => void };
-type TwinServerFactory = (opts: { port?: number; root?: string; readOnly?: boolean }) => TwinServer;
+// `stop` returns void OR a promise (76 of 78 packs return Bun's async server.stop) and the
+// factory itself may be async (fly's createFlyTwinServer) — both shapes are awaited, so
+// "resolves once every twin is listening" is true for async factories and shutdown actually
+// WAITS instead of fire-and-forgetting (§9 skeptic finding M1, 2026-08-31: an async factory
+// made host.stop() throw `s.stop is not a function`, turning every SIGTERM into downWorld's
+// SIGKILL escalation for the whole world).
+type TwinServer = { port: number; stop: () => void | Promise<void> };
+type TwinServerFactory = (opts: { port?: number; root?: string; readOnly?: boolean }) => TwinServer | Promise<TwinServer>;
 
 async function loadFactory(spec: ColocatedTwinSpec): Promise<TwinServerFactory> {
   const mod = (await import(spec.module)) as Record<string, unknown>;
@@ -56,6 +62,11 @@ async function loadFactory(spec: ColocatedTwinSpec): Promise<TwinServerFactory>
 
 const workerEntry = new URL('./host-worker.ts', import.meta.url);
 
+/** Per-twin stop budget inside host.stop(). Must stay comfortably under downWorld's 5s
+ *  SIGTERM→SIGKILL grace (DOWN_GRACE_MS_DEFAULT): the host must reach process.exit(0) even
+ *  when a twin's stop hangs, or the whole co-located world dies by SIGKILL. */
+const STOP_TIMEOUT_MS = 3000;
+
 /**
  * Start a co-located host. Resolves once every twin is listening. The returned `stop()`
  * tears the whole host down (all servers / all workers).
@@ -86,7 +97,7 @@ export async function startColocatedHost(
     const servers: TwinServer[] = [];
     for (const spec of specs) {
       const factory = await loadFactory(spec);
-      servers.push(factory({ port: spec.port, root: spec.root, readOnly: spec.readOnly }));
+      servers.push(await factory({ port: spec.port, root: spec.root, readOnly: spec.readOnly }));
     }
     return {
       isolation,
@@ -94,7 +105,18 @@ export async function startColocatedHost(
       stop: async () => {
         process.off('unhandledRejection', onRejection);
         process.off('uncaughtException', onUncaught);
-        for (const s of servers) s.stop();
+        // EVERY stop is invoked, IN PARALLEL, each under its own timeout, and no outcome —
+        // rejection, hang, or slowness — can prevent the others or wedge host.stop() itself.
+        // The awaited-sequential first cut re-created the SIGKILL escalation it was fixing
+        // through a new door (§9 round two H2, 2026-08-31: one pending/throwing stop — fly's
+        // cleanup throws on a failed container removal — left siblings unstopped and the host
+        // ignoring SIGTERM forever). The bound stays under downWorld's 5s SIGKILL grace.
+        await Promise.allSettled(servers.map((s) =>
+          Promise.race([
+            Promise.resolve().then(() => s.stop()),
+            new Promise((resolveTimeout) => setTimeout(resolveTimeout, STOP_TIMEOUT_MS).unref?.()),
+          ]),
+        ));
       },
     };
   }

package/src/index.ts

@@ -9,6 +9,9 @@ export type {
   WorldExternalDiscover,
   WorldExternalDiscoverSource,
   WorldExternalReadyWhen,
+  WorldRunOutcome,
+  WorldRunRecord,
+  WorldResourceRequirements,
 } from './schema.ts';
 export { loadWorldConfig, resolveConfigPath } from './configs.ts';
 export {
@@ -16,6 +19,8 @@ export {
   downWorld,
   listWorlds,
   statusWorld,
+  planWorldActions,
+  reviewWorldActions,
   doctorWorld,
   runWithWorldEnv,
   activateScript,
@@ -28,15 +33,106 @@ export {
   shareWorldServices,
   unshareWorld,
   urlsWorld,
+  urlWorld,
 } from './runtime.ts';
+// `volter-world app-url` — the recorded, queryable app endpoint of an instance (see app-url.ts).
+export { appUrlFile, appUrlUnsetMessage, detectAppUrl, readAppUrl, setAppUrl } from './app-url.ts';
+export type { AppUrlRecord, AppUrlSource } from './app-url.ts';
+export { tailWorldActions } from './tail.ts';
+export type { TailWorldOptions } from './tail.ts';
+// the changeset primitive + the diff verb (docs/OPERATIONAL_VCS.md v0) and the operational-PR
+// contract over it (v1: verify/approve/status). World-side glue only — markers, deltas, content
+// hashing, replay, verifier evaluation and approval binding live in @volter/twin's control plane.
 export {
-  checkDockerRuntime,
+  approveWorldChangeset,
+  createWorldChangeset,
+  diffWorld,
+  EPHEMERAL_VERIFY_TARGET,
+  findWorldChangeset,
+  listWorldChangesets,
+  listWorldMarks,
+  markWorld,
+  replayWorldChangeset,
+  resolveBaseMarker,
+  statusWorldChangeset,
+  verifyWorldChangeset,
+  worldChangesetsDir,
+  worldLedgers,
+  worldMarksDir,
+} from './changeset.ts';
+export type { ApproveWorldOutcome, ChangesetLocation, VerifyWorldOutcome, WorldRootOptions } from './changeset.ts';
+export {
+  checkLocalExecution,
   checkPrerequisites,
   formatPrerequisiteChecks,
 } from './prerequisites.ts';
+export { inspectProject, formatProjectInspection, projectDependencies, projectEnvNames, SDK_TWINS, workspaceDirs } from './project-inspect.ts';
+export type { ProjectInspection } from './project-inspect.ts';
+// Structurally valid fake credentials for world configs (fixture env) — see fixture-env.ts
+// for the pattern (a fake a client SDK parses/signs with must be structurally real).
+export { fakeEnvValue, fakeGoogleOAuthClientJson, fakeGoogleServiceAccountJson, isGoogleOAuthClientEnvName, isGoogleServiceAccountEnvName } from './fixture-env.ts';
+export type { FakeServiceAccountOptions } from './fixture-env.ts';
+export {
+  coverWorld,
+  detectRepoVendors,
+  envNameVendor,
+  formatCoverageReport,
+  injectorVendorKeysFor,
+  isCredentialShapedEnvName,
+  worldTwinInventory,
+} from './covers.ts';
+export type { CoverageReport, CoverageRow, CoverageStatus, CoverageOptions, RepoVendorSignals } from './covers.ts';
+// `volter-world init` — the deterministic front door: detect the repo's vendors (covers), emit a
+// world config + env file OUTSIDE the repo (fixture-env), and prove the emission with `covers`.
+export { formatInitReport, initWorld, packCatalog, planWorldInit, renderEnvFile, writeWorldInit } from './init.ts';
+export type {
+  EnvDisposition,
+  InitEnvRow,
+  InitInfraStub,
+  InitOptions,
+  InitPlan,
+  InitResult,
+  InitVendorPlan,
+  InitWiring,
+} from './init.ts';
+export {
+  deriveWorldManifest,
+  findWorldRefFile,
+  isRemoteWorldRef,
+  resolveWorldRef,
+  WORLD_REF_FILE,
+  worldManifest,
+} from './attach.ts';
+export type { ResolvedWorldRef, WorldManifest, WorldRefSource } from './attach.ts';
+export {
+  parseSni,
+  readReflectRoutes,
+  reflectRoutesPath,
+  reflectManifestPath,
+  readReflectManifest,
+  writeReflectManifest,
+  clearReflectManifest,
+  composeOverrideForReflect,
+  splitDockerComposeArgs,
+  dockerComposeWithOverride,
+  CA_TRUST_ENV,
+  ATTACHED_CA_PATH,
+  startReflectFront,
+  startReflectResolver,
+  writeReflectRoutes,
+} from './reflect.ts';
+export type { ReflectFrontHandle, ReflectFrontOptions, ReflectManifest, ReflectResolverHandle, ReflectResolverOptions } from './reflect.ts';
 export type {
   PrerequisiteCheck,
   PrerequisiteId,
 } from './prerequisites.ts';
 export { startColocatedHost } from './host.ts';
 export type { ColocatedTwinSpec, ColocatedHost, HostIsolation } from './host.ts';
+export {
+  advertiseWorldManifest,
+  fetchRemoteManifest,
+  MANIFEST_PATH,
+  remoteAttachEnv,
+  startManifestServer,
+} from './serve.ts';
+export type { ManifestServerHandle, ManifestServerOptions } from './serve.ts';