@godspeedai/cognate-profile 0.1.0 → 0.1.2

package/README.md

@@ -1,14 +1,73 @@
 # @godspeedai/cognate-profile
 
-Profiles are pure composition (spec §29, §40.J/K): a named, ordered
-selection of registered component names plus per-component options. They
-add no kernel concepts. `defineProfile` validates (non-empty name, unique
-non-empty component names) and returns a deep-frozen `ProfileDefinition`
-with `description` defaulting to `""`.
-
-`resolveProfile(profile, registry)` looks up each requested component name
-in a caller-supplied `ComponentEntry[]` registry, in profile order. An
-unknown name resolves with reason `"unknown component"`; an entry with
-`supported: false` resolves with its own `reason`; only supported entries
-have `contribute(profile.options[name])` called. Every requested-but-missing
-component is reported in `unresolved` — nothing is silently dropped.
+Declarative composition for Cognate applications: `defineProfile` names an ordered selection of registered components plus their configuration, and `resolveProfile` turns that selection into contributions. Profiles add no kernel concepts — they only select and configure what packages already register.
+
+**When to use this package:** you are defining a reusable application composition (a "profile") or building the registry a profile resolves against. Ready-made profiles include
+[`@godspeedai/cognate-profile-harness`](https://www.npmjs.com/package/@godspeedai/cognate-profile-harness)
+and [`@godspeedai/cognate-profile-copilot`](https://www.npmjs.com/package/@godspeedai/cognate-profile-copilot).
+
+## Installation
+
+```sh
+bun add @godspeedai/cognate-profile
+```
+
+Requires [Bun](https://bun.sh) >= 1.4.0.
+
+## Quick start
+
+```ts
+import { defineProfile, resolveProfile } from "@godspeedai/cognate-profile";
+import type { ComponentEntry } from "@godspeedai/cognate-profile";
+
+// A registry: entries a package provides, each producing one contribution.
+const registry: ComponentEntry<string[]>[] = [
+  {
+    name: "sessions",
+    package: "@godspeedai/cognate-runtime-bun",
+    supported: true,
+    contribute: () => ["sessions"],
+  },
+  {
+    name: "agents",
+    package: "@godspeedai/cognate-runtime-bun",
+    supported: true,
+    contribute: (options) => [`agents:${JSON.stringify(options ?? null)}`],
+  },
+];
+
+// Validate and freeze the profile. Names must be unique and non-empty.
+const profile = defineProfile({
+  name: "research-workbench",
+  description: "Sessions plus a bounded agent pool",
+  components: ["sessions", "agents"],
+  options: { agents: { max: 2 } },
+});
+
+const resolved = resolveProfile(profile, registry);
+resolved.contributions; // [{ name: "sessions", ... }, { name: "agents", contribution: 'agents:{"max":2}' }]
+resolved.unresolved; // every requested name that could not be included, with a reason
+```
+
+`resolveProfile` walks the profile's components in order, calling `contribute(profile.options[name])` only for supported entries. An unknown name is reported with reason `"unknown component"`; an entry marked `supported: false` is reported with its own reason. Nothing is ever silently dropped.
+
+## What the types guarantee
+
+- `defineProfile` returns a deep-frozen `ProfileDefinition`: the component list and options cannot be mutated after definition, and validation errors throw `ProfileError` at definition time, not resolution time.
+- `ResolvedProfile` separates `contributions` (in profile order, each tagged with its source package) from `unresolved` (requested but absent, each with a reason), so a composition can show exactly what it is running and why anything is missing.
+- `ComponentEntry.supported: false` records an unavailable component explicitly, with a human-readable `reason`.
+
+## Limitations
+
+- Pure data: this package validates and resolves — it mounts nothing, starts nothing, and knows no registry by itself. The caller owns what `contribute` returns and what happens with the resolved contributions.
+- Options are opaque to this package; they are passed through to each entry's `contribute` untouched.
+
+## Related packages
+
+- [`@godspeedai/cognate-kernel-api`](https://www.npmjs.com/package/@godspeedai/cognate-kernel-api) — the kernel contract profiles select against, without extending it.
+- [`@godspeedai/cognate-runtime-bun`](https://www.npmjs.com/package/@godspeedai/cognate-runtime-bun) — the runtime compositions are typically resolved into.
+- [`@godspeedai/cognate`](https://www.npmjs.com/package/@godspeedai/cognate) — the SDK umbrella.
+
+## License
+
+Apache-2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@godspeedai/cognate-profile",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "defineProfile: reusable application compositions that select and configure components without new kernel concepts (spec §29).",
   "type": "module",
   "license": "Apache-2.0",
@@ -22,6 +22,6 @@
     ".": "./src/index.ts"
   },
   "dependencies": {
-    "@godspeedai/cognate-kernel-api": "^0.1.0"
+    "@godspeedai/cognate-kernel-api": "^0.1.2"
   }
 }