Skip to content

ObneyAI/orc / orc-skills/orc-runtime-bootstrap

orc-runtime-bootstrap

Verified

Wire an ORC behavior-tree runtime for an experiment or application, choosing the event store, tenant processor, projection cache, provider, execution, and restart recovery. Use when starting a new ORC project or correcting its runtime setup.

---
name: orc-runtime-bootstrap
description: Wire an ORC behavior-tree runtime for an experiment or application, choosing the event store, tenant processor, projection cache, provider, execution, and restart recovery. Use when starting a new ORC project or correcting its runtime setup.
---

# Bootstrap an ORC runtime

Start with ORC’s tracked [agent instructions](../../AGENTS.md) and [principles](../../docs/ORC-PRINCIPLES.md). Follow the consumer project’s own instructions if it provides them. Check the actual ORC and Grain revisions before copying setup code; the pinned example in [runtime.md](references/runtime.md) is a starting point, not an API freeze.

For a standalone project, use the reference's public Git `deps.edn` form and its two LMDB JVM options. Choose the lean `projects/orc-service` package for ordinary trees; add backend packages deliberately. Resolve and execute the setup in the application's own directory before claiming it works.

For mixed-family caps, checkpoint opt-out or old bounded resumes, read [durable family budgets](references/durable-family-budgets.md). Historical campaign-only counting is insufficient; verify the consuming implementation before relying on a total cap.

## Decide the lifetime and concurrency first

For one application serving many independent users, read [concurrent serving](references/concurrent-serving.md). It covers nonblocking admission, durable completion, scoped ownership and recovery. Parallel branches within one tree and multiple servers owning a tenant are separate contracts.

| Need | Store | Processor ownership |
| --- | --- | --- |
| Disposable REPL/test | Grain v3 `:in-memory` | One standalone tenant poller |
| Durable single process | Grain `event-store-sqlite-v3`, `:database-file` | One standalone tenant poller |
| Multiple instances | Grain `event-store-postgres-v3` | Grain control plane assigns tenant pollers |

Use a real, stable UUID `:tenant-id` and carry it through every context and direct event-store read. Treat LMDB as a rebuildable **projection cache**, not the event store. Configure its capacity explicitly: the inspected Grain constructor defaults to only 10 MiB. The reference uses a configurable 1 GiB example and exposes reader slots separately; size for the reconstructed projection workload and verify actual map size/page highwater. LMDB map capacity, JVM heap and process resident memory are different measurements. Load the backend namespace to register its `:conn` type, and load ORC's public interface before starting pollers so its command, query, schema, and processor registrations exist. Provide a local pub/sub on the event store; distributed SSE also needs the event tailer.

Load application registrations, then start the store/cache and tenant poller. Decide periodic ownership separately: `periodic/start-periodic-triggers!` starts every registered trigger, using explicit `:append-fn` and `:tenant-ids-fn` capabilities. Retain schedule handles; namespace registration and poller startup do not start schedules. At ORC `1851212396cced2fc4533fda30b824bd4b691390`, ordinary execution leases distinguish active work from abandoned executions. Keep schedules an explicit owned choice and verify restart/lease behavior in the consuming deployment; leases are not durable assessment jobs or external exactly-once guarantees. Put trusted code capabilities in the poller context as well as the caller context. On shutdown, stop schedules, await/cancel active ORC ticks and children, then stop poller, cache, store and pub/sub. See the reference for actual forms and partial-startup cleanup obligations.

Register the LLM provider with the application's `litellm.router` configuration and put its keyword in both the execution context and poller context. For ordinary `llm` nodes, omit `:model` to inherit that configured model or supply an actual provider model ID; an ordinary provider alias in `:model` becomes a literal request override. Native decision providers differ: register `:protocol :decision` and choose them per node using their registered names. Verify both paths through the serialized adapter request with `orc-model-sio`; a fake predictor does not verify model resolution. Use `get-family-usage` for descendant accounting.

Register providers and reconstruct trusted capabilities **before** starting workers that can consume persisted execution events. Protect every startup step with owned cleanup, including capture, MCP sessions and partially started runtime resources. Use each cleanup function's real arity; an install handle does not imply `stop!` accepts that handle. Verify startup failure unwinds only owned resources and that cleanup joins the actual tool/HTTP bodies before closing their stores.

Keep independent experiment stores isolated in memory as well as on disk. At the inspected Grain pin, the process-global projection L1 key includes read-model name/version, tenant and scope, but not store identity. New SQLite/LMDB paths with the same tenant in one JVM can still return prior state. Use a distinct tenant for each unrelated store or a fresh JVM; preserve the original tenant when reopening the same durable experiment. An empty-store projection check catches a contaminated harness before it can fake a result.

For cold readback, copy a quiescent SQLite source and any associated WAL/SHM before opening the copy. Check byte equality before first open; after startup, compare canonical event rows and the untouched original source hashes. The pinned SQLite backend runs `ANALYZE`, which can change the copy’s planner-statistics bytes without changing events. Keep the copy’s closure separate from the original runtime’s closure proof. See [immutable readback](references/execution-verification.md).

Build child sheets before parents, then build each stable named workflow once at startup. `build-workflow!` is content-hash idempotent for unchanged definitions, but changing a definition under the same name rebuilds it. Execute through `orc/execute` with bounded timeout and, where needed, an LLM call budget. Check returned status **and** the durable tick/projection. Quiesce or cancel active ticks before shutdown; stopping the Grain worker pool does not join ORC's independently launched futures. Then stop poller before cache, store, and pub/sub. After a durable restart, recreate services and trusted capabilities against the same store. If automatic recovery is required, start the owned schedules and observe the original tick before any manual resume. Then use `orc/resume-in-progress!` to verify explicit recovery/idempotence. A successful terminal `get-tick` has `{:status :completed :root-status :success}`, while `execute` returns `{:status :success}`. Read `:root-status` for the tick’s behavior outcome. The live stream is ephemeral and cannot stand in for the event log. For a projection-rebuild proof, use a fresh JVM and fresh projection directory: Grain's process-global L1 survives ordinary runtime shutdown. Current ordinary delegates inherit family call budget/remaining time and tool context; conditions and supported native decisions use the shared budget path. Use a shared outbound attempt gate when a cap must count actual HTTP attempts across provider retries or unrelated roots. Acquire campaign ownership before loading a persisted attempt counter. Bound the actual tree and verify physical family call counts rather than treating the root budget as a total cap. Configure provider request, root, delegate and shutdown-drain timeouts, plus the result silence-grace threshold separately for the intended work; a REPL/MCP client wait timeout is another boundary. A terminal tick or cancellation request does not prove tool/model bodies have exited. Put a verified application quiescence gate inside shutdown before closing stores; keep resources needed by active work open if draining fails.

When implementation is needed, read [runtime.md](references/runtime.md) for verified API forms and [public execution verification](references/execution-verification.md) for startup, actual model visibility, tick lifecycle, automatic recovery, shutdown and immutable readback. Apply the relevant proof before claiming the runtime works. For command/read-model design, use `orc-grain-application`. For node values and traces, use `orc-observe-debug`.

Keep access checks executable: direct Grain command/query processors do not evaluate `:authorized?` metadata, and trusted claims alone do not guard a call. Use an enforcing adapter or explicit host/handler guard; the [Grain reference](../orc-grain-application/references/contracts.md) shows complete UUID/offset-date-time envelopes and command → projection → query proof. Canonical values default to inline event storage; explicit file-store mode stores all values externally, with no size threshold or fallback, and needs a separately included backend.

## Skill check

Try: “Create a disposable ORC experiment that runs one typed LLM sheet for tenant A, then make the same setup survive a single-process restart. Show how tenant B is isolated.” A satisfactory result selects in-memory and then SQLite; loads backend and ORC registrations; wires pub/sub, LMDB, poller, and provider; runs via public ORC APIs; reads a tenant-scoped projection/event trace; restarts against the same SQLite file; and proves repeated recovery does not create a second tick. No provider or production call is implied by this check.

## Evaluation lifetime

For judge registration, asynchronous completion handling, durable evidence and owned cleanup, read [orc-judges](../orc-judges/SKILL.md). Load evaluation registrations before the poller. At merged ORC `250de6e6de2ad95647ef6da4c69220c2bd631279`, explicit attachments run without the Living Description flag and may target any existing sheet node; the flag gates default researcher judges. Native assessment requests/outcomes are durable, while their execution still uses process-local background futures. Managed GEPA has a separate task-ledger recovery path: restore custom metric registrations and capabilities before workers, load GEPA registrations, and explicitly own recovery schedules; see [GEPA readiness](../orc-judges/references/gepa-readiness.md). This source review does not establish automatic restart execution or bounded capacity for attached judges; timeout/cancel alone does not join model or judge bodies before closing the store.

## Versioned family shutdown evidence

At the earlier inspected merge pin `1851212396cced2fc4533fda30b824bd4b691390`, execution leases and shared budget admission were implemented, while a reproduced cancellation ordering/publication defect could leave a cancelled active child without its durable trace and root cancellation committed without prompt delivery. Reproduce before attributing that defect to a later checkout. Keep owned body draining and strict family readiness; a timeout/cancellation request is not proof of complete cancellation or joined work. Follow [proof limits](../orc-tools/references/current-proofs-and-limits.md) rather than disabling useful budgets or relaxing readiness.

## Durable recursive researchers

Use [orc-repl-researcher](../orc-repl-researcher/SKILL.md) when the runtime includes adaptive researcher nodes. Enable real startup/periodic tenant recovery, reconstruct trusted process-local capabilities, and preserve the original campaign deadline/identity/budget. Configure JVM heap and projection cache independently. Epoch acceptance fences durable results; it does not guarantee instant stale-worker exit or once-only external provider spend. Use [pattern reuse](../orc-researcher-pattern-reuse/SKILL.md) when adding ontology/ColBERT, explicit index readiness and deliberate background processor topology.

## Follow application and model contracts before live admission

When the experiment adds domain commands, projections or queries, read [orc-grain-application](../orc-grain-application/SKILL.md) before declaring them, even in a disposable fixture. It covers generated-Var collisions, direct-processor authorization and effect concurrency boundaries; runtime wiring alone does not supply these contracts.

Before paid calls, compile the actual registered generation output contracts through the consuming SIO path. Mocking the ORC executor can prove tree control while hiding invalid provider schemas. On the documented strict repair stack, nested generated objects must explicitly declare `:closed true`. Use [model contract preflight](../orc-model-sio/references/contract-preflight.md), then verify exact live requests and parsed writes.

## Standard-node fallback revision

Configured fallback is integrated in merged ORC `4966c8e35e3bb5939570bfc645eac52a8d18eb6e`, with its pinned SIO and client dependencies. Register every candidate provider in worker and recovery context before workers start. Configure `:fallback-models` and `:fallback-policy` on existing standard model nodes; no separate wrapper or consumer parser is required. Candidate configuration is retained with published workflows; sticky researcher selection belongs to one run/role and has saved-quantum recovery evidence. See [configured model fallback](../orc-model-sio/references/configured-model-fallback.md) for exact pins, budget/deadline and first-visible-output stream boundaries; historical local/open-PR checkpoints are not the current adoption status.
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall