@chronofile/edge

The Chronofile edge runtime: the part that ships inside products. Inside a desktop app it is an embedded library; on a plain rented machine it is a process exposing the same interface over HTTP to a web application's backend.

node ../packaging/npm_install_edge.mjs   # npm ci, or npm install until the platform packages are published
npm run typecheck    # tsc, strict
npm test             # node --test
npm run lint         # eslint, flat config in this directory
npm run generate:types   # api/types.ts from ../api/openapi.yaml

Plain npm ci refuses the lockfile while the four @chronofile/edge-<os>-<cpu> optional dependencies are not on the registry, since npm cannot lock a package it cannot resolve. The helper falls back to npm install --no-save on exactly that failure and fails on any other, as CI does.

What is here

| Directory | | | ----------- | ------------------------------------------------------------------------------- | | api/ | generated types — do not edit | | cache/ | the local store: a SQLite subset of the evidence store (K3), WAL, content-keyed | | hostapi/ | the Core API client, the payload builders, and chrono serve | | intake/ | the line-JSON protocol to the bundled chronofile-intake worker | | outbox/ | the sync loop: drain facts, resume uploads, apply events | | probe/ | the hardware report — measured, never acted on locally | | session/ | session negotiation and the plan cache | | rungs/ | the weights manifest for the C1–C3 rungs, which run in bundled sidecars | | sidecar/ | chronofile-asr, the Rust whisper.cpp wrapper that is the C3 speech rung | | runtime/ | the desktop runtime (chronofile-runtime) and its SDK client, RuntimeClient | | examples/ | the reference client, an Electron main process, and request bodies |

The desktop runtime

chronofile-runtime is the process a desktop app (or an MCP server) talks to: it accepts files as durable jobs, prepares them with the bundled intake worker, uploads them, asks the service to index them and reports what is ready, and it forwards Search and Analyze to the service. RuntimeClient is its SDK, and startRuntime() starts it. The contract is docs/DESKTOP-RUNTIME.md in the repository; npx chronofile-runtime manifest prints it as data.

import { safeStorage } from 'electron';
import { startRuntime } from '@chronofile/edge';

// In Electron's main process, after app.whenReady(); plain Node passes { memoryOnly: true }.
const runtime = await startRuntime({ dataDir, serviceUrl, credentials: { store: safeStorage } });
await runtime.setGrants(['/Users/me/Movies']);
await runtime.setCredentials(tenantToken);
const job = await runtime.submit({ path: '/Users/me/Movies/holiday.mov', collectionId: 'holiday' });
const done = await runtime.waitForJob(job.job_id);
const search = await runtime.search({ query: 'the dog jumps into the pool' });

Credentials

credentials is required. With { store } (Electron's safeStorage, or any object with its three methods) the store wraps a key for the data directory, and the runtime seals its device credential and its control key with it; the runtime can outlive the app and the next start reconnects. With { memoryOnly: true } nothing is written and the runtime stops with the process that started it. The service credential given to setCredentials is held in memory only, in either mode. Plain-text credential files an earlier version wrote are migrated on the first protected start. examples/electron-main.mjs is a complete Electron main process; docs/DESKTOP-RUNTIME.md ("Credentials") is the contract.

Search: which videos

// One video (a job names its video as `source.timeline_id`).
await runtime.search({ query, timelineIds: [id] });
// A selection, from any groups.
await runtime.search({ query, timelineIds: [a, b, c] });
// Every video the account can see.
await runtime.search({ query });

• With timelineIds, the service searches exactly those videos, whichever groups they are in. Order and duplicates do not matter; at most 500 ids per request.
• With no selector, it searches every video the account can see, across groups. The SDK sends no scope and makes no library() call.
• An empty folder is sent as timelineIds: [], which the service refuses (400 CF-E012); it is never widened to every video.
• A video whose original file is unplugged can still be searched: its indexed evidence lives in the service.
• timelineId and groupId keep their meaning. Legacy library: true means the runtime's library group only; combined with groupId, timelineId or timelineIds it is refused (400 CF-E012) before any call.

The one rule

The edge holds no policy (I-10). It executes the placement plan mechanically — local:<rung> runs the rung, api calls the mirror, disabled reports the capability unavailable and lets the service account for it — and all knowledge of why stays on the service, where it can change without a release.

It may not import from service/, lanes/, answers/, registry/models/, chrono_platform/worker/ or chrono_platform/deploy/. Gate ci/gates/g8_distribution.py walks the import graph on every commit.

Two implementations, one contract

The chrono CLI is Python and this library is TypeScript, and both implement the edge verbs. Neither language can host the other's runtime, so the two agree by being held to written-down answers rather than by sharing code:

• The cache schema — cache/schema.sql and cli/edge/schema.sql are byte identical, and tests/unit/test_edge_cache.py fails if they drift.
• The host payloads — cli/serialize.py generates tests/fixtures/host_payload_vectors.json; hostapi/payloads.test.ts rebuilds each case here and compares the encoded strings (I-12).
• resolve() — tests/fixtures/resolve_vectors.json.

All three files are committed so this suite runs on a machine with no Python.

See PUBLISHING.md for the release process and THIRD-PARTY.md for bundled third-party software.