Services

services.astrale.ai owns provider-backed compute resources. It keeps provider protocols behind neutral SDK Integrations and stores only admitted lifecycle evidence in the graph.

Model

• Service records one opaque provider name, its owner-scoped stable serviceKey, deployment mode, URL, lifecycle, provider digest, operation receipt, and exact cleanup locators.
• service_owned_by connects each Service to its owning Identity and governs graph visibility.
• Owners may be Shell users, local Kernel roots, or application/CI identities. Services requires only the Kernel Schema; a Shell installation is not required to deploy. Ownership remains exact-subject scoped, and existing Shell-user ownership edges remain valid.
• secret values stay write-only at Cloudflare and never enter Astrale mutations or graph state.
• schedules remain provider state; only the owner may read or replace them.
• logs are remote evidence admitted by the Cloudflare Provider before a Workflow returns them.
• the only admitted Worker service binding is the logical platform router; the provider resolves it to the selected environment and callers cannot name arbitrary same-account Workers.
• tenant Workers do not receive namespace dispatch authority. Inter-Service requests use public ingress, including its retirement and private-route checks. Only the platform dispatcher and candidate-readiness operator retain their respective native dispatch bindings.
• the provider supplies WORKER_URL as the Service's canonical HTTPS URL to both candidate and public Workers. It is reserved provider metadata, not a caller variable or secret. Applications therefore keep one issuer even when requests arrive over HTTP or through a dispatcher alias.

The View, CLI, and agent consumers read the named Service Queries directly; there is intentionally no list Function wrapping listServicesQuery. Deployment, secrets, schedules, logs, and deletion are Workflows because they coordinate admitted caller intent with external effects. Receiver Methods are authorized by the ownership Policy before their Workflows begin. service-hosting is the provider-neutral compute Integration contract. Cloudflare is its first Provider.

Service declares seven abstract management contracts. CloudflareWorker owns their executable Methods (setSecret, deleteSecret, secrets, setSchedule, schedules, logs, migrateIngress, delete) and applies OwnService to each one. Workflow addresses are CloudflareWorker.*; abstract Service.* keys are not executable. A future provider Class must supply its own concrete declarations and implementations. Properties and ownership relationships retain their inherited meaning.

Shared public ingress

New Services use the environment's proxied wildcard DNS, wildcard Worker route and wildcard certificate. Services observes the expected dispatcher route and probes a never-registered hostname before uploading a Worker without an existing Custom Domain. It never creates a per-Service Custom Domain or certificate. Missing shared ingress is an operator provisioning issue; it is not repaired by consuming another certificate during a Service deployment.

After activating routing, deployment waits for public dispatcher visibility with a bounded budget. This is separate from optional candidate application health checks. An uncertain activation retains the Service record and can be retried with the same owner-scoped service key.

Existing exact Custom Domains and their immutable certificate locators are retained on ordinary updates. Detaching old hostnames is a separate migration, coordinated with Service operations; upgrading this Runtime does not perform that migration. A Service without an exact domain persists tenantDomainState: 'absent'. Deletion handles both placements and never removes shared ingress infrastructure.

Cloudflare callers that must traverse same-zone public Worker routes need global_fetch_strictly_public. Audit existing callers before migrating their exact hostnames; explicit runtime flags retain their authored meaning. A rollback after creating wildcard Services must use a Runtime that understands explicit absent placement, not an older certificate-required implementation.

Migrating existing Services

The owner calls CloudflareWorker.migrateIngress with an action (detach, complete, or restore) and a deterministic public health probe: a local GET path, expected successful status, and the exact response body's SHA-256 in bodySha256. The Workflow acquires the existing Service operation lease and verifies provider ownership, active dispatch, wildcard TLS and health before detaching the exact Custom Domain. It does not redeploy the Worker or alter its routing KV, secrets or schedules.

After detach, observe real traffic for at least 30 minutes before calling complete. Until completion, the graph retains the previous domain and certificate locators with tenantDomainDetachedAt; completion clears them after provider cleanup and another successful health check. Cloudflare can automatically delete the generated certificate as soon as its Custom Domain is detached. restore recreates the exact domain, waits for active TLS and records the actual replacement certificate locator. A pending result requires a later retry; it is not completion.

The beta replacement serves at https://services-v2.beta.astrale.ai with the retained https://services.beta.astrale.ai issuer and signing key. Keep the original runtime and identity discovery available for existing installations. Adopt the replacement's public URL per instance before invoking its additive migration API; do not uninstall Services or replace the shared R1 runtime underneath installations that still use its Schema. An instance rollback must restore any detached domain before reinstalling the original endpoint, and must first be qualified with real retained Service data.

Plain background Service starter

The package also ships an isolated scaffolding binary (the root import remains Schema-only):

npm exec --package @astrale-domains/services -- create-astrale-service my-worker
cd my-worker
npm install
# Edit service.json and src/job.js for the existing business Domain.
npm run deploy -- --instance development --as developer

The generator creates local source only and refuses an existing destination. It does not install dependencies, create/register accounts, grant permissions, set secrets, enable schedules or deploy. The generated project owns a plain HTTP/cron entry, an ES256 account session, a job implementation and build/deploy scripts. No Application, Schema, Publication, Domain signer or frontend is generated. Deployment calls the public Services API through the installed Astrale CLI and requires an explicit instance or URL. The project README explains account setup, secret custody, private cron and cleanup. No tooling dependency is added to the Schema runtime or imported from the package root.

Domain development

Copy .env.example to .env.dev and fill the Cloudflare values.

pnpm dev watches and deploys the development Environment remotely. pnpm dev beta selects beta; pnpm beta and pnpm prod deploy once. These bootstrap Environments are deliberately deploy-only: install the resulting URL on the intended Kernel explicitly. Stopping development leaves the remote Worker available. No local Worker or tunnel is started.

To validate without deploying:

pnpm typecheck
pnpm test
pnpm lint
pnpm frontend:build
pnpm build
pnpm package

The deployed module named by entry must be present in modules. Module contents use one Base64 string or bounded Base64 chunks when one string cannot cross the portable Value boundary; names are unique and secrets use environment-variable identifiers. Plain and revisioned artifacts are distinct modes and cannot replace each other at one Service record. Five-field cron expressions are supported when CLOUDFLARE_SCHEDULE_KV_ID is configured.

Plain deployments that omit compatibilityFlags use nodejs_compat, nodejs_compat_populate_process_env, and global_fetch_strictly_public. Public fetch() calls therefore traverse Cloudflare's public routes, including same-zone Astrale endpoints, instead of bypassing those routes for the zone's origin. This changes routing, not Kernel authorization. An explicitly supplied flags array replaces these defaults, including []; low-level callers own that complete runtime configuration. Existing Workers change only on redeployment.

Revisioned deployments require explicit runtime configuration and upload it unchanged to both the candidate and the serving Worker. Those exact flags participate in the deployment identity; Services must not inject defaults after its computation. The Cloudflare adapter already includes public-fetch routing in the generated configuration before building the artifact and its digest.

SDK-authored Applications should deploy through @astrale-os/adapter-astrale, which projects the admitted Cloudflare artifact into the revisioned Services request and verifies the live Publication. Project tooling installs the exact Release only when that environment declares installation. Services never interprets or caches Application, Publication, Schema revision, issuer, or callable inventory. Manual callers may deploy provider compute first and then use the ordinary Domain installation command themselves.

Revisioned deployments may request readiness: { paths: ['/health'] }. Services executes these bounded local GET paths through its private candidate dispatch binding and requires HTTP 200 before public promotion. It never follows redirects or reads the response body as Application metadata. For an existing Service, required checks need every retained secret supplied in the candidate configuration. Missing values fail before staging or promotion. A caller may explicitly request readiness: { paths: ['/health'], required: false } to preserve updates with Worker-only secrets: Services then retains those secrets on the serving Worker and returns candidateReadiness: 'unavailable-retained-secrets' without invoking the incomplete candidate. An executed, successful check returns candidateReadiness: 'passed'. Failed checks still refuse promotion even when required is false; this is not a fallback for broken candidates. Checks share a 30-second budget, shortened by invocation cancellation/deadline. A failed check leaves the public Worker unchanged and removes the newly owned candidate. Unchecked provider-only requests retain their existing contract.

The updated Astrale adapter requests optional /health preflight automatically: SDK Workers initialize their Runtime before serving it. No Project option is needed. The adapter reports unavailable preflight explicitly and always verifies the public Publication, Bundle, and identity after deployment. Private preflight alone never proves complete product correctness. Provision and deploy the updated Services Runtime before using this adapter cohort. Older strict Services schemas reject the new field; the adapter must not retry without the safety check.

An uncertain provider promotion is adopted only after observing its exact, non-secret attempt receipt alongside the artifact tag. Matching code alone is insufficient: Cloudflare's script ETag can remain unchanged when only secrets change. Services-owned operation leases serialize callers; operators making direct provider changes must coordinate with those operations. The code ETag is not a lock for concurrent configuration changes.

If a Kernel interruption prevents recording a deployment outcome, the Service can remain busy until its retained operation lease expires (currently 30 minutes from acquisition or renewal). Retry the same deployment after the expiry reported in the rejection; it reuses the Service and provider identity. Do not clear the lease or create another Service to bypass an uncertain outcome. An operation without a recorded expiry needs operator inspection, not a guessed retry deadline.

A definitively rejected update restores a previously ready Service only when the Provider observes the same serving script digest and tenant routing coordinates. The restoration is atomic and fenced by the current operation receipt; it restores the previous name and description and clears the rejected attempt. The deployment still returns a rejection, but the retained Service remains manageable. Failed creations, uncertain outcomes, mismatched observations, and unresolved previous attempts remain failed rather than claiming that the old deployment is ready. This verification adds no provider request to a successful deployment.

For the complete live owner-management and non-owner-denial journey, see remote acceptance. Run it against an isolated instance; ordinary unit tests do not prove callable admission or real provider telemetry.