Files
hypit/docs/guide/runtime.md
2026-08-17 14:03:54 +08:00

3.8 KiB

title, description
title description
Runtime The execution boundary outside Narratage source and Core.

Runtime

Narratage keeps three decisions separate:

Owner Decides
Workspace Which source files and local assets compilation may read
Runtime Profile Which environmental packages may be used
Local Runtime How Builds are queued, executed, stored and observed

Core is a domain neutral state machine. It accepts facts, derives Commands and verifies returned Records. It does not start processes, read credentials, choose Providers or know that a Build makes video.

@narratage/runtime-local is the default execution environment. It owns one Worker, scheduler, Build queue and SQLite database. Those are one implementation, not user-selectable pseudo-components.

Runtime Profile

The Profile contains only environmental choices that genuinely vary:

{
  "format": "narratage.runtime-profile@1",
  "runtime": {
    "use": "@narratage/runtime-local",
    "config": {
      "dataRoot": ".narratage/runtimes/local",
      "artifacts": {
        "use": "@narratage/artifact-store-fs",
        "config": { "path": "artifacts" }
      },
      "credentials": {
        "environment": { "use": "@narratage/credential-store-env" }
      },
      "endpoints": {
        "media": { "use": "@narratage/provider-media-local" }
      }
    }
  }
}
  • artifacts selects where generated bytes are stored.
  • credentials selects stores for explicit credential references.
  • endpoints selects exact Provider implementations and their configuration.

Installing a package only makes an implementation available. A Profile must select it. The Profile contains no Workspace, author imports or creative routing.

Local state

Selecting a Profile writes a project pointer. Execution data stays under dataRoot:

.narratage/
  runtime
  runtimes/
    local/
      runtime.sqlite
      artifacts/
      worker/
      programs/

check and plan do not create Runtime data. SQLite stores Build facts, Operations and queue state; Artifact bytes stay in the selected Artifact Store; secrets stay in the selected Credential Stores.

The Workspace is resolved independently from the explicit --workspace, the project containing the Runtime pointer, or the entry source directory. Runtime configuration cannot widen source access.

Queue and concurrency

build admits a fresh Build and returns. The Worker advances every runnable Build while Core preserves each Build's graph dependencies. Endpoint packages declare Provider and capability limits, so work from separate Builds shares the exact external capacity that performs it.

Cancellation is best effort. Queued work is withdrawn before it starts; running work stops receiving new commands and an Endpoint may try to cancel an already submitted external operation. Completed output is retained and never rolled back.

Managed Programs

An Endpoint may declare a long-lived helper such as a warm local WhisperX service. The Endpoint owns its probe and optional start command; the local Runtime only supervises it.

narratage programs status
narratage programs up
narratage programs down

Program commands load Endpoint packages only. They do not open SQLite, Artifact Stores or Credential Stores.

Lifecycle

narratage runtime use narratage.runtime.json
narratage runtime up
narratage runtime status
narratage runtime logs
narratage runtime down

runtime up starts the local Worker. build submits work; status, queue and cancel observe or control it. A terminal Build is not resumed. Reusing an earlier result is an explicit Candidate in a new .svrun, not hidden Runtime behavior.

Runtime packages are trusted local deployment code. npm or pnpm owns their installed versions; the Runtime does not implement another package manager or claim that metadata is a sandbox.