@uos/core

@uos/core is the headless engine for UOS. It owns typed packs, manifests, shared schemas, diff and plan generation, apply transactions, rollback primitives, and cross-plugin contracts. It does not own guided setup UX, operator dashboards, or provider-specific connector logic.

Built as part of the UOS split workspace on top of Paperclip, which remains the upstream control-plane substrate.

Boundary Summary

• Owns the shared engine, schema, plan, apply, rollback, import, export, and compatibility contract surface.
• Feeds lifecycle evidence into uos-plugin-setup-studio and uos-plugin-operations-cockpit.
• Exposes governed integration contracts to uos-plugin-connectors and the narrow tool plugins.
• Does not own guided setup UX, operator dashboards, or provider-specific auth and webhook control.

What This Repo Owns

• Typed packs, manifests, schemas, and versioned contracts.
• Diff, plan, apply, rollback, import, export, and reconciliation primitives.
• Reusable lifecycle evidence that setup and cockpit plugins can render.
• Stable extension contracts for setup, operations, connectors, departments, and tools.
• Demo fixtures that exercise the engine without redefining product boundaries.

Runtime Form

• Headless package first. Any bundled plugin scaffold exists only to exercise or demo the engine contract, not to become the primary operator surface.

Highest-Value Workflows

• Resolve a desired pack or manifest into an auditable apply plan.
• Execute apply, rollback, import, or export transactions safely.
• Produce raw lifecycle evidence that other plugins can surface to operators.
• Guard cross-repo contracts so downstream plugins fail fast when core changes.
• Keep shared schemas and compatibility rules stable across slimmer plugins.

Key Connections and Operating Surfaces

• GitHub, package registries, pnpm/npm, CI systems, and release tooling needed to build, version, compare, and ship the core safely.
• Cloudflare, Vercel, Render, Docker hosts, cloud runtimes, Postgres/SQLite, and secret stores when core fixtures need real infrastructure-backed transaction coverage.
• Artifact stores, changelogs, and compatibility metadata when releases need reproducible engine evidence across repos.
• Minimal provider or admin-surface touch points required to keep core contracts honest, without turning this repo into the connector or cockpit layer.

KPI Targets

• Plan generation remains deterministic for 100% of maintained fixture packs.
• Apply and rollback coverage exists for 100% of supported release paths.
• Shared schema and contract regressions fail fast in CI before downstream repos drift silently.
• Import and export round-trip fidelity stays >= 95% on the maintained fixture corpus.

Implementation Backlog

Now

• Stabilize the canonical packs, manifests, and engine contracts with explicit failure boundaries.
• Build replayable fixtures for apply, rollback, import, export, and reconciliation.
• Harden cross-repo contract checks so core changes fail fast when slimmer plugins drift.

Next

• Improve evidence output for every lifecycle action, including diffs, approvals, and verification artifacts.
• Reduce engine ambiguity by removing leftover monolith-era responsibilities from docs and demos.
• Finalize compatibility rules for the slimmer setup, cockpit, connector, and tool layers.

Later

• Move from template-by-template hardening to generalized pack certification.
• Expand contract testing across more maintained pack families without growing the core surface area.

Local Plugin Use

curl -X POST http://127.0.0.1:3100/api/plugins/install \
  -H "Content-Type: application/json" \
  -d '{"packageName":"<absolute-path-to-this-repo>","isLocalPath":true}'

Validation

npm install
npm run check
npm run plugin:typecheck
npm run plugin:test