# DevFn v0.1 contract ## Configuration `devfn.config.ts`, JavaScript variants, or JSON define versioned semantic intent: project identity, named ports, native processes, Compose services, dependency-ordered profiles, health checks, prerequisites, environment outputs, and proxy hostnames. TypeScript and JavaScript manifests require digest-bound trust, execute from the verified snapshot, and cannot import executable dependencies. ## Identity and state The instance key hashes canonical repository identity, real worktree path, and project ID; a named runtime (`--runtime `) adds its name, so one checkout can run several lifecycles whose locks, receipts, leases, routes, Compose projects and namespaces stay apart, while the default runtime keeps the v0.1 key. A named runtime refuses environment outputs without a `{runtime}` file-name token and Wrangler, Xcode or extfn processes without an explicit `artifacts` choice, a runtime claims its environment-output files and its runtime directory checkout-wide before any lease or generated file, with or without outputs, keeps that directory disjoint from every other live runtime's (neither the same through a symlink nor nested either way; a replacement under a changed `runtimeDir` holds its old and new directory), creates it as a real directory at the claim and writes each generated file of the start (through readiness and on failure) only while its path still reaches that directory and no symlink inside leads out of it, renaming `runtime.env` into place and starting a hard-linked log anew, and never writes one another runtime holds (by name or as a hard link) or one inside DevFn's own state (receipts and claims, the configured runtime directories and any live runtime's recorded one; refused at the start, never at manifest load) or, when named, one it did not write (checked again at each write, which writes only the canonical file it claimed, creates a new file exclusively without following links, replaces only a file still holding what it last wrote, and records the digest of what it writes before the write, so an interrupted write leaves a file it recognizes as its own), and a receipt recording another runtime is refused rather than adopted. Machine state lives under `$XDG_STATE_HOME/devfn` or the platform user's local state directory. Project runtime receipts and logs default to ignored `.devfn/instances//` paths. Registry mutations use an exclusive lock plus atomic rename. Allocations distinguish planned, active, stale, released, and externally occupied state. Exact ports fail closed; preferred/range/fallback ports reallocate; explicitly ephemeral requirements ask the OS for a temporary port. DevFn never chooses a TCP port that fetch() and browsers refuse (the Fetch Standard's bad ports); only an exact or preferred TCP port can be one, and UDP ports are not restricted. Cohesive `block` requirements receive contiguous ports. ## Lifecycle `up` validates trust/configuration, resolves the profile graph (rejecting cycles and unknown nodes, setup tasks included), verifies any machine-registered route domains resolve only to loopback, reserves ports, writes runtime environment, starts dependencies, waits for health, updates explicit Caddy routes, activates leases, and returns a receipt. Every successful mutation is persisted. Failure walks the journal in reverse and cleans only resources started by that invocation. Replacing a ready instance validates, reserves and activates routes before stopping it, then starts the replacement; a later failure leaves the instance stopped with its leases released and says so, rather than relaunching old processes from a changed working tree. `down` resolves the exact worktree instance, verifies process birth identity, stops its process groups and Compose services, removes its proxy routes, and releases its leases. Persistent volumes are never deleted. ## Setup tasks A process or Compose service with a `task` contract is a finite lifecycle node: it declares no ports, health or persistence, runs to completion in start order (a Compose task as a one-off `docker compose run --rm`), and only its exit code 0 lets later nodes start. A nonzero exit, a per-attempt timeout or a cancellation stops what the task left running, fails the start and rolls back as any startup failure; its dependents never start. A task observes only the resources it declares: it receives no other resource's generated values, and a reference to one in anything it receives fails before any mutation (a profile environment entry names itself, to be moved to the env of the nodes that use it). Each task's input revision digests its declared command and settings, manifest and profile environment as written, secret channel names, consumed resource targets, namespaces and the non-port resource values it receives, its Compose service as its included and extended files define it, selected with the startup environment, with where each part is defined, the resource declarations its references select as Compose resolves them (its implicit default network included) and env-file declarations (repository-relative, only credential values masked) and declared input files, never leased ports, secret values (also literal ones in the Compose file) or inherited host values. A machine-state journal per task scope (its instance, or the project, task and the targets shared across worktrees it consumes: remote ones with a shared namespace or none; local targets and isolated namespaces, a browser's included, are per instance, and a shared-namespace browser is neither; a task mixing shared and per-instance targets is rejected before any mutation) records the latest success and bounded attempts (never evicting one a decision still depends on) with exit status, revision and effects (`applied`, `unknown` or `none`); an attempt is journaled, with its launcher and any one-off Compose launch, before its command can start, and counts as stopped, also after exit 0, only once its one-off containers are verified gone. Before a scope decides, whatever an earlier attempt of any worktree sharing it could not be verified to stop is stopped through those journaled identities, or every start of the scope blocks; an attempt a dead DevFn left running is then recorded interrupted. Teardown and rollback never revert or claim to revert a task's effects. A recorded success for the current revision skips the task unless it reruns `always`; `once` tasks with a changed revision and non-idempotent tasks with an attempt since their last success that may have partly applied block, before any mutation, until rerun explicitly; an idempotent task with such an attempt reruns (a `once` one with a success only at a revision it already ran). A duplicate start after a ready one, task-only lifecycles included, runs nothing and reports it already running; one after a failed start decides again from the journal. Tasks are decided before the lifecycle lock and again under it, from the journals as concurrent starts left them, before any lease, replacement or node. Retries are bounded, only for idempotent tasks, and stop when an attempt cannot be verified stopped. Task runs hold their journal lock, so concurrent starts run a task at most once at a time and later ones decide from its recorded outcome; a lock whose holder is verified dead is taken over within any waiter's timeout. ## Adapters and boundaries Native adapters cover command, npm, Corepack-pinned pnpm, Turbo, Wrangler, Xcode, and ExtFn workflows. Compose retains conventional container ports and uses generated loopback mappings unless public exposure is explicit. Caddy is a DevFn-owned singleton with locked explicit routes and safe reloads; unrelated Caddy instances are never reconfigured. An explicitly started OAuth callback relay serves one registered redirect URI host and forwards each single-use, expiring state only to the live route its owner bound it to. A profile may publish selected routes through a machine-registered nonproduction Cloudflare or ngrok tunnel binding only with `--allow-public` on that start; reserved public URLs are known before start, and explicitly selected ngrok ephemeral URLs only after it; the DevFn-owned connector reaches a dedicated public origin listener that serves only those routes and denies everything else, and each lifecycle withdraws only its own public routes. Registered development domains live in machine state, bound to a repository and project. Manifests may select registered domains but cannot register them. The DevFn Caddy binds to IPv4 loopback and uses IPv6 loopback when available, does not install its internal CA in OS trust stores, and denies unselected hosts and paths. Explicit certificate files are checked for generated hostname coverage. DNS-01 remains unavailable without a validated adapter. ## Resource targets Profiles select each declared resource target (local lifecycle node and declared port, or credential-free remote URL) independently of execution location and public exposure. Selection, consumption cycles, undeclared provider ports, secret channels and namespace collisions are validated before any mutation. Selected endpoint and namespace values reach the endpoint resolver as generated `DEVFN_RESOURCE_*` values under its existing template precedence. Compose consumers receive Compose-internal or platform host-gateway endpoints, never host loopback in any spelling; `*.localhost` targets are never rewritten, and a Compose provider of a selected resource cannot have a loopback service name. Every Compose service receives namespace values; only consumers receive endpoint values, and a Compose provider receives the addresses it advertises without consuming itself. Namespace collisions compare the listeners every receiving context resolves for local and remote targets alike (the host side and each consuming Compose service): loopback port, Compose container port (reached by service name, `container_name` or a network-scoped alias on an effective network in any project), or canonical host; object-store namespaces include the target path and are compared by path segment. Port names, URL scheme aliases and target spellings do not matter, a provider's container port is known in every pass, and which services a name reaches is decided only with effective networks, read before any state whenever a Compose service provides, consumes or references a resource, and a consumer's endpoint must reach at most one selected Compose service (for a local Compose target, only its provider) and must not be a name the consumer maps itself through links or extra_hosts other than only to host-gateway, which reaches the host gateway; an unmapped gateway name no selected service may otherwise answer, and a selected provider's service name is never the gateway: it may not be mapped, nor equal a defined container host gateway name; collisions that depend on a not-yet-leased port are detected after reservation and release the lease. Compose-only `${DEVFN_RESOURCE_*}` references must name a value the service receives. A changed selection replaces a running lifecycle instead of reusing it, also from a receipt without startup fingerprints. Namespaces are isolated per lifecycle owner and runtime identity (a random `runtime-id` linked complete into the state directory after preflight) unless sharing is explicit. Receipts record a redacted plan with value provenance and secret names only, which `up` and `restart` JSON output show without key-based masking. ## Output and compatibility Commands support deterministic JSON receipts and stable `DEVFN_*` error codes. macOS and Linux are the validated v0.1 hosts. Windows-aware process identity and termination paths are present but require Windows CI before support is declared.