This document catalogues the modular primitives and engines of the Refarm monorepo.
| Package | Purpose | Maturity | Status |
|---|---|---|---|
@refarm.dev/tractor |
The Sovereign Microkernel & Plugin Host | 🟡 Stable-ish | Internal |
@refarm.dev/windmill |
Automation Engine & Infrastructure | 🟠 Alpha | Internal |
@refarm.dev/health |
Stratified Health & Policy Auditor | 🟢 Production | Release-profiled; held |
These packages define foundational interoperability layers between Refarm and its plugins. They are release-policy candidates, not an automatic publish list: publication remains held by the daily-driver gate or explicit human override.
| Package | Tests | Status | Publishing |
|---|---|---|---|
@refarm.dev/storage-contract-v1 |
✅ Conformance | 🟢 Candidate | kernel-candidates; held |
@refarm.dev/sync-contract-v1 |
✅ Conformance | 🟢 Candidate | kernel-candidates; held |
@refarm.dev/identity-contract-v1 |
✅ Conformance | 🟢 Candidate | kernel-candidates; held |
@refarm.dev/channel-policy-v1 |
✅ Fixture Validation | 🟡 Candidate | kernel-candidates + vault-seed-ready; held |
@refarm.dev/skill-contract-v1 |
✅ Manifest/Surface Validation | 🟡 Proof-gated | held until engine dogfood smoke |
These packages provide the source:v1 librarian boundary. The base contract
and authenticated-web fixture adapter are now selected for the consumer-pulled
vault-seed-ready lane after the T3 proof. The other adapters remain
release-profiled and checked, but held until Refarm dogfood, the official
vault-seed checkout, or agents-lab needs that package leaf directly.
source-dispatch is intentionally absent until one of those paths needs
source:v1 through dispatch-surface with an executable proof.
| Package | Purpose | Publishing |
|---|---|---|
@refarm.dev/source-contract-v1 |
Versioned source:v1 capability contract and conformance suite |
vault-seed-ready; held |
@refarm.dev/source-git |
Clean cached git checkout provider for remote repositories | release-profiled; held |
@refarm.dev/source-local |
Live local working-tree provider with dirty/untracked status | release-profiled; held |
@refarm.dev/source-web |
Authenticated web capture fixture adapter that materializes redacted, replayable local snapshots through source:v1 |
consumer-proven; vault-seed-ready; held |
The T3 requirements-vault pressure activated @refarm.dev/source-web as a
sanitized fixture adapter. It deliberately reports source:v1 snapshots as
location.kind = "local" and carries web session/cache/redaction details in
package-owned provenance. Accessible-system discovery, login strategy, and
source-specific selectors remain downstream.
These packages are the neutral slices identified by the requirements-vault activation packet and must not enter release policy before package-local checks and downstream proofs exist.
| Candidate | Purpose | Publishing |
|---|---|---|
@refarm.dev/enrichment-contract-v1 |
Deterministic record/note enrichment provider contract with dry-run/apply evidence, diagnostics, and provenance | consumer-proven; vault-seed-ready; held |
@refarm.dev/records-contract-v1 |
Graph/content envelope for records, sections, relations, attachments, source references, hashes, and review state; YAML-LD codec lives at the package subpath | consumer-proven; vault-seed-ready; held |
@refarm.dev/content-projection |
Markdown/MDX frontmatter, wikilink, and inline-link projection into records:v1 records without owning acquisition or rendering |
candidate; vault-seed-ready; held |
@refarm.dev/local-surface |
Local-first surface manifest, DS-backed HTML rendering, white-label launch plan, and quality report helpers without owning provider adapters or Homestead runtime | consumer-proven; vault-seed-ready; held |
@refarm.dev/ds-astro |
Product-neutral Astro/MDX DS component bindings and component-map metadata without owning downstream content vocabulary | candidate; vault-seed-ready; held |
@refarm.dev/skill-contract-v1 is the schema/conformance helper for native
Refarm skill surfaces. It parses SKILL.md-style content into
SkillManifestV1, records source hashes, requires explicit capabilities, and
defaults to plan-only, declared-capability tool access. It also builds
host-policy-checkable invocation plans, requests, pre-runtime decisions, and
host-owned execution receipts from engine-call evidence. It also builds
pi/skill surface declarations for package manifest handoff from a validated
manifest plus a relative package asset path. The first engine dogfood smoke
uses source:v1 through @refarm.dev/source-local; external dgk-skills or
agents-lab fixtures must stay wrapper/evidence based. The first
agents-lab git-workflow wrapper smoke records upstream source evidence without
installing or executing the external skill; the first DGK vault-search
wrapper smoke records upstream vault-seed source evidence and validates a
package-declared pi/skill surface without executing dgk or Obsidian CLI.
It also records activation preflight and now has a helper for converting
plugin-manifest validation, source integrity, and host install-policy decisions
into install evidence. Runtime-host execution and accepted host install policy
remain the next promotion gates.
It is deliberately not a second plugin system. Packages and plugin manifests remain the distribution/trust boundary; skills are declared as surfaces or assets inside that bundle and are consumed by runtime hosts only after policy and adapter proof.
The vault-seed-ready selection is a pre-publication handoff lane for packages
that vault-seed can consume as local tarballs before the full daily-driver
release. It is not an automatic npm publication promise: the lane remains
manual-approval gated, product-neutral, and downstream-owned for vault-specific
CLI labels, copy, notebooks, routes, and UX.
| Package | Purpose | Publishing |
|---|---|---|
@refarm.dev/artifact-contract-v1 |
Artifact/provenance manifests for Lab datasets, outbox manifests, and notebook snapshots | vault-seed-ready; held |
@refarm.dev/channel-policy-v1 |
Channel delivery evidence, rate limits, dry-run reports, and review gates | kernel-candidates + vault-seed-ready; held |
@refarm.dev/effort-contract-v1 |
Effort/task contract dependency for dispatch evidence | vault-seed-ready; held |
@refarm.dev/quality-contract-v1 |
Declared quality/lint profiles, findings, reports, conformance, and checker contract | vault-seed-ready; held |
@refarm.dev/storage-contract-v1 |
Versioned storage:v1 contract used by wallet/storage seams |
kernel-candidates + vault-seed-ready; held |
@refarm.dev/identity-contract-v1 |
Versioned identity:v1 signing contract used by credentials seams |
kernel-candidates + vault-seed-ready; held |
@refarm.dev/source-contract-v1 |
Versioned source:v1 support contract for source-web |
vault-seed-ready; held |
@refarm.dev/enrichment-contract-v1 |
Deterministic enrichment reports for source-linked records | consumer-proven; vault-seed-ready; held |
@refarm.dev/records-contract-v1 |
Neutral records envelope plus YAML-LD subpath for proof-backed front matter bridges | consumer-proven; vault-seed-ready; held |
@refarm.dev/process-handoff |
Build-free tokenized process specs and runner adapters | vault-seed-ready; held |
@refarm.dev/release-engine |
Package acceptance and release-policy summaries | vault-seed-ready; held |
@refarm.dev/ds |
Design tokens, theme CSS, and build-free HTML helpers consumed by vault admin/Lab UI | vault-seed-ready; held |
@refarm.dev/heartwood |
Cryptographic core dependency for Silo | vault-seed-ready; held |
@refarm.dev/dispatch-surface |
Product-neutral dispatch surface contracts | vault-seed-ready; held |
@refarm.dev/silo |
Namespaced secret collection and storage | vault-seed-ready; held |
@refarm.dev/storage-memory |
Volatile storage:v1 reference provider for consumer proof and smoke wallets |
vault-seed-ready; held |
@refarm.dev/credentials-contract-v1 |
credentials:v1 issue, verify, present, wallet, and local status-list revocation seams |
consumer-proven; vault-seed-ready; held |
@refarm.dev/identity-heartwood |
Heartwood-backed Ed25519 identity:v1 reference provider |
vault-seed-ready; held |
@refarm.dev/source-web |
Authenticated-web replay fixture adapter over source:v1 |
consumer-proven; vault-seed-ready; held |
@refarm.dev/content-projection |
Markdown/MDX projection helpers for frontmatter, wikilinks, inline links, and valid records:v1 output |
candidate; vault-seed-ready; held |
@refarm.dev/local-surface |
Local-first surface manifest, DS-backed HTML rendering, white-label launch plan, and quality report helpers | consumer-proven; vault-seed-ready; held |
@refarm.dev/ds-astro |
Product-neutral Astro/MDX DS component bindings and component-map metadata | candidate; vault-seed-ready; held |
This layer waits for the Pi and multi-layer plugin architecture proofs before entering the release lane.
| Package | Tests | Status | Publishing |
|---|---|---|---|
@refarm.dev/plugin-manifest |
✅ Validation | 🟡 Deferred | v0.2.0+ candidate |
| Package | Type | Backend | Maturity |
|---|---|---|---|
@refarm.dev/storage-sqlite |
Storage | OPFS/SQLite | 🟡 Beta |
@refarm.dev/storage-memory |
Storage | In-Memory | 🟢 Stable |
@refarm.me/identity-nostr |
Identity | Nostr/Relays | 🟠 Alpha (Experimental) |
@refarm.dev/sync-crdt |
Sync | Automerge-like | 🟠 Alpha |
@refarm.dev/silo: Context & Secret Provisioning.@refarm.dev/fence: Scope & Boundary Auditing.@refarm.dev/thresher: Data Ingestion & Transformation.@refarm.dev/heartwood: Cryptographic Core (WASM).@refarm.dev/process-handoff: Build-free tokenized process launch helpers and provenance-ready runner adapters.@refarm.dev/cli: Shared CLI primitives, process adapters, JSON envelopes, and compatibility Refarm contracts. The executable Refarm app lives inapps/refarm.
"We cultivate the code as we cultivate the soil: with patience, honesty, and respect for the cycle."