@awebai/oats 0.24.12 → 0.25.0

package/docs/layers.md

@@ -34,8 +34,8 @@ Classic `kind`/`type`/`repo` declarations and config-targeted agent types are a
 
 ## Workspace, repository and adoption contracts
 
-- `oats-workspace.yaml` declares intended members, defaults, imports and optional provider-owned stores/team/catalog references.
-- `oats.yaml` advertises a repository's actual soul/package/knowledge exports and, for membership, a workspace backlink.
+- `oats-workspace.yaml` (v2) declares members, the pinned `packages:`, team labels, defaults per slot and per team, stores, the messaging payload and pinned `external:` souls.
+- `oats-membership.yaml` is a repository's half of the handshake: the workspace backlink plus an optional default team label. Everything under `souls/` and `capabilities/` is discoverable by convention (`private: true` opts out); there are no export lists.
 - Membership requires compatible observations on both sides; folder adjacency or a copied declaration is not admission.
 - External source import does not adopt the publisher's workspace. A framework repository may host its own development workspace without imposing it on consumers.
 - Operator choices and workspace defaults must respect source requirements. Git read access is not write permission, executable approval or messaging enrollment.
@@ -96,7 +96,7 @@ The work target is independent of source publication and knowledge placement. Pr
 
 ## Kernel briefings versus operational capabilities
 
-The kernel owns only what describes the layout it creates: the `instance-boundary` briefing (home versus `work/`), the selected work-mode briefing and config-declared injections. Knowing how to *operate* OATS (status, spawn, retire, soul discovery) and how to *configure* it (workspaces, packages, trust) is capability content — accepted as the official capabilities `oats.core` (explicit default on every soul, removable) and `oats.setup` (held by the onboarding-created `oats-setup-expert`). At the0.24 baseline those skills are still kernel-shipped; see the [workspace guide](workspaces.md#how-a-soul-knows-oats-accepted-direction-not-yet-shipped) and the adoption plan's distribution packages.
+The kernel owns only what describes the layout it creates: the `instance-boundary` briefing (home versus `work/`), the selected work-mode briefing and config-declared injections. Knowing how to *operate* OATS (status, spawn, retire, soul discovery) and how to *configure* it (workspaces, packages, approval) is capability content — the official capabilities `oats.core` (a workspace default via `defaults.capabilities`, removable per soul with `off`) and `oats.setup` (held by an onboarding expert), both provided by the `oats.framework` package; see [souls and instances](souls-and-instances.md#oats-operational-knowledge-is-a-capability).
 
 ## Capture and knowledge are separate
 

package/docs/oats-local.schema.json

@@ -0,0 +1,50 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://oats.dev/schemas/local-v2.json",
+  "title": "Deployment-local overrides v2 (oats-local.yaml)",
+  "description": "The operator's side of a workspace: which workspace this machine realizes, where member clones live when not at the taught convention, host-owned capability settings (absolute paths belong HERE, never in the workspace file), and souls disabled on this machine. Never shared through Git.",
+  "type": "object",
+  "required": ["schemaVersion", "workspace"],
+  "additionalProperties": false,
+  "properties": {
+    "schemaVersion": { "const": 2 },
+    "workspace": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^(?:git@[^@\\s]+|[^@\\s]+)$",
+      "description": "Repo ref of the workspace host; observed over the remote, need not be cloned."
+    },
+    "standalone": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^(?:git@[^@\\s]+|[^@\\s]+)$",
+      "description": "Repo ref to realize in the STANDALONE view (decision 10): its own souls and from: here capabilities plus oats.core (decision 25), no workspace lookup. Use when the repo's workspace cannot be read; `workspace:` still names the repo you point the kernel at."
+    },
+    "clones": {
+      "type": "object",
+      "propertyNames": { "type": "string", "pattern": "^[^\\s@/][^\\s@]*/[^\\s@]+$" },
+      "additionalProperties": { "type": "string", "minLength": 1 },
+      "description": "<repo key>: <path on this machine> for member clones outside the convention."
+    },
+    "settings": {
+      "type": "object",
+      "propertyNames": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]*$" },
+      "additionalProperties": {
+        "type": "object",
+        "propertyNames": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_.-]*$" }
+      },
+      "description": "<capability>: { <key>: <value> } host-owned values the manifests ask for."
+    },
+    "souls": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "disabled": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }
+        }
+      }
+    }
+  }
+}

package/docs/oats-membership.schema.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://oats.dev/schemas/membership-v2.json",
+  "title": "Repository membership backlink v2 (oats-membership.yaml)",
+  "description": "The repo's half of the reciprocal handshake: it names the workspace it belongs to, plus an optional default team label for the repo's items. Nothing else. A backlink is consent, not admission — the workspace must list the repo too.",
+  "type": "object",
+  "required": ["schemaVersion", "workspace"],
+  "additionalProperties": false,
+  "properties": {
+    "schemaVersion": { "const": 2 },
+    "workspace": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^(?:git@[^@\\s]+|[^@\\s]+)$",
+      "description": "Repo ref of the workspace host, without revision."
+    },
+    "team": {
+      "type": "string",
+      "pattern": "^[a-z0-9][a-z0-9._-]*$",
+      "description": "Default team label for souls and capabilities in this repo that carry no `team:` of their own."
+    }
+  }
+}

package/docs/oats-workspace.schema.json

@@ -1,68 +1,153 @@
 {
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "https://oats.dev/schemas/workspace-v1.json",
-  "title": "Portable workspace definition v1",
-  "description": "Data shape only; hosting identity, reciprocal membership and provider readiness are verified separately.",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://oats.dev/schemas/workspace-v2.json",
+  "title": "Workspace declaration v2 (oats-workspace.yaml)",
+  "description": "Data shape only. Members carry NO revision (a member is always its latest state); `external` sources REQUIRE a full 40-hex commit; absolute filesystem paths are refused anywhere in this file (host paths belong in oats-local.yaml). Reciprocal membership is observed over Git remotes, not declared here.",
   "type": "object",
   "required": ["schemaVersion", "name"],
   "additionalProperties": false,
   "properties": {
-    "schemaVersion": { "const": 1 },
-    "name": { "type": "string", "minLength": 1 },
-    "members": { "type": "array", "items": { "$ref": "#/$defs/repository" } },
-    "defaults": { "$ref": "https://oats.dev/schemas/soul-v1.json#/$defs/defaults" },
-    "knowledge": {
-      "type": "object", "required": ["stores"], "additionalProperties": false,
-      "properties": { "stores": { "type": "array", "items": { "$ref": "https://oats.dev/schemas/soul-v1.json#/properties/knowledge" } } }
+    "schemaVersion": { "const": 2 },
+    "name": { "$ref": "#/$defs/slug" },
+    "members": {
+      "type": "array",
+      "uniqueItems": true,
+      "items": { "$ref": "#/$defs/memberRef" },
+      "description": "Repo refs without revision. Each becomes a member only when its oats-membership.yaml names this workspace back."
+    },
+    "packages": {
+      "type": "object",
+      "propertyNames": { "$ref": "#/$defs/packageId" },
+      "additionalProperties": { "$ref": "#/$defs/packageVersion" },
+      "description": "The ONLY versioned things: <package-id>: <version | git ref with @revision>."
     },
     "teams": {
-      "type": "object", "propertyNames": { "$ref": "#/$defs/alias" },
-      "properties": { "private": { "const": "per-human" } },
-      "additionalProperties": {
-        "type": "object", "required": ["provider", "id"], "additionalProperties": false,
-        "properties": { "provider": { "$ref": "https://oats.dev/schemas/soul-v1.json#/$defs/capability" }, "id": { "type": "string", "minLength": 1 } }
-      }
+      "type": "object",
+      "propertyNames": { "$ref": "#/$defs/label" },
+      "additionalProperties": { "$ref": "#/$defs/team" },
+      "description": "Org team labels. A label never gates, restricts or partitions anything."
+    },
+    "defaults": { "$ref": "#/$defs/defaults" },
+    "stores": {
+      "type": "object",
+      "propertyNames": { "$ref": "#/$defs/slug" },
+      "additionalProperties": { "$ref": "#/$defs/memberRef" },
+      "description": "Knowledge stores, declared once: <name>: <repo ref>."
     },
-    "catalogs": {
-      "type": "array", "items": {
-        "type": "object", "required": ["source"], "additionalProperties": false,
-        "properties": { "source": { "$ref": "#/$defs/source" }, "revision": { "$ref": "#/$defs/revision" }, "path": { "$ref": "#/$defs/path" } }
+    "messaging": {
+      "type": "object",
+      "description": "Opaque provider payload consumed by the messaging-slot capability. May carry byTeam: { <team label>: <payload> } — the kernel merges base ⊕ byTeam[soul.team] and strips byTeam before the provider sees it (decision 23).",
+      "properties": {
+        "byTeam": {
+          "type": "object",
+          "propertyNames": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" },
+          "additionalProperties": { "type": "object" }
+        }
       }
     },
-    "imports": { "type": "array", "items": { "$ref": "#/$defs/import" } }
+    "external": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/external" },
+      "description": "Souls adopted by reference from repos that are NOT members; pinned to a full commit."
+    }
   },
   "$defs": {
-    "source": { "type": "string", "pattern": "^git:.+$" },
-    "revision": { "type": "string", "minLength": 1 },
-    "path": { "type": "string", "minLength": 1, "description": "Canonical contained repository-relative path; the shared source codec enforces semantic path rules." },
-    "alias": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._-]*$" },
-    "repository": {
-      "type": "object", "required": ["source"], "additionalProperties": false,
-      "properties": { "source": { "$ref": "#/$defs/source" }, "revision": { "$ref": "#/$defs/revision" } }
+    "slug": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" },
+    "label": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]*$" },
+    "capabilityName": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]*$" },
+    "packageId": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]*$" },
+    "packageVersion": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^(?:v?\\d+(?:\\.\\d+)*(?:[-+][0-9A-Za-z.-]+)?|git:(?:git@[^@\\s/:]+:)?[^@\\s]+@(?:[0-9a-f]{40}|(?!-)(?!.*(?:\\.\\.|@\\{|\\^|~|:|\\?|\\*|\\[|\\\\|\\.lock$|\\.$|/$|^/))[!-?A-~]+))$",
+      "description": "Exactly two forms: a bare version (v2.1.3) resolved through the catalog, or git:<repo>@<ref> (a direct package ref). lib/packages.mjs#classifyPackageValue is the full grammar."
+    },
+    "memberRef": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^(?:git@[^@\\s]+|[^@\\s]+)$",
+      "description": "A repo ref (git:<host>/<path>, https://…, git@host:path.git, file:///…) with NO @revision."
+    },
+    "pinnedRef": {
+      "type": "string",
+      "pattern": "^(?:git@[^@\\s]+|[^@\\s]+)@[0-9a-f]{40}$",
+      "description": "<repo ref>@<full 40-hex commit OID>."
+    },
+    "repoKey": {
+      "type": "string",
+      "pattern": "^[^\\s@/][^\\s@]*/[^\\s@]+$",
+      "description": "Canonical repo identity <host>/<path> (or local/<abs-path> for file remotes), as produced by parseRepoRef(...).key."
     },
-    "import": {
-      "type": "object", "required": ["source", "soul", "revision", "alias"], "additionalProperties": false,
+    "fromLocation": {
+      "anyOf": [
+        { "const": "package" },
+        { "const": "here" },
+        { "$ref": "#/$defs/repoKey" }
+      ],
+      "description": "WHERE a capability comes from — a location, never a version."
+    },
+    "capabilityRef": {
+      "type": "object",
+      "required": ["from"],
+      "additionalProperties": false,
+      "properties": { "from": { "$ref": "#/$defs/fromLocation" } }
+    },
+    "capabilityChoice": { "anyOf": [{ "$ref": "#/$defs/capabilityRef" }, { "const": "off" }] },
+    "capabilityMap": {
+      "type": "object",
+      "propertyNames": { "$ref": "#/$defs/capabilityName" },
+      "additionalProperties": { "$ref": "#/$defs/capabilityChoice" }
+    },
+    "slotDefault": {
+      "anyOf": [
+        { "const": "none" },
+        {
+          "type": "object",
+          "maxProperties": 1,
+          "propertyNames": { "$ref": "#/$defs/capabilityName" },
+          "additionalProperties": { "$ref": "#/$defs/capabilityRef" }
+        }
+      ],
+      "description": "At most one capability fills a slot; `none` leaves it empty."
+    },
+    "team": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": { "description": { "type": "string" } }
+    },
+    "defaults": {
+      "type": "object",
+      "additionalProperties": false,
       "properties": {
-        "source": { "$ref": "#/$defs/source" },
-        "soul": { "$ref": "#/$defs/path" },
-        "revision": { "$ref": "#/$defs/revision" },
-        "alias": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" },
-        "adoption": {
-          "type": "object", "additionalProperties": false,
-          "properties": {
-            "teamAliases": { "type": "object", "propertyNames": { "$ref": "#/$defs/alias" }, "additionalProperties": { "$ref": "#/$defs/alias" } },
-            "providers": {
-              "type": "object", "additionalProperties": false,
-              "properties": {
-                "knowledge": { "$ref": "https://oats.dev/schemas/soul-v1.json#/$defs/defaultProvider" },
-                "messaging": { "$ref": "https://oats.dev/schemas/soul-v1.json#/$defs/defaultProvider" },
-                "tasks": { "$ref": "https://oats.dev/schemas/soul-v1.json#/$defs/defaultProvider" }
-              }
-            },
-            "bindings": { "type": "object" }
+        "capabilities": { "$ref": "#/$defs/capabilityMap" },
+        "knowledge": { "$ref": "#/$defs/slotDefault" },
+        "messaging": { "$ref": "#/$defs/slotDefault" },
+        "tasks": { "$ref": "#/$defs/slotDefault" },
+        "byTeam": {
+          "type": "object",
+          "propertyNames": { "$ref": "#/$defs/label" },
+          "additionalProperties": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": { "capabilities": { "$ref": "#/$defs/capabilityMap" } }
           }
         }
       }
+    },
+    "external": {
+      "type": "object",
+      "required": ["source", "soul"],
+      "additionalProperties": false,
+      "properties": {
+        "source": { "$ref": "#/$defs/pinnedRef" },
+        "soul": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "^(?![A-Za-z]:)(?!/)(?!.*(?:^|/)\\.{1,2}(?:/|$))[^/\\\\\u0000]+(?:/[^/\\\\\u0000]+)*$",
+          "description": "Repository-relative directory holding the soul's soul.yaml."
+        },
+        "team": { "$ref": "#/$defs/label" }
+      }
     }
   }
 }

package/docs/official-marketplace.md

@@ -10,14 +10,17 @@ or workspace membership alone does not make a package official.
 - Browse the catalog for the kernel/source version you use. Each package entry
   identifies its repository, release ref and payload root; capability aliases
   can point to the package that supplies them.
-- Today, `oats install <capability-or-package-id>` resolves official short names
-  through the CLI's catalog. For example, `oats install oats.okf --dir /absolute/scope`
-  selects the listed package; it does not enroll a team or adopt
-  the publisher's workspace. See [package operations](packages.md).
+- A workspace pins an official package by **bare version** in its
+  `packages:` map (`oats.okf: v2.1.3`); `oats sync` resolves it through the
+  catalog to an exact commit, locks it and asks for executable approval once
+  per version. A package outside the catalog is written `git:<repo>@<ref>`.
+  Pinning does not enroll a team or adopt the publisher's workspace. See
+  [packages](packages.md).
 - The Desktop marketplace view/search is **planned for the parity phase**, not
   shipped by this policy or by OATS 0.24. There is no new marketplace CLI verb.
-- **Discoverable ≠ installed ≠ approved.** Acquisition and exact locking are
-  separate from capability selection and per-capability executable approval.
+- **Discoverable ≠ pinned ≠ approved.** A catalog listing grants nothing; a
+  `packages:` pin selects a version; the lock's per-version approval is what
+  lets its executables run. Nothing is installed.
   Official status never grants trust, credentials or permission to run code.
 - Listing also does not prove that every harness, provider combination or
   deployment profile is supported. Check the package's declared compatibility,