Development to production

Give the environment a canonical home

Use defineInfraEnvConfig in the filename the loader discovers:

The directory selects the environment; a custom name does not change the remote filename. Environment identifiers accept lowercase alphanumeric segments separated by hyphens, so names such as review-team are possible; the common local, staging and production enum values are conveniences, not the complete vocabulary. Follow the existing project’s discovered environment-file layout when adding another environment.

Separate the service from the data it serves

This excerpt follows Wonder Todos’ local declaration. Its other backing services and policy blocks are omitted; it is the database portion of an environment, not a complete stack recipe.

import {
  defineInfraEnvConfig, WildoEnvironment, WildoDeploymentRuntime,
  BackingServiceSource, DatabaseEngine,
} from '@wildo-ai/platform-config-lib';

export default defineInfraEnvConfig({
  environment: WildoEnvironment.LOCAL,
  runtime: WildoDeploymentRuntime.DOCKER_COMPOSE,
  publicDomain: 'localhost',
  database: { engine: DatabaseEngine.POSTGRESQL, source: BackingServiceSource.SELF },
  applicationDatabase: { engine: DatabaseEngine.POSTGRESQL },
  backingServices: {
    postgresql: {
      source: BackingServiceSource.SELF,
      host: 'localhost', port: 5432,
      database: 'wonder-todos-db',
    },
  },
});

database selects the platform’s persistence engine. applicationDatabase selects the application’s default persistence engine. backingServices.postgresql describes the supplied connection. Naming a server is not itself a request to move existing business data to it.

Ship the PostgreSQL schema with the connection change

Selecting PostgreSQL supplies a default engine and connection; it does not create the application’s tables or transfer existing records. Resource and module schema changes need reviewed migrations and an updated accepted schema baseline, shipped together with the release.

For non-platform applications, startup applies shipped PostgreSQL migrations before checking the physical tables against the resource plan. Platform services run that work in their own startup phase. An absent or incompatible table can therefore stop startup even when the connection is valid.

Follow database schema planning and migration for the workflow. The application’s application-database-migrations guidance covers migration authoring and baseline review; moving existing business data between stores is separate work.

Let each field keep its meaning

The per-kind schemas reject unrelated fields and incorrect types. defineInfraEnvConfig validates the authored shape; a valid shape still needs usable service addresses and credentials.

Regenerate at the configuration boundary

From a configured application workspace, wildo config sync projects the selected environment into runtime and deployment artifacts. Change the authored file, rather than editing generated connection values. Restart affected processes or apply the deployment through its normal lane to make the new configuration active.

For remote public services, serviceHosts and publicDomain feed the shared hostname resolver used by runtime addresses and ingress routes. Conflicting resolved hostnames are rejected. The descriptor expresses intended configuration; it is not a continuously running cluster reconciler.

Check the generated configuration before deployment

Run these from the configured application workspace with a registered production Kubernetes environment; select the environment whose application artifacts you intend to check:

wildo config sync --env=production --domain config
wildo config validate --env=production --domain manifest --deployment-artifacts

Confirm synchronization actually produced the deployment artifacts. A skip message can mean the platform is unavailable or the application credential was refused; restore platform access and application registration before retrying.

The manifest check renders infrastructure/platform Kubernetes files into a temporary directory. --deployment-artifacts also checks the saved application YAML and refuses missing or empty output. Both parse YAML and check required document fields. It leaves the persisted manifests intact and does not contact a cluster. Inspect the generated service addresses and mounts before applying them; this check establishes render consistency, not cluster admission or working credentials.

Declare a meaningful set

Adapted from the current local environment, this block belongs inside defineInfraEnvConfig. The imports and other environment fields are omitted here; BackingServiceSource comes from @wildo-ai/platform-config-lib.

backingServices: {
  postgresql: {
    source: BackingServiceSource.SELF,
    host: 'localhost', port: 5432, database: 'wonder-todos-db',
  },
  rabbitmq: {
    source: BackingServiceSource.SELF,
    host: 'localhost', port: 5672, vhost: 'wonder-todos',
  },
  s3: {
    source: BackingServiceSource.SELF, provider: 'minio',
    endpoint: 'http://localhost:9000', bucket: 'wonder-todos-local',
  },
}

The database name, broker virtual host and storage bucket identify different namespaces. The backing-service kind maps to an infrastructure capability; the runtime’s grants determine which connection material it receives. A declaration and permission to use that service are connected decisions, not the same decision.

Understand which workloads are emitted

Both Compose and Kubernetes consult selfHostsBackingService. The current omission policy is deliberate:

MongoDB’s search process follows its database’s selection. Document rendering and telemetry are not additional backing-service kinds: their configuration has its own provider/runtime path. Do not add invented gotenberg or metrics keys to this block.

Follow the generated result

The Compose generator passes inclusion flags, host ports, internal ports, networks and data paths into the platform template. Stateful service directories follow the same selection. Kubernetes derives its workload list from the same self-hosting policy, then applies its own manifest and readiness mechanics.

Generation does not establish that credentials work or that a service has started. Inspect the resolved provider, generated workload and runtime diagnosis as separate steps. The backup declaration has no concrete provider; it must not be interpreted as a backup or restore service.

Keep hosting and brand separate

This is a configuration fragment using the current schema, adapted from the production environment. Add it to the selected environment’s backingServices; account details and secrets remain outside this excerpt.

backingServices: {
  mongodb: {
    source: BackingServiceSource.MANAGED,
    provider: 'atlas',
    database: 'application-records',
  },
  rabbitmq: {
    source: BackingServiceSource.SELF,
    vhost: 'application-work',
  },
}

source selects the hosting model. provider selects a brand recognized by the provider resolver. The declaration does not create a vendor account or migrate data. Provider provisioning uses the operator authority available to the selected environment, and runtime delivery uses the generated application credentials.

Check the actual provider resolution

PostgreSQL’s unrecognized brand falls back to its generic managed entry. S3 dispatches recognized brands first and otherwise falls back by source. MongoDB has no generic managed fallback. Inspect the resolved infrastructure section of wildo-saas.lock.json after synchronization; a syntactically valid choice alone is not evidence of a supported provider.

Check what can actually execute

A resolved provider name and a lockfile entry describe a selection; neither proves that a provisioning implementation exists. The lockfile can record the authored selection even when no provider module contributes an executable plan.

The built-in provider catalog currently has a self-hosted PostgreSQL module, but no modules for its managed PostgreSQL enum entries. Those names are not a claim that Wildo provisions RDS, Cloud SQL, Neon or the other listed offerings. This does not prevent using an externally supplied PostgreSQL connection; its configuration and operational responsibility remain separate.

Separate provider resolution from workload selection

The local workload policy is shared by Compose and Kubernetes. Explicit managed cache, broker or S3 choices suppress those local workloads, even though a managed cache or broker has no provider in the resolver above. Omission retains their baseline local workloads. This distinction matters: removing a container does not prove a replacement was provisioned.

Before changing a hosting choice, check the provider connection, runtime credential, generated deployment and existing data separately. The common application contract reduces hosting-specific code; it does not remove service compatibility or migration work.

Choose the command for the intended result

From an application workspace whose local environment has already been set up:

# Start and inspect the supporting stack.
wildo local up
wildo local status

# Start the supervised application development session.
wildo local dev

local dev includes infrastructure preparation, so a normal working day need not run up separately. Use up when you specifically want the supporting stack. local down stops it; local reset additionally removes local data and asks for confirmation.

Read generated Compose as a projection

The platform template carries backing-service workloads and, for the application-creator lane, platform services. The application template carries application containers and their routing. Framework developers can run platform processes natively, so their generated platform stack is not identical to an installed application’s stack.

The host-facing connection and the container-internal address need not be identical. A host port override avoids a local collision without changing where the image listens internally.

Preserve startup and storage behavior

The template’s health checks support dependency readiness, with fast startup checks and a quieter steady-state cadence. Generated start_interval requires the Compose plugin version accepted by Wildo’s preflight. Memory limits bound resident services; persistent bind mounts preserve state across container replacement.

MongoDB binds /data/db and /data/configdb individually because a parent mount can be shadowed by the image’s declared child volumes. Do not simplify these generated mounts by hand.

The MongoDB search sidecar illustrates why startup is more than launching containers. Its template waits for the initializer that creates its authentication user:

mongot:
  depends_on:
    mongodb-init:
      condition: service_completed_successfully
  mem_limit: 2048m
  healthcheck:
    interval: 60s
    timeout: 10s
    start_period: 30s
    start_interval: 3s

This is an excerpt of the current template, omitting its image, mounts and probe command. The dependency is successful initialization, not merely a running database. The separate startup cadence checks readiness promptly without repeating the same expensive probe every few seconds throughout the day.

On a server, deployment automation applies the generated artifacts. Local startup is not proof of a server deployment or of Kubernetes equivalence; verify the selected lane’s rendered configuration and operating result.

Author the cluster-facing fields

This excerpt follows Wonder Todos’ production descriptor, with a neutral domain and names. Backing services and other policy blocks are omitted.

export default defineInfraEnvConfig({
  environment: WildoEnvironment.PRODUCTION,
  locationType: WildoLocationType.REMOTE,
  runtime: WildoDeploymentRuntime.KUBERNETES,
  runtimeEnvironment: RuntimeEnvironment.PRODUCTION,
  publicDomain: 'example.com',
  serviceHosts: { app: 'app', docs: 'docs', website: '' },
  remoteProvider: {
    provider: 'scaleway', registryEndpoint: 'rg.fr-par.scw.cloud/example',
  },
  kubernetes: {
    namespace: 'application-production',
    ingressClass: 'traefik',
    services: {
      backendApi: { replicas: 3 },
      app: { replicas: 3 },
      website: { replicas: 2 },
    },
  },
  deployment: {
    branch: 'main', runtime: WildoDeploymentRuntime.KUBERNETES,
    namespace: 'application-production',
  },
});

The configuration helpers and environment enums come from @wildo-ai/platform-config-lib. Service keys match the application’s declared service keys, such as backendApi, app and website, rather than generated image names. Synchronization carries their replica counts into each deployment; an omitted count defaults to one. An override without a matching emitted application deployment produces a warning, including frontends served through a CDN. Worker replicas remain in the worker declaration. Replica declarations describe desired workload size; they are not proof of availability or spare cluster capacity.

Import RuntimeEnvironment from @wildo-ai/saas-models. Remote generation also needs runtimeEnvironment and the authored remoteProvider.registryEndpoint shown above. That endpoint is the only image registry: synchronization carries it into the workload configuration, and the generated deployment workflow pushes images to the same place. The deployment block has no registry field to keep aligned with it.

Understand the two application boundaries

Locally, the bootstrap creates a Kind cluster, prepares storage, installs the ingress stack, applies manifests and checks readiness. Host storage is mounted into the node. Remotely, generation supplies manifests and the deployment workflow applies them to the selected cluster.

getDeployableInfraServicesForK8s selects local backing workloads through the same self-hosting predicate used by Compose. The readiness loop follows emitted workloads; MongoDB search readiness follows its database initialization. Storage manifests have their own rendering path using the same selection policy.

Keep each process’s configuration explicit

Application deployment templates consume a runtime environment secret and provider-specific secret material. Required environment material prevents a process starting with its essential configuration missing; optional provider material supports runtimes with no such provider declaration. These are generated per-runtime inputs, not an instruction to share one broad secret across every pod.

The backend deployment template makes that distinction directly. This template excerpt is generated structure, not a file to author; the names are supplied by the shared runtime-secret naming functions.

envFrom:
  - secretRef:
      name: {{runtimeEnvSecretName}}
  - secretRef:
      name: {{providersSecretName}}
      optional: true

The missing optional flag on the first reference is significant: losing essential runtime configuration must prevent startup. The second reference is optional because a runtime may declare no external providers.

Cluster storage, ingress, certificates and controller installation remain operational concerns to verify after applying the artifacts. The local Compose telemetry collector does not establish a Kubernetes collector deployment; a cluster environment must have a reachable telemetry destination of its own.

Check the generated configuration before deployment

Run these from the configured application workspace, selecting the environment you intend to change:

wildo config sync --env=production --domain config
wildo config validate --env=production --domain manifest
wildo config validate --env=production --domain manifest --deployment-artifacts

Confirm synchronization actually produced the deployment artifacts. A skip message can mean the platform is unavailable or the application credential was refused; restore platform access and application registration before retrying.

The first validation command checks freshly rendered infrastructure and platform manifests in a temporary directory. Adding --deployment-artifacts also checks the application files produced by synchronization under .wildo-saas/deploy/production/k8s: workloads, ingress, Secrets and every other YAML/YML document in that directory. Missing or empty deployment output fails.

Both checks parse YAML and require resource identity fields. They leave persisted files intact, omit document payloads from diagnostics and do not contact a cluster. Inspect service addresses and mounts before applying the artifacts; Kubernetes admission and working credentials require deployment checks.

Declare the names and issuer

This fragment belongs in a remote Kubernetes environment. Provider identifiers and registry settings below are illustrative operator choices; the field shape and service-host pattern follow the production descriptor.

publicDomain: 'example.com',
serviceHosts: {
  app: 'app',
  docs: 'docs',
  website: '',
},
remoteProvider: {
  provider: 'scaleway',
  registryEndpoint: 'rg.fr-par.scw.cloud/example',
  acmeEmail: 'operations@example.com',
  tlsIssuer: WildoTlsIssuer.LETSENCRYPT_STAGING,
},

Import WildoTlsIssuer from @wildo-ai/platform-config-lib. Validate DNS and routing with the staging issuer, then select LETSENCRYPT_PROD for browser-trusted issuance. The staging certificate is intentionally not a production trust result.

Use the TLS owner for the selected runtime

The public hostname inputs are shared; certificate ownership differs:

The remote Compose application generator supplies the same resolved service hosts and ACME email to its Traefik template. Preserve its certificate volume across container recreation and make the HTTP challenge reachable. The Kubernetes tlsIssuer staging/production choice shown above does not configure the Compose resolver.

Follow the generated ingress

Wildo’s Kubernetes workflows install Traefik. kubernetes.ingressClass accepts traefik or omission; other controller values are rejected in authored and saved configuration. Application ingress and HTTP-01 challenge routing use that same supported class.

The shared public-host resolver produces ingress routes and advertised runtime endpoints. It rejects hostname collisions. The application ingress template enumerates those hosts, points each at its own service and adds the configured cert-manager.io/cluster-issuer annotation.

A per-ingress TLS secret can cover the hosts enumerated on that ingress. Do not interpret this as one independently generated certificate for every hostname. Remote issuer templates use HTTP-01, while the retained wildcard alternative is not part of that rendering path.

Keep CDN frontends outside the application edge

For a frontend with enabled: true in the environment’s cdn map, Wildo preserves its advertised public URL but removes its self-hosted deployment target and public route. Kubernetes therefore emits no nginx Deployment/Service or ingress route for that frontend; remote Compose emits no corresponding application container or Traefik router. Both consume the same filtered target list.

The CDN must serve that hostname through its own publishing, origin, DNS and TLS setup. Follow the frontend CDN publishing guide for that separate path.

Distinguish the local cluster edge

The local Kubernetes bootstrap applies the separate self-signed issuer and wildcard certificate for its local domain. It does not request a public certificate through the remote HTTP-01 path. Browser trust in that local authority is a separate machine concern; a successfully applied local certificate is not evidence of remote public issuance. Ordinary host-based local development endpoints remain a different topology from the cluster edge.

Keep controller work and operator work distinct

The ingress template includes host-header pass-through and sticky-cookie routing. It does not add a general edge rate limiter or security-header policy; those belong to the application or the operator’s chosen edge configuration. Generated YAML alone does not establish successful remote issuance.

Inspect the expected layout

Local data belongs to the application workspace. Selecting another environment changes the service selection, not the base local_data directory.

The service list is derived for the selected environment. This illustrates the paths for an environment running these services; other selected services have their own directories.

<application>/.wildo-saas/local_data/
  mongodb/
    db/
    configdb/
  mongot/
  postgresql/
  rabbitmq/
  minio/

getDockerComposeLocalDataServices selects stateful services using the same inclusion rules as Compose. EnvironmentPaths.ensureLocalDataServiceDirs creates their host directories before Compose mounts them. MongoDB’s child directories come from INFRA_SERVICE_DATA_SUBDIRS; they must correspond to its actual /data/db and /data/configdb targets.

Understand the local cluster’s relationship

Kind mounts the host data tree into its node and local volumes refer to that mounted storage. This gives the two local runtime lanes a known host location; it is not a promise that switching database versions or runtime layouts requires no compatibility checks. Compose pre-creates individual service paths; local cluster materialization follows its own storage bootstrap.

Choose retention or deletion deliberately

The wipe runs after workloads release storage. It targets the selected service directories rather than deleting the parent indiscriminately, and aggregates removal failures instead of reporting success after a partial wipe.

This is local persistence, not backup or replication. An omitted cache, broker or object-store declaration retains its baseline local service; an explicit managed choice suppresses its local directory with its workload. Check the resolved set before any destructive operation.

Start from a configured local Compose workspace

# Start the selected application's local Compose development session.
wildo local dev

# Inspect it from another terminal, without starting another session.
wildo local dev-status

local dev supports local Compose environments; it refuses Kubernetes environments. The local environment and its authored secrets must already exist. Initial application setup uses the registered setup/initialization journey; this command does not silently replace missing credentials with new values.

Understand the order before diagnosing a failure

Framework-development mode can supervise native platform processes, while the application-creator lane uses its platform containers. The application process set follows the selected development scripts; a runtime declaration alone does not prove that a particular worker is launched by those scripts.

Read the cause, not just the signal

createLocalDevShutdownCoordinator distinguishes an external interrupt from an internal bootstrap failure or a managed process exit. It sends termination to managed children, waits for their close/drain promises and then closes the combined output. Each process tree has a 15-second exit wait by default. A timeout is reported before the output is closed, so a process that never closes does not hold shutdown open indefinitely. A printed termination signal is therefore not sufficient evidence that another process killed the session.

The output boundary frames stdout and stderr independently and preserves the machine log while terminal presentation follows the authored logging policy. Use local dev-status to inspect compiler/supervisor and endpoint facts, including when the normal TypeScript CLI layer cannot load. It is an observation surface, not an automatic restart or repair loop.

Attach another application to a shared platform

A second session using the same owned roots is refused. In framework-development mode, another application can attach to a healthy platform already owned by a separate local Compose session. Run this from the second application’s configured workspace, leaving the owning session running:

# Reconcile only this application's registration and runtime configuration.
wildo local init --register-only

# Start this application's processes without starting the native platform again.
wildo local dev --skip-platform

--register-only avoids shared infrastructure initialization. --skip-platform keeps native platform startup and platform-root process cleanup out of the second session; when a live foreign owner is detected, shared container convergence is skipped too. If that owner’s infrastructure is down, the attaching session refuses to start it from the second application.

This is the framework-developer shared-platform path. Application creators use the platform-container lane described above; the native-platform attachment sequence is not a general Kubernetes startup recipe.

# Report host prerequisites and Compose running-stack checks.
wildo local doctor

# Observe the development processes and their current facts.
wildo local dev-status

Run these from the configured application workspace so they resolve the intended environment. The doctor does not initialize a missing environment on your behalf. Its running-service probes target Compose containers. On Kubernetes it still runs host checks and warns that cluster-specific diagnosis is not covered; a healthy host result does not establish pod or cluster health.

Separate preparation from runtime probes

For a local Compose session, local dev calls the shared collectLocalPreconditionChecks before starting its application tree. A failure blocks startup; a warning is printed and may continue. Running-stack probes remain in doctor, because a preflight must not require the stack it is about to start to be healthy already.

Is the running code current?

wildo local doctor also requests the derived-artifact currency sweep and the coding-agent probe. The shared development preflight omits these additional checks unless requested: it must remain suitable for starting the stack, while doctor spends more time diagnosing it.

When source and behavior disagree, read the currency result before changing the implementation. Source files, compiled output, injected package snapshots and an already-running process can represent different revisions. Currency findings are advisory; follow the named artifact and remediation, then confirm the process has loaded the refreshed output. A green compiler result alone does not establish which code a running service uses.

Interpret each result as an action

Example: a MongoDB container is running, but its administrator authentication fails. This is a shortened diagnostic result; the check name, status and authentication detail come from the implemented probe:

{
  "name": "mongo admin auth",
  "status": "fail",
  "detail": "Authentication failed"
}

For this result, the check suggests comparing the container’s MONGO_INITDB_ROOT_PASSWORD with the administrator connection in the apps-manager’s MONGO_CONNECT_URL. Resolve the configuration mismatch before choosing a repair. A suggested reset wipes data; it is not a prerequisite for reading or understanding the report.

The database probes authenticate with platform administrator credentials. Success establishes that administrator connection, not the application’s own credentials or permissions. Listing stale application users is a separate inventory check; it does not authenticate as each user.

The shared diagnostic contract carries the observation and its next step separately. This is the framework result shape used by the checks and their renderers, not application configuration:

export enum LocalPreconditionCheckStatus {
  PASS = 'pass',
  WARN = 'warn',
  FAIL = 'fail',
}

export interface LocalPreconditionCheckResult {
  readonly name: string;
  readonly status: LocalPreconditionCheckStatus;
  readonly detail?: string;
  readonly fix?: string;
}

A failure commits the preflight to blocking. A warning communicates a finding while allowing continuation. The optional fix carries guidance rather than executing it, preserving the separation between observation and repair.

Prefer executed evidence

The toolchain checks execute the relevant binaries; the C++ probe compiles a small modern-language program where supported. This distinguishes a reported version from a usable installation. The network and authentication probes similarly ask more than whether a port was declared in a Compose file.

A result can include a suggested remediation. Apply that action separately after understanding its scope. Orphan detection does not kill the processes it finds, and reporting stale service users does not remove them.

A successful diagnostic establishes only its measured checks. It does not prove the application implements its business rules correctly, nor that an unprobed platform is healthy. Use the per-check status and detail rather than treating the command as a blanket correctness certificate.

These commands require an active local environment. Initialization also needs a targeted application root and the installed CLI/framework path. reinit additionally checks framework-developer mode; --force does not bypass that check. Application creators who deliberately need an empty restart use local reset, then invoke local init separately.

Follow a Compose repair with application startup

# Preserve backing-service data while reconciling initialization.
wildo local init

# In a local Compose environment, start application development afterward.
wildo local dev

Initialization converges generated artifacts, backing-service readiness, platform initialization, application registration and runtime environment projections. Its completion includes an executable platform JWT/configuration postcondition. It prepares the infrastructure and control plane; application processes start separately.

The command needs the targeted application root and an existing local environment. Missing or invalid authored secrets must be restored or deliberately prepared through setup; repair must not invent a competing credential set.

Treat an empty rebuild as a different operation

In framework-developer context, local reinit stops the relevant supervised/tracked processes, wipes through the selected runtime lane and delegates back to initialization. Compose stops containers before host directories are removed. The cluster path releases claims and local storage before recreating the environment. Failed removal is reported rather than hidden behind a later bring-up.

In interactive mode, the destructive commands try to list the absolute data paths before asking for confirmation. That preview is best-effort: a path-resolution failure can leave the prompt without a directory list. Confirm the selected application and data scope before proceeding. Non-interactive execution requires explicit destructive opt-in. Do not use that mode merely to bypass a question during diagnosis.

Respect a live shared owner

A full initialization can disturb shared platform processes and generated state, so a live owning session causes a refusal. The --register-only path reconciles this application’s registration and projections against the existing platform instead. These commands are local lifecycle tools; they do not restore remote business data or replace a remote deployment procedure.

wildo config sync invokes provisioning for file-backed environments. Each registry material declares its identity keys, generated secret keys, purpose, presence check and provisioning/rotation functions.

The provisioning loop checks each material before and after minting:

Selected source from framework-managed-secrets.ts:

export function provisionFrameworkManagedSecrets(
  secrets: PlatformEnvSecretsDraft,
): FrameworkManagedSecretsProvisioningResult {
  const mintedRefs: FrameworkManagedSecretMaterialRef[] = [];
  const mintedKeys: string[] = [];

  for (const material of FRAMEWORK_MANAGED_SECRET_MATERIALS) {
    if (material.isProvisioned(secrets)) continue;

    material.provision(secrets);

    if (!material.isProvisioned(secrets)) {
      throw new Error(
        `Framework-managed secret material '${material.ref}' did not satisfy its own provisioning check. `
        + 'This is a registry authoring bug in framework-managed-secrets.ts, not an environment problem.',
      );
    }

    mintedRefs.push(material.ref);
    mintedKeys.push(...material.identityKeys, ...material.secretKeys);
  }

  return { secrets: secrets as PlatformEnvSecretsJson, mintedRefs, mintedKeys };
}

The selected source returns the updated structured secrets object together with the material and key names it created. Operational reporting can use those names without displaying credential values. A material that fails its own presence check aborts provisioning instead of saving a falsely complete environment.

Keep backfill distinct from rotation

Normal synchronization provisions missing materials; --rotate-secrets is the explicit rotation choice. The general overwrite flag does not imply rotation. Rotation must be coordinated with the deployed services and published verification keys that use the changed material.

The registry groups keys that belong together. A complete existing material is preserved; repairing a partially missing material follows that material’s own provisioning function. Do not remove one key from a running credential pair as a way to request routine synchronization.

Keep operator choices with the operator

The registry can generate an administrator password when one was not supplied, but it does not invent the administrator’s identity. Vendor credentials and other operator-authored values remain inputs. In a fileless CI lane, the framework reads persisted secret-store material rather than minting new credentials that disappear with the runner.

The CI adapter reads WILDO_SECRET_* variables and validates the reconstructed object with the same schema as file-backed environments. Provider variables use WILDO_SECRET_PROVIDER_ENV_<ENV_VAR_NAME>, retaining their declared runtime name.

Generate the workflow’s variable list from the configured application workspace:

wildo config sync --env=production --domain cicd

Inspect the generated deployment workflow’s env block. It derives required and optional inputs from the secret schema and the selected providers; do not copy a fixed list from another environment.

For example, suppose a configured provider declares EXAMPLE_API_KEY as its runtime secret. The corresponding workflow fragment is:

- name: Generate deployment artifacts
  env:
    WILDO_SECRET_PROVIDER_ENV_EXAMPLE_API_KEY: ${{ secrets.WILDO_SECRET_PROVIDER_ENV_EXAMPLE_API_KEY }}
  run: npx wildo config sync --ci --env=production --domain config

This is a placeholder-only example of one entry, not the complete generated workflow. Store the real value under that secret-store name; never replace the expression with a literal credential.

The adapter validates the reconstructed inputs. Required provider inputs must be supplied; optional inputs are identified separately by the generated list. CI consumes persisted material rather than minting temporary replacements. Generated Kubernetes artifacts are written under .wildo-saas/deploy/production/k8s/ for the deployment step to consume.

Preserve key material across the boundary

The adapter normalizes escaped newlines for key and certificate variables before use. Store the actual material in the deployment’s secret manager and expose it only to the runner steps that need it. Do not replace missing persisted keys by generating fresh ones during an ephemeral deployment.

Separate source hygiene from secret operations

The framework consumes the values; the secret store owns access, rotation and expiry policy. The runner holds them in memory and may render secrets-bearing deployment artifacts, which require their own access and cleanup policy. Local file-backed environments remain a separate supported workflow; their secrets are authored inputs, not disposable generated files.

The application backend uses the application’s provisioned material. Additional runtime principals derive their grants from their declarations. A minion’s resourceAccess.read and write lists govern application data; platform-access scopes are a separate axis.

Database ownership and a scoped table grant use distinct provider operations. Scoped synchronization replaces the previous authority so removing a declared resource can remove the grant instead of leaving an accumulating permission set.

Declare read and write separately

Inside the minion’s entry in wildo.saas.config.ts, an illustrative editing task would declare:

resourceAccess: {
  read: ['todos'],
  write: ['todos'],
},

These identifiers name resource types, not database collection names. User-relative self-resource doors are rejected by this authoring contract. Write permission deliberately does not imply read permission.

Synchronize the changed configuration and inspect the provisioned principal’s grants. Removing a resource must remove the corresponding authority, while a read-only declaration must still refuse a write. The neighboring runtime-topology guide shows the enclosing minion registration. Storage sessions remain scoped to the application’s prefix; a database read-only grant does not also make object storage read-only.

Confine delivery as well as provisioning

The authenticated configuration fetch resolves the presenting principal. Before overlaying a non-backend principal’s material, the manager removes every path that a provider can mint per principal:

Selected source from apps-to-manager.apps-manager.platform.controller.ts:

const isApplicationBackend = principal.kind === ApplicationRuntimePrincipalKind.APPLICATION_BACKEND;

const projected: Record<string, unknown> = structuredClone(rest);
if (!isApplicationBackend) {
  for (const path of collectPerPrincipalSecretBlobPaths()) {
    AppsToPlatformAppsManagerPlatformController.deleteSecretBlobPath(projected, path);
  }
}

if (!section) {
  return projected;
}

// Overlay the principal's own material, by the same JSON paths the provider modules mint into.
for (const [path, value] of Object.entries(section.secretBlobValues)) {
  AppsToPlatformAppsManagerPlatformController.assignSecretBlobPath(projected, path, value);
}
return projected;

This selected section is from the controller’s credential projection. Stripping occurs even when the principal has no credential section. Otherwise an absent narrow grant could accidentally leave the broad application value in place. The application backend is explicitly distinguished by principal kind because that base material is its own.

Match storage access to the application identity

Object storage uses short-lived sessions with a policy tied to the platform-issued application identifier and storage prefix. Bucket provisioning remains a platform operation; a prefix-confined session does not need permission to create the bucket.

Review the resulting principal grants and delivered material when changing a runtime declaration. Credential generation, network reachability and resource-service permissions reinforce one another, but they are distinct controls with distinct consumers.

Wonder Todos selects read-only application data for its marketing-scrapper minion:

Selected source from wildo.saas.config.ts:

minions: {
  marketingScrapper: {
    path: './minions/marketing-scrapper',
    resourceAccess: {
      read: ['todos'],
      write: [],
    },
  },
},

This is a selected minions entry inside the existing wildo.saas.config.ts declaration, not a standalone configuration file. A minion is a separately declared background service with tick-based execution. The example omits its independent platform-access settings. A worker is a different runtime category; do not use the names interchangeably or assume a worker is the backend’s queue consumer.

After editing the declaration, run wildo config sync from the configured application workspace. Inspect the environment generated for ./minions/marketing-scrapper and its deployment network membership. Queue, cache and telemetry are part of the minion service set; database and object-storage topology follow the presence of resourceAccess. Inspect names and grants without printing credential values.

The presence of resourceAccess activates the data-service topology. Omitting it excludes those services; an explicit { read: [], write: [] } still activates the topology but grants no resources through these lists. Reachability and resource grants are separate decisions.

Derive addresses and reachability together

resolveRuntimeBackingServiceAccess evaluates the runtime principal and declaration. The environment builder intersects that access with provisioned services; resolveRuntimeNetworkMembership uses the same result for network membership.

Serving HTTP is a deployment choice. Internet egress is a separate explicit declaration. A connection address does not select the application’s database engine, and network reachability does not replace operation-level permissions.

For a new runtime, inspect the generated environment and network projection together. They should express the same declared access instead of compensating for one another.

Author application and infrastructure choices in their configuration files. Use configuration synchronization to regenerate derived environments; edit the source value instead of patching a generated .env.

Builders return raw values. The local dotenv writer encodes them exactly once for its reader:

Selected source from env-configuration-generator.service.ts:

function writeEnvFile(filePath: string, env: Record<string, string>): void {
  const dir = dirname(filePath);
  if (!existsSync(dir)) {
    mkdirSync(dir, { recursive: true });
  }

  const content = Object.entries(env)
    .map(([key, value]) => `${key}=${encodeDotenvValue(key, value)}`)
    .join('\n');

  writeFileSync(filePath, GENERATED_FILE_HEADER + '\n\n' + content + '\n');
}

For example, take this harmless raw value (two lines, not a real key):

PUBLIC-LINE-ONE
PUBLIC-LINE-TWO

The Node dotenv sink writes one quoted entry with an escaped newline:

EXAMPLE_PUBLIC_MATERIAL="PUBLIC-LINE-ONE\nPUBLIC-LINE-TWO"

The dotenv reader reconstructs PUBLIC-LINE-ONE followed by a newline and PUBLIC-LINE-TWO. The provider passes the original two-line value; it does not add the quotes or the escape sequence itself.

Compose and Kubernetes have their own sink encoders. A value safe for one format is not necessarily correctly escaped for another. This is why providers and runtime builders should supply the raw key or JSON value, not a pre-quoted string.

Keep runtime projections separate

The generator creates environments per process kind. Kubernetes runtime environment Secrets and provider credential Secrets have derived names shared with the workload manifests. A runtime without provider contributions does not need a provider-secret mount; it still needs its required runtime environment.

Generation changes an artifact, not the memory of an already-running process. Restart or roll out the affected runtime so it reads the new projection. Protect local environment files and deployment artifacts as secrets-bearing material; encoding a Kubernetes Secret is not an at-rest encryption policy.

Platform initialization provisions each service’s keypair and publishes the matching public key in platform configuration. The private key belongs to the signing service’s environment. The framework-managed registry makes missing signing materials part of synchronization rather than a manual key-copy task.

On receipt, the manager checks that the token issuer matches the service identity in the request, resolves that service’s published key and verifies the token:

Selected source from apps-to-manager.apps-manager.platform.controller.ts:

await this.jwtService.verifyRaw(token, publicKey, {
  // Validate issuer matches the serviceId
  issuer: jwtServiceId,
  // Audience should be apps-manager for platform-to-platform requests
  audience: PlatformApplicationType.PLATFORM_APPS_MANAGER,
});

This selected verification call is from apps-to-manager.apps-manager.platform.controller.ts. Its surrounding path refuses an unrecognized service or missing public key. The published configuration is the verification authority; it does not silently fall back to a second environment key.

The platform-service credential retrieval route is different: it authenticates a shared platform secret and looks up the supplied registered service ID. Do not extend the signed route’s caller-to-key binding to that shared-secret route.

Keep application authentication separate

An application runtime presents its platform secret through the application door. The manager resolves the presenting runtime principal from that credential rather than trusting a principal name supplied by the caller.

A service token proves service identity and audience. The endpoint still decides what that service may do; it is not a user session or a general authorization grant.

Coordinate a key change

When rotating, distribute the private half to the signing service and publish the corresponding public half for verifiers. A mismatch is an authentication/configuration failure with a republishing remedy, not a reason to weaken verification. In local environments, wildo local init republishes platform configuration from the secret store.

What does the Dockerfile include?

Dockerfile.platform-base uses the framework root as its build context, with a Dockerfile-specific ignore file. It expects compiled dist/ trees to exist before packaging.

Selected production install and peer guard steps from that Dockerfile:

RUN pnpm install --frozen-lockfile --prod \
    --config.node-linker=hoisted \
    --filter "@wildo-ai/platform-apps-manager..." \
    --filter "@wildo-ai/platform-crontabs-batches-manager..." \
    --filter "@wildo-ai/platform-module-registry..."

RUN node templates/infra/docker-images/platform/verify-peers.mjs /app/wildo-ai \
    "@wildo-ai/platform-apps-manager..." \
    "@wildo-ai/platform-crontabs-batches-manager..." \
    "@wildo-ai/platform-module-registry..."

The trailing ... selects each service and its dependency closure. Installation happens inside the Linux builder stage; host-installed native binaries are not copied as the dependency solution. The guard resolves non-optional peers from the selected packages so a missing runtime peer fails during image preparation.

How is a service selected?

The entrypoint reads PLATFORM_SERVICE, including platform_apps_manager, platform_crontabs_batches_manager and platform_module_registry. Its configuration supports JSON values or corresponding file inputs such as INFRA_SECRETS_FILE, letting deployment tooling deliver configuration through mounted files.

This is framework platform packaging. The separate backend base Dockerfiles are not in the current publication set and are not inherited by application Dockerfiles. When extending the published platform image, update its real service selection and dependency filters together; adding a file to the repository does not automatically make it a runnable image service.

How are the variants produced?

FrameworkDockerPublishService uses FRAMEWORK_DOCKER_IMAGE_PLATFORMS, containing linux/amd64 and linux/arm64. This selected source excerpt shows the publication invocation after target resolution:

FrameworkDockerPublishService.runDockerCommand('buildx build --push', [
  'buildx',
  'build',
  '--platform',
  FRAMEWORK_DOCKER_IMAGE_PLATFORMS.join(','),
  '-f',
  buildContract.dockerfilePath,
  '-t',
  target.imageRef,
  '--push',
  buildContract.contextPath,
]);

The platform Dockerfile leaves platform selection to this invocation and installs dependencies inside each target’s builder stage. Building a non-native target may need emulation or a suitable remote builder; creating both variants is separate from running either one.

Why are aliases handled separately?

Only after all immutable image pushes succeed does the publisher repoint mutable aliases with docker buildx imagetools create. This references the full manifest rather than retagging whichever single-architecture image a local daemon holds.

The local rebuild path creates an image for the host rather than publishing a multi-platform manifest. Application image workflows are also separate: the platform publisher’s target list does not automatically configure their architecture list.

For a release, inspect the published manifest and exercise the intended hosts. The emitted two-platform command establishes the publication contract; it is not by itself evidence that a particular registry tag contains both runnable variants.

Which declarations drive generation?

This is the deployment block from Wonder Todos’ production infrastructure configuration. Its surrounding environment declaration and imports are omitted:

deployment: {
  branch: 'main',
  runtime: WildoDeploymentRuntime.KUBERNETES,
  namespace: 'wonder-todos-production',
},

CiWorkflowGeneratorService selects the runtime template, resolves the image-tag strategy and derives build targets from declared services, workers and minions. Each target needs its Dockerfile at the configured package path. The example is authored configuration, not evidence that this particular production environment has been deployed.

Generate, inspect and adopt

From an application root, after declaring its environments:

wildo config sync --domain cicd

# Review .github/workflows/deploy-<env>.yml before using it.
# Deliberately replace existing generated workflows only after preserving custom work:
wildo config sync --domain cicd --force

Existing files are preserved by default. --force replaces them; it does not merge operator edits. Re-running generation after changing a service therefore requires deliberate adoption of the new workflow.

Both templates run npx wildo config sync --ci --env=<environment> --domain config before image builds, because provider artifacts generated into package source must exist before compilation. They then sync each frontend’s Content-Security-Policy for that environment, since an image bakes its policy in at build time. Images are pushed to the environment’s remoteProvider.registryEndpoint — the registry the generated manifests pull from — logging in with REGISTRY_USERNAME and REGISTRY_TOKEN repository secrets, or the workflow’s own GitHub token for GHCR. A Docker Compose environment without an endpoint builds images and says in the workflow that nothing is published. The Kubernetes template later applies .wildo-saas/deploy/<environment>/k8s/.

Generated workflows target GitHub Actions. Secret mappings name variables configuration sync consumes; storing and granting those secrets remains an operator responsibility. A successful workflow generation is a reviewable procedure, not a completed remote rollout.

Resolve an explicit environment

From an application root, with a declared production environment and an app frontend service, this command sequence first reports drift, then refreshes and verifies the artifacts:

wildo dev sync-csp --env production --service app --check

# After reviewing a reported difference:
wildo dev sync-csp --env production --service app
wildo dev sync-csp --env production --service app --check

--check performs the same resolution without writes and exits nonzero for stale output. Omit --service to cover the CSP-capable frontends. Environment resolution uses --env, then WILDO_INFRA_ENV, then the active environment; production execution refuses an implicit local fallback.

What is composed and written?

The resolver combines the surface baseline, application policy, environment overrides and declared provider footprints. Provider origins are service-specific and come from materialized provider data; run configuration synchronization after changing provider declarations.

The writer preserves nginx text outside the policy markers. It rejects invalid service policy keys and missing required API connection origins before emitting the artifact set. Development startup also invokes synchronization.

Reporting and enforcement are different choices

For the SaaS application surface, an omitted policy defaults to enabled, report-only behavior. An environment named production does not itself turn enforcement on. Inspect reportOnly and the emitted header name: Content-Security-Policy-Report-Only reports; Content-Security-Policy enforces.

Generated files and check mode establish agreement with current configuration. Inspect the actual response header and browser behavior after deployment to establish what users receive; a correct source artifact alone cannot prove the running server uses it.

Which authority determines the versions?

The framework root’s pnpm.overrides supplies version pins. app-dependency-alignment.mjs derives the propagated names from framework manifests, applies explicit exclusions, and reconciles application overrides. The scaffolder consumes that derived set for new standalone applications.

For a framework contributor maintaining the checked-out Wonder Todos application, these are the alignment script’s supported commands. Run them from the framework root; this is not a standalone-application CLI recipe:

node scripts/app-dependency-alignment.mjs --app examples/wonder-todos --check

# Apply manifest changes, then verify the declarations:
node scripts/app-dependency-alignment.mjs --app examples/wonder-todos --write
node scripts/app-dependency-alignment.mjs --app examples/wonder-todos --check

# Refresh the application's own installation and lockfile:
pnpm --dir examples/wonder-todos install

Review the manifest and lockfile changes together. --write does not install packages, and an override cannot supply a peer that no consumer has declared.

Why track peers separately?

engine-peer-closure.mjs computes transitive required peers. The closure is delivered as engine-peer-closure.json, so composition can add a package after scaffolding without a framework checkout. Required peers are declared with wildcard ranges; the shared override remains the version authority. Optional peers are not treated as unconditional requirements.

Reconciliation does not remove declarations merely because they no longer appear in the derived closure: an application may own them independently. Framework-development compiler, watcher and finalizer choices are deliberately outside application pin propagation.

What runs, and where?

These are framework-repository workflows under .github/workflows/, not a deployment gate automatically installed in every application. Their path filters select relevant changes; each checker owns the property it recognizes. Application scaffolding separately installs wildo-config-validation.yml for application configuration.

The following selected steps are copied from .github/workflows/store-neutrality.yml:

- name: Validate the checker itself (and that no baseline row has gone stale)
  run: pnpm run check:store-neutrality -- --self-test

- name: Validate no e2e store access is store-coupled without a declaration
  run: pnpm run check:store-neutrality

The first step challenges the scanner with fixtures and verifies its baseline. The second scans the actual checkout. --self-test selects a different execution mode: it does not also run the repository check.

What does a passing result establish?

Secret scanning treats changed content as untrusted scan data and obtains scanner controls separately. Its pinned scanner and locally recorded checksums are managed by run-gitleaks.mjs.

Use the workflow log to distinguish a checker failure from an application failure. The purpose is to make recurring architectural mistakes visible while keeping behavior verification explicit.

The deployment templates use a shared platform image with a runtime service discriminator. Compose and Kubernetes describe the platform services and their initialization dependencies. In framework development, services can run from source. These are execution choices around the same named responsibilities.

Platform services use the engine’s repositories and runtime mechanisms, with service-specific startup sequences. The application manager and module registry extend the common startup; the schedule manager uses its own two-phase sequence. A common engine does not mean their readiness dependencies or initialization order can be ignored.

Match the caller to the door

Sharing a service does not mean sharing one credential or one permission model for all its endpoints.

This selected middleware from crontabs-scheduler.crontab.controller.ts protects the administrative scheduler routes. Comments and later route registration are omitted; the excerpt stops inside setupRoutes.

protected setupRoutes(): void {
  this.router.use((req, res, next) => {
    const middleware = this.authMiddleware.create({
      allowPlatformServices: true,
      allowApplications: false,
      expectedAudience:
        PlatformApplicationType.PLATFORM_CRONTABS_BATCHES_MANAGER,
    });
    return middleware(req, res, next);
  });

  this.router.use((req, res, next) =>
    this.authzMiddleware.requireAppsManager()(req, res, next),
  );

The first layer authenticates an appropriate service token and audience. The second requires the application manager’s identity. The application synchronization and runtime self-read endpoints deliberately use other contracts; do not apply this administrative example to all scheduler traffic.

Separate operational control from customer authority

A platform environment hosts registered applications. Each application can then have its own application-wide administrators and customer organizations. Those application roles govern its resource operations; they are not the credentials the application manager uses to operate the shared platform.

Provision the shared services and their access before bootstrapping applications. Inspect each readiness endpoint and the specific authenticated exchange needed by the caller. A generated service definition establishes the intended deployment, not a running multi-region service or a guarantee of uninterrupted operation.

From the application root, with its wildo.saas.config.ts and selected environment configured, use the registration-only local path when the platform is already running:

wildo local init --register-only

The active environment must be local, with the operator credentials established by wildo setup; this command rejects remote environments. The platform must already be reachable and healthy. This path skips shared cleanup, platform initialization and substrate convergence. Full local initialization has a different effect and refuses when an active development session owns the platform. The registration-only path lets another application join without taking ownership of that shared lifecycle.

Author the application’s bootstrap policy and service requirements first. Operator credentials and generated key material are not application source literals. The first administrator’s application user types belong in the authored bootstrap settings; their actual login material comes through the initialization workflow.

Match the first administrator to a declared user type

For example, Wonder CRM declares this bootstrap selection in wildo.saas.config.ts (selected fields):

bootstrap: {
  firstAdmin: {
    userTypes: ['member'],
  },
},

The authoritative backend’s src/saas-config.backend.ts must declare the matching userTypes.member entry and its authentication policy. Registration rejects an empty selection, a missing authoritative backend or configuration file, and user types absent from that backend. A user type identifies a category of user; it is not an administrator password or role declaration.

The initialization workflow can also receive a distinct approving administrator. That identity is optional for bootstrap, but application-wide access grants require another administrator to approve the request. Creating one administrator does not by itself make that two-person workflow operable.

Prepare the administrator who can approve wider reads

Some application-wide directory and audit reads need a temporary application-wide access grant. That request always starts pending and must be approved by a different application super-administrator. This is not a requirement for every application-scoped operation; the declared read admission determines when it applies. See product and customer authority for the two grant scopes.

The approving identity belongs in the selected environment’s authored secrets.json, in the approver block with email, firstName, lastName and password. Keep it outside application source and version control.

The four explicit inputs are WILDO_INIT_APPROVER_EMAIL, WILDO_INIT_APPROVER_FIRSTNAME, WILDO_INIT_APPROVER_LASTNAME and WILDO_INIT_APPROVER_PASSWORD. The local fallback replaces an email’s sub-address with +approver and shares the development password. It creates a different identity so a developer can exercise both decisions; it does not prove that two people participated.

For an existing local application on a running platform, add the block and run wildo local init --register-only. Registration forwards the identity to the application-manager seeding phase. Repeated seeding preserves an existing approver’s password instead of resetting it. Check the seeding outcome and sign in as the intended approving account before relying on the workflow. Remote environments use their provisioning workflow, not this local command. Older secrets without an approver remain readable; successful registration alone does not establish that application-wide approval is usable.

Derive every runtime from the same registration

The following framework implementation excerpt comes from application-runtime-bootstrap.service.ts; explanatory comments are omitted. Application authors do not call these helpers individually. They show why the backend, companion, workers and minions receive projections of the same prepared target.

const prepared = await AppBootstrapService.prepareApplicationEnvTargets(registeredTargetInput);
if (!prepared) {
  throw new Error(
    'Application bootstrap resolved no application target. Check wildo.saas.config.ts and the selected application slug.',
  );
}
const projectionInput = { ...registeredTargetInput, prepared };

const applicationBackends = await AppBootstrapService.buildApplicationBackendTargets(
  projectionInput,
);
const companionApis = await AppBootstrapService.buildApplicationCompanionTargets(
  projectionInput,
);
const applicationWorkers = await AppBootstrapService.buildApplicationWorkerTargets(
  projectionInput,
);
const applicationMinions = await AppBootstrapService.buildApplicationMinionTargets(
  projectionInput,
);

The workflow synchronizes the projections, then performs a signed platform-to-platform configuration read as the application manager, naming the target application slug. It checks that the returned slug matches and that the frontend-services projection is nonempty. This probe does not authenticate using the application’s backend primary secret.

A declaration-reapply dry run then compares the stored configuration with wildo.saas.config.ts: an empty updatedFields result establishes declaration coherence; any proposed change fails verification. Preparing once avoids mixing separately obtained registration or credential snapshots between runtime files.

These checks establish the selected application’s managed configuration, not its first login or every runtime’s health. Check the running application through its health and readiness endpoints, then verify its required services and first login independently.

Keep provisioning, migrations and seeding distinct

The lifecycle service supports provisioning before seeding. The CLI can apply application migrations and register again with seeding required. Its appDatabaseSeeding report distinguishes DEFERRED, SEEDED and NO_PERSISTENCE_TARGET; it is not a per-service readiness report.

Registration uses upserts so a repeated attempt can continue existing setup. It is not an all-or-nothing infrastructure transaction. Some provisioning branches log and continue when their administrative service is unavailable; inspect the actual selected services, seeding outcome and runtime bootstrap verification. Explicit override paths can replace material, so routine registration and destructive reinitialization remain different operations.

Each call belongs to one explicitly identified platform environment. The application manager does not publish application workloads, and successful registration alone does not establish that an application is serving traffic.

Generate runtime files from the authored application and environment inputs. Do not maintain a second hand-written copy of platform metadata in each process. Bootstrap still requires environment material: the application has to know who it is, where the manager is and how to authenticate before it can ask for anything.

Author behavior in its owning file

For example, these selected fields from Wonder CRM’s backend-authored configuration describe its local passkey identity. The surrounding authentication settings remain required:

auth: {
  passkeyConfig: {
    rpName: 'Wonder CRM',
    rpId: 'localhost',
    maxPasskeysPerUser: 10,
  },
},

Use the deployed application’s real relying-party domain outside local development. The final configuration requires the user-type auth posture, passkey configuration and email.from; unresolved placeholders are rejected at startup. For a login request naming both a frontend service and user type, a missing or disabled frontendServices.<service>.usersManagement.<userType>.auth entry causes refusal. That check is scoped to requests carrying both values, not a claim that every authentication route behaves identically.

The backend configuration merger rejects changes to protected platform/runtime fields and validates the resolved configuration. These are enforced ownership boundaries, not simply file-organizing conventions. See passkey configuration for the authentication contract.

Authenticate the bootstrap before assembling configuration

This selected implementation from app-configuration-loader.backend.service.ts shows the application’s identity on the request and the separate data sources. Comments are omitted; these are loader internals, not application setup code to copy into a backend.

this.applicationEnvConfig = this.loadPlatformEnvironmentConfig();
this.serviceName = this.applicationEnvConfig.SERVICE_NAME;

this.axiosInstance = axios.create({
  baseURL: this.applicationEnvConfig.PLATFORM_APPS_MANAGER_URL,
  timeout: APPS_MANAGER_REQUEST_TIMEOUT_MS,
  headers: {
    [WildoHeaderKeys.CONTENT_TYPE]: 'application/json',
    [WildoHeaderKeys.SERVICE_ID]: this.serviceName,
    [WildoHeaderKeys.PLATFORM_SECRET]:
      this.applicationEnvConfig.PLATFORM_APPLICATION_PRIMARY_SECRET,
    [WildoHeaderKeys.APPLICATION_ID]:
      this.applicationEnvConfig.APPLICATION_ID,
  },
});

const appConfig = this.buildConfigFromEnv();

const appSecrets = await this.loadPlatformManagedSecrets();

const { appSlug } =
  await this.fetchAndMergeBootstrapConfigMetadata(appConfig);

Identity headers select and authenticate the caller; they are not a requested application switch. The bootstrap secret is credential material, never a value to paste into public examples. The timeout bounds each request.

The loader fetches reduced bootstrap metadata, not the entire application configuration. It validates responses against the managed contracts before merging their fields. Backing-service connection settings remain environment-owned. Application behavior is resolved from its authored source, while operator-owned service-auth token lifetimes retain their authority at signing.

Keep application-managed and platform-managed material separate

The stored configuration uses appManaged and platformManaged branches. Materialization combines the appropriate branches for the consumer rather than persisting a complete process-specific runtime object. The application-facing channel rejects attempts to mutate protected platform-managed secret branches.

Configuration and secrets travel through separate authenticated responses. A process cannot bootstrap simply because an HTTP response returned 200: required identity and key metadata must also parse correctly. Development retries are bounded; they accommodate startup ordering but do not establish a usable configuration when the final request still fails.

Derive different access from the same registration

A present empty resourceAccess object differs from an absent declaration: it enters the minion data-capability branch. That topology allowance is not an unrestricted resource grant. Resource operations and credential minting still apply their own declaration checks.

Secret delivery removes shared principal identity lists. For non-backend callers it strips provider-derived credential paths before overlaying only that principal’s minted section, including when the section is absent. The backend exception is based on principal kind. One prepared registration therefore does not mean every process receives the same credentials. See per-runtime credentials.

Choose the bootstrap exchange the runtime needs

These exchanges are separate from ordinary configuration and secret loading. A worker does not need every exchange merely because they share a manager. Follow scoped storage sessions and per-runtime credentials for the detailed boundaries.

Publish token policy before restarting

For an existing local application, author both token lifetimes in its selected wildo.infra.local.config.ts. The values below are an example policy, not a recommendation for every application:

// Within the selected infrastructure configuration:
serviceAuth: {
  accessTokenExpirationMinutes: 22,
  refreshTokenExpirationDays: 9,
},

From that application’s workspace, refresh the selected environment snapshot, then register it:

wildo config sync --env local --domain config
wildo local init --register-only

The config sync step reloads the authored infrastructure file into config.json; registration-only reads that snapshot. Config sync also refreshes related deployment artifacts and can prepare or register application targets. Registration sends serviceAuth to the application manager. After finding or creating the application’s managed record, initialization reconciles those two JWT lifetimes even when no other configuration changed. This policy reconciliation preserves the other stored settings and does not require broad initialization override. Registration can also reconcile other supplied declarations; it is not a token-policy-only command.

Omitting the entire serviceAuth block preserves an existing policy during ordinary registration. A present block applies schema defaults to omitted members, so author both values when you intend a complete explicit policy. First registration uses defaults when no policy is supplied. Broad override retains its wider reset behavior and is unnecessary for this change.

Already-running processes keep their current snapshot. Restart or redeploy the affected runtime through its normal lifecycle after the registration succeeds. This does not migrate data, restart services automatically, or retroactively change the expiration claim of tokens already issued.

Wonder Todos declares a cron-mode minion in minions/marketing-scrapper/wildo.minion.config.ts. This selected configuration omits display metadata and comments:

import { defineMinionConfig } from '@wildo-ai/platform-config-lib';

export default defineMinionConfig({
  version: 1,
  name: 'marketing-scrapper',
  runtime: { type: 'docker', language: 'typescript' },
  mode: 'cron',
  schedule: '0 */6 * * *',
  reinstantiation: {
    policy: 'kill_previous',
  },
  resources: { cpu: '500m', memory: '512Mi' },
});

The minion must also be declared in wildo.saas.config.ts, with its path and resource/platform access. Its work implementation belongs to that runtime. Synchronization brings the declaration into managed configuration; startup schedule synchronization registers the application’s jobs with the scheduler.

mode and schedule select recurring delivery. reinstantiation.policy controls replacement during deployment: the Kubernetes generator maps kill_previous to Recreate and let_run to RollingUpdate. It does not make successive cron handlers mutually exclusive. If overlapping ticks could duplicate an export or an external API charge, the application handler must coordinate that work and make its effects idempotent.

Follow the application identity through dispatch

The authenticated jobs-sync endpoint derives applicationId and the advertised broker virtual host from the application’s identity, not a target application supplied in the request body. A full sync creates or updates jobs and removes jobs no longer declared by that application.

The automatic resource-cron, custom-batch and minion extractors register their expressions in UTC, including the minion shown above. These declarations do not supply a timezone field. The lower-level application jobs-sync API accepts an explicit timezone, which the scheduler preserves; its stored-job default is UTC. Do not read that lower-level support as local-time or daylight-saving behavior for the illustrated declaration.

The scheduler validates expressions and refreshes its active job set. A dispatch names exactly one operation, custom batch or minion. The publisher selects its queue accordingly:

const queueName = input.minionName
  ? QueueNamingUtils.buildMinionTickQueueName(input.applicationId, input.minionName)
  : QueueNamingUtils.buildQueueName(input.applicationId, 'scheduled');

That selected implementation keeps a minion tick out of the backend’s ordinary scheduled-work queue. Both are still inside the application’s configured virtual host. The token signer names the target and work; the receiver verifies the scheduler’s signature before interpreting the instruction.

Bring up the queue owner before publishing

The receiving runtime declares its queue: the application backend owns the scheduled-work queue, and each minion owns its named tick queue. The scheduler checks that the destination already exists and refuses publication if it is absent; it does not create a replacement queue with guessed settings.

Repair the receiving runtime, queue topology or broker permissions before requesting fresh work. Queue existence alone does not prove a consumer is healthy, and a message retained by the broker can outlive its signed authorization.

Distinguish the stages when operating it

A published tick is not a completed business job. Inspect the receiving runtime and resulting effect when diagnosing a missed export. A broker-refused virtual host enters bounded retry quarantine; it needs provisioning or permission repair, not repeated immediate attempts.

Know which failures retry

Successful minion handling acknowledges the tick. The no-requeue rule above describes the consumer’s explicit failure handling; it does not promise that broker or connection failures can never cause redelivery. The application owns recovery of an incomplete business effect, including deciding whether and how it is safe to replay it.

Scheduler replicas coordinate through a shared lease: the leader arms schedules and rechecks ownership before each scheduled tick; standbys disarm their tasks. A lease check is not end-to-end deduplication: a stalled publisher can race with takeover after passing the check. Application-declared schedules are reconciled through startup sync; administrative scheduler operations are a separate control surface. Keep handler retry/idempotency policy and recovery of interrupted work explicit.

When a runtime misses a tick

A signed tick has a five-minute token lifetime. The verifier allows 30 seconds of clock tolerance; a queued message is not an indefinitely reusable authorization to run the work.

After an outage, inspect the receiving runtime and the business result before deciding what to recover. Reusing an expired token does not repair missed work. A catch-up action must deliberately select the missing work and avoid duplicating completed effects; the next cron occurrence alone does not establish that recovery happened.

ResourcePrimaryScope.APPLICATION means the scope of one hosted application. It is distinct from ResourcePrimaryScope.ORGANIZATIONS, which describes its customer organizations. It does not mean the Wildo application-manager service or authority over other hosted applications.

These selected entries from roles.shared.defaults.ts show the separate default role tables. They are fragments of two declarations, not one complete configuration object.

[CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN]: {
  role: CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN,
  inheritFrom: CORE_APP_ROLES.APP_ADMIN_BILLING_MANAGER,
  isSystemRole: true,
  relatedPrimaryScope: ResourcePrimaryScope.APPLICATION
}

// Separately, in DEFAULT_ORGANIZATION_ROLES:
[CORE_ORG_ROLES.ORG_OWNER]: {
  role: CORE_ORG_ROLES.ORG_OWNER,
  inheritFrom: CORE_ORG_ROLES.ORG_ADMIN,
  isSystemRole: true,
  relatedPrimaryScope: ResourcePrimaryScope.ORGANIZATIONS
}

A role is resolved in the table for its scope, including that table’s inheritance chain. Writing the name of an application role into an organization membership does not create application authority. Organization-unit roles are narrower still; a unit assignment is not an organization-wide membership.

Declare the operation and the reach it needs

Application authority is necessary for product administration, but it is not blanket permission to read or edit every customer’s records. The authorization layer separately evaluates the operation’s admission and the applicable grant. Customer-specific and application-wide grants have different scopes; an empty customer identifier is not a substitute for the latter.

Match the approval to the grant’s scope

An active grant must still be usable for the requested access, including its expiry and revocation state. Neither grant replaces the operation’s role and admission checks. The registration workflow explains how to provision the second identity, including the deliberate single-developer local convenience.

Keep recovery authority explicit

The framework’s administrative floors protect against writes that would remove the last usable administrator. A startup report also detects states introduced outside those write paths, such as a restore or direct database edit.

Within the application’s role hierarchy, an organization may have a higher application-level recovery path; the application super-administrator floor has no still-higher role in that hierarchy. Recovery from an externally introduced zero-administrator state is an operator procedure. Sharing Wildo’s infrastructure does not silently create a cross-application customer-support identity.

The ownership-repair operation on organizationMembers is a concrete example. This selected fragment removes comments and the neighboring notification declaration; it belongs inside the resource’s operation configuration:

[OrganizationMembers_Operations.GRANT_OWNERSHIP]: {
  variants: [
    {
      variantType: ResourceOperationVariantType.API_CALL,
      isDefault: true,
      roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN],
      riskLevel: ResourceOperationRiskLevel.CRITICAL,
      resourceOperationLike: CoreResourceOperation.UPDATE,
      admitsCrossTenantPlatformAdministration: true,
      requestDto: z.object({
        justification: z.string().min(1).max(1000),
      }),
    },
  ],
},

The role gate and admitsCrossTenantPlatformAdministration do different work: one checks authority, the other opts this variant into crossing. The implementation supplies the narrow ownership change; the declaration alone does not implement a business action. Its required justification belongs to the request, while grant approval follows the separate access-grant lifecycle.

Establish access before invoking the action

Request a temporary platform access grant for the target organization and follow its approval policy. The authorizer looks for a usable grant for this operator and organization within its time window. A lookup failure refuses access. The request-access operation has a narrow bootstrap exception because requiring an existing grant to request one would make the flow unreachable.

Membership is established from authenticated role entries, not an organization ID supplied in the URL. Unit-scoped authority is not treated as organization-wide membership. Admission is checked in the role/collection path and the fetched-record path so that opening one route does not silently open another.

Repair ownership without replacing existing permissions

The target must be an active membership linked to an active user. An invited or suspended member, or a disabled user, cannot restore usable administration; the action refuses that target instead of reporting a cosmetic repair.

The implementation makes roles server-authoritative and includes the linked-user read in the membership transaction. A caller cannot inject its own role set through a lower-level service call. The following selected implementation preserves existing roles and makes an already-owner retry succeed:

const currentRoles = normalizeRoleArray(currentObject!.roles);

if (rolesConferOrganizationOwner(currentRoles, organizationOwnerConferralResolver())) {
  return { roles: currentRoles };
}

// Add ownership without removing the member's other roles.
return { roles: [...currentRoles, CORE_ORG_ROLES.ORG_OWNER] };

Keep the operation’s purpose narrow

The crossing flag is an authoring decision, not a client header or runtime switch. Review it with the resource specification and the implementation’s actual writes. Reversibility is a design choice in these default operations, not a type-system rule preventing an application author from declaring an unsafe custom action.

At a fetched-record tenant denial, the response conceals existence with not-found semantics. Other earlier authorization failures can be refused before a record is fetched. Access evidence records the applicable observation; it does not establish that the action later completed successfully.

This selected payload comes from recordCrossTenantAdministrativeAccess in AuthorizationsBackendService. It is framework emission code, not an event an application should re-emit from every handler:

auditLogsService.logCrossTenantAdministrativeAccess({
  operatorUserId: executionContext.initiatorIds?.userId,
  targetOrganizationId: rowOrganizationId,
  resourceType: resourceIdentifier,
  operationIdentifier: String(operation.operationIdentifier ?? ''),
  variantType: operation.variantType as ResourceOperationVariantType,
  variantKey: operation.variantKey,
  targetResourceIds: resourceObject?._id ? [String(resourceObject._id)] : undefined,
  authorizingGrantId: (executionContext as { authorizingPlatformAccessGrantId?: string }).authorizingPlatformAccessGrantId,
  authorizingGrantScope: (executionContext as { authorizingPlatformAccessGrantId?: string }).authorizingPlatformAccessGrantId
    ? PlatformAccessGrantScope.TENANT
    : undefined,
  admissionDeclared: operation.admitsCrossTenantPlatformAdministration === true,
  initiatorRoles: initiatorRoles.flatMap(roleInfo => roleInfo.roles ?? []),
  executionType: executionContext.executionType,
})

authorizingGrantId connects this use of access to the grant’s own lifecycle. For a row crossing, authorizingGrantScope identifies the tenant-grant collection; both are absent when no tenant grant was resolved. An application-wide read grant does not substitute for row admission. admissionDeclared states whether the operation opted into crossing. Neither field alone is a business-success result: a declared operation can still lack a usable grant or fail later.

Read the sequence correctly

The fetched row identifies the organization. Organization-wide role entries determine whether the caller belongs to it. For a crossing, admission resolves the usable grant, the observation is emitted, and the tenant-boundary decision then permits or refuses the request.

This ordering includes permitted crossings and refusals reaching that observation point. It is not a record of every rejected HTTP request: a request rejected before a target row is known follows its own authentication or authorization evidence path.

Example: investigate a support crossing

Use the customer’s audit inspection API with an authenticated session authorized for that organization. This illustrative query selects crossing observations; the same route’s access rules still apply:

GET /organizations/{organizationId}/audit-logs?eventType=cross_tenant_administrative_access

Inspect the returned data records for the operator, eventData.targetOrganizationId, operation and target resource IDs. Resolve eventData.authorizingGrantId in the collection named by eventData.authorizingGrantScope to find the justification and approval history. A missing grant is not enough to determine the access decision: application audit reads use administrator permissions by default, while the optional independent-approval policy requires a grant. Other grant-controlled operations still require their grants. Then inspect the business change separately: observing a crossing does not prove that restoration or another action succeeded.

Preserve the scope when a read reaches several customers

Declared cross-tenant reads outside organization-scoped resources use a second observer for READ, LIST and SEARCH. Enrollment follows the executed operation variant. The observer groups the foreign organizations actually returned, with their target record IDs; a single-record read is included, while an empty result or records belonging only to the caller’s organizations produces no crossing.

Organization-scoped resources already observed during authorization are excluded from this second path to avoid double counting. Internally initiated requests and webhook callbacks are also excluded. COUNT returns no attributable records and is not enrolled.

Each resulting crossing is stored under its target organizationId, so it participates in that customer’s authorized audit access. This attribution does not grant audit-reading permission or guarantee delivery.

For application audit reads, auditTrail.applicationReadAccess defaults to role-based; independent-approval adds a time-bound grant approved by another administrator. Both retain the read observations. This policy does not change other application-wide or tenant-support access.

When a grant is recorded, interpret authorizingGrantId together with authorizingGrantScope. Tenant and application-wide grants live in different collections, so the ID alone does not identify where to resolve the authorization. If both grants are present, the observation names the narrower tenant grant.

An application-wide directory read has its own observation, including the returned count and application-wide grant. It does not invent a target customer for a read spanning the directory.

Monitor evidence delivery as well as access

emitAuditObservation keeps audit delivery from changing the request’s authorization result. If the service is unavailable or emission fails, the observation seam reports the loss through diagnostics and metrics rather than silently converting the business request into an audit-store failure.

Delivery remains best effort. Do not interpret an absent event as proof that no access occurred, or a crossing event as proof of a successful modification. The application must retain and route evidence according to its operating policy and investigate delivery-loss signals.

Application-wide reads use their own scope classification and access-grant policy. A directory listing with no single target organization cannot be represented faithfully as a row-specific customer crossing.

Declare and invoke roles through the resource’s membership operations and their registered custom implementations. Their role-ceiling and administrative-continuity checks still apply. Direct database edits bypass this operation lifecycle and cannot be expected to produce its semantic evidence.

The following selected emission from organization-member-custom-implementation.backend.service.ts shows why authority evidence contains more than the final row:

await emitAuthorityChangeAuditWhenDurable({
  serviceOptions: utils.serviceOptions,
  effectKey: ['organization-member-roles-changed', memberId, pending.operation].join(':'),
  logger: utils.logger,
  failureContext: { operation: pending.operation, memberId, organizationId },
  emit: async () => {
    const auditLogsService = container.get<AuditLogsBackendService>(SAAS_SERVICE_TYPES.AuditLogsService);
    await auditLogsService.logOrganizationMemberRolesChanged({
      organizationId,
      memberId,
      userId,
      previousRoles: pending.previousRoles,
      newRoles: pending.newRoles,
      requestedRoles: pending.requestedRoles,
      operation: pending.operation,
      changedBy: resolveAuditActorId(executionContext),
    }, executionContext);
  },
});

The operation stages its inputs before persistence, then emits through the durability helper. requestedRoles preserves what the caller authored; newRoles describes the resulting set. This matters when defaults, validation or grant ceilings distinguish the request from the stored authority.

Keep the scope visible in the event

Include ownership repair in an authority review

The ownership-repair action uses update-like persistence, but its custom implementation is registered under its own operation identity. It does not inherit the ordinary UPDATE hook that emits ORGANIZATION_MEMBER_ROLE_CHANGED. Its critical risk instead triggers automatic RESOURCE_OPERATION_PERFORMED evidence; the roles field is marked for before-and-after evidence.

A query restricted to ORGANIZATION_MEMBER_ROLE_CHANGED can therefore miss ownership repair. Query the automatic RESOURCE_OPERATION_PERFORMED event family, then inspect the returned eventData.resourceType and eventData.operationIdentifier for the membership resource and GRANT_OWNERSHIP operation. Those nested fields are not LIST query filters. Inspect fieldEvidence for the role change; do not expect the specialized event’s requestedRoles field in this payload. An idempotent repair can leave the roles unchanged.

Correlate the operation evidence with the crossing observation by actor, operation, affected record and request context. Resolve the observation’s grant ID together with its grant scope to inspect the grant lifecycle. These are complementary records, not identical payloads or an atomic evidence bundle.

A unit assignment holds one role per assignment record. Treating it as an organization-wide role array would erase the scope that limits its authority. The audit subject identifies the acting principal; the affected user/member and assignment remain explicit event data.

Removing a membership also removes the record that explained its access. Capturing its status distinguishes a revoked invitation from an active membership removal; retaining the unit assignments explains the narrower authority removed with it.

Example: investigate a membership role change

After a role change, query the customer’s audit resource using an authenticated session authorized for that organization. This illustrative request uses the declared event-type filter; replace the organization placeholder and use the application’s API base URL:

GET /organizations/{organizationId}/audit-logs?eventType=organization_member_role_changed

The default LIST variant declares organization member, organization administrator and application super-administrator roles. The route and authorization context still constrain access: a role name or an organization ID in a URL does not grant access to another customer’s trail. See the audit inspection and export API for the full read/filter contract.

Read the returned data records as follows:

For example, if an administrator changes another member’s roles, the actor filter finds the administrator’s action while the event data identifies the member affected. Compare requested and resulting roles rather than assuming they are identical. A repeated unchanged role set emits no new role-change event; an empty result alone also cannot establish that audit delivery was healthy.

Record durable changes, not rolled-back intentions

The helper emits after the relevant write is durable and defers to an outer transaction’s post-commit lane when necessary. A rollback must not leave an event claiming a grant that never took effect. Repeating the same role set produces no role-change event.

Cascade removal follows the parent lifecycle’s evidence rather than fabricating an individual revocation for every child assignment. Audit routing also uses authenticated context; a system provisioning action can reach the shared audit store without an authenticated customer routing context.

These events explain changes made through the framework lifecycle. Preserve the supplied registrations and transaction context when extending that lifecycle, and monitor audit-delivery diagnostics rather than treating the event stream as an infallible transactional replica.