@awebai/oats 0.22.0

package/docs/oats-lock.schema.json

@@ -0,0 +1,175 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://oats.dev/schemas/oats-lock.schema.json",
+  "title": "OATS lockfile (oats-lock.json)",
+  "description": "Scope-local lockfile. lockfileVersion 2 records BOTH levels of the capability-materialization model: `packages` locks the transport unit (exact source + commit + selected root + payload integrity + package-identity dependencies) and `capabilities` locks the installed entity (the materialized artifact under .agents/capabilities/installed/<id>/, its provider package, its dedicated manifest path inside that package, its artifact integrity, and its executable trust). Both maps are REQUIRED. lockfileVersion 1 (per-capability marketplace locks) remains readable and usable and converts only through explicit migration. The earlier transitional package-root spelling of lockfileVersion 2 — package rows carrying `capabilities`/`trustedCapabilities`/`depsIntegrity`, and/or no top-level capability map — is UNSUPPORTED: it is rejected as an invalid lock, never converted and never partially interpreted. A lock never advances silently on restore.",
+  "type": "object",
+  "required": [
+    "lockfileVersion"
+  ],
+  "oneOf": [
+    {
+      "title": "lockfileVersion 2 — package provenance + materialized capability identity",
+      "type": "object",
+      "required": [
+        "lockfileVersion",
+        "packages",
+        "capabilities"
+      ],
+      "properties": {
+        "lockfileVersion": {
+          "const": 2
+        },
+        "packages": {
+          "description": "Map of package identity → exact provenance of the transport unit for the full dependency closure at this scope. A package row proves WHERE the bytes came from; it does not describe an installed directory, because there is no persistent package store. Which capabilities a package supplies is read off the `capabilities` map's `package` back-reference, so the two levels can never disagree — a package row carrying a capability list, a trust list, or a dependency-closure digest is the unsupported transitional shape.",
+          "type": "object",
+          "propertyNames": {
+            "pattern": "^[a-z0-9][a-z0-9._-]*$"
+          },
+          "additionalProperties": {
+            "type": "object",
+            "required": [
+              "source",
+              "path",
+              "version",
+              "commit",
+              "integrity",
+              "dependencies"
+            ],
+            "properties": {
+              "source": {
+                "description": "Normalized acquisition source, in EXACTLY the writer's grammar: git:<url>@<ref>, path:<absolute-dir>, catalog:<id> for an originally bare catalog request, or catalog:<id>@<selector> for an originally explicit selector (the resolved commit is separate; official catalog identity grants no executable trust). It never carries a \"#<path>\" fragment — the selected package root is the entry's own \"path\" field. Parsed strictly: a payload that merely starts with a known scheme but is not valid for that kind (catalog:../evil, path:relative/dir) is an invalid lock, because update and the locked-template reader re-derive a source spec from this string and would reclassify it.",
+                "type": "string",
+                "pattern": "^(catalog:[a-z0-9][a-z0-9._-]*(@[^#]+)?|path:/[^#]*|git:(https?://|file://|git@|ssh://|git://)[^#]+)$"
+              },
+              "path": {
+                "description": "Canonical, repository-relative path of the SELECTED package root inside the source (the directory carrying oats-package.json). \".\" is the canonical spelling of the source root; git/catalog sources default to \"oats-package\" when the source contract selects nothing; path: sources are exact directories and always record \".\". Never normalized or repaired on read — a non-canonical spelling is an invalid lock. Only `oats update` may change it.",
+                "type": "string",
+                "pattern": "^(\\.|(?!~)(?![A-Za-z]:[/\\\\])(?!\\.\\.?(/|$))[^/\\\\]+(/(?!\\.\\.?(/|$))[^/\\\\]+)*)$",
+                "minLength": 1
+              },
+              "version": {
+                "description": "Version from the locked oats-package.json.",
+                "type": "string",
+                "minLength": 1
+              },
+              "commit": {
+                "description": "Exact git commit the package was acquired at (40-hex). For path: sources this is the string \"local\".",
+                "type": "string",
+                "pattern": "^([0-9a-f]{40}|local)$"
+              },
+              "integrity": {
+                "description": "sha256 tree hash of the validated package PAYLOAD (the selected package root as fetched, before capability projection). It proves the exact distribution bytes and is what bare restore re-verifies before reprojecting. Materialized node_modules are excluded here — a capability's runtime closure is part of its own materialized artifact integrity.",
+                "type": "string",
+                "pattern": "^sha256-[0-9a-f]{64}$"
+              },
+              "dependencies": {
+                "description": "Package identities of direct dependencies, each a key of this lock's packages map. ALWAYS recorded — an empty array when the package has none, so a reader never has to distinguish absent from empty. Package-identity references only, never source strings.",
+                "type": "array",
+                "items": {
+                  "type": "string",
+                  "pattern": "^[a-z0-9][a-z0-9._-]*$"
+                },
+                "uniqueItems": true
+              }
+            },
+            "additionalProperties": false
+          }
+        },
+        "capabilities": {
+          "description": "Map of capability ID → the materialized installed entity at .agents/capabilities/installed/<id>/. REQUIRED (empty object when the scope locks nothing). Every entry names the package that supplied it; that package MUST be a key of this lock's `packages` map.",
+          "type": "object",
+          "propertyNames": {
+            "minLength": 1
+          },
+          "additionalProperties": {
+            "type": "object",
+            "required": [
+              "version",
+              "package",
+              "path",
+              "integrity",
+              "trusted"
+            ],
+            "properties": {
+              "version": {
+                "description": "Version from the capability's own oats.json (independent of the provider package's version).",
+                "type": "string",
+                "minLength": 1
+              },
+              "package": {
+                "description": "Identity of the provider package; must be a key of this lock's `packages` map.",
+                "type": "string",
+                "pattern": "^[a-z0-9][a-z0-9._-]*$"
+              },
+              "path": {
+                "description": "Canonical, package-relative path of the capability's DEDICATED root inside the provider package — the directory carrying its oats.json. Records exactly what was projected, so a package that moves a capability root is visible as a change. \".\" occurs only for an already-published legacy package whose capability root is the package root; newly authored packages use dedicated roots such as \"capabilities/<slug>\".",
+                "type": "string",
+                "pattern": "^(\\.|(?!~)(?![A-Za-z]:[/\\\\])(?!\\.\\.?(/|$))[^/\\\\]+(/(?!\\.\\.?(/|$))[^/\\\\]+)*)$",
+                "minLength": 1
+              },
+              "integrity": {
+                "description": "sha256 tree hash of the MATERIALIZED capability artifact — every byte under .agents/capabilities/installed/<id>/, including its generated .oats-installation.json provenance file and its materialized runtime closure (node_modules). This is the only thing executable trust binds to.",
+                "type": "string",
+                "pattern": "^sha256-[0-9a-f]{64}$"
+              },
+              "trusted": {
+                "description": "Whether this capability's executable surface (commands, hooks, and launch-environment authority) is approved at exactly this artifact integrity. Reset to false whenever the artifact integrity changes. Official catalog identity never grants it; there is no package-level approval.",
+                "type": "boolean"
+              }
+            },
+            "additionalProperties": false
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    {
+      "title": "lockfileVersion 1 — legacy per-capability marketplace locks (readable and usable; converts only through explicit migration)",
+      "type": "object",
+      "required": [
+        "lockfileVersion",
+        "capabilities"
+      ],
+      "properties": {
+        "lockfileVersion": {
+          "const": 1
+        },
+        "capabilities": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "object",
+            "required": [
+              "source",
+              "version",
+              "integrity"
+            ],
+            "properties": {
+              "source": {
+                "description": "marketplace:<id>@<version>, git:<url>, or path:<dir>.",
+                "type": "string",
+                "minLength": 1
+              },
+              "version": {
+                "type": "string",
+                "minLength": 1
+              },
+              "commit": {
+                "type": "string"
+              },
+              "integrity": {
+                "type": "string",
+                "pattern": "^sha256-[0-9a-f]{64}$"
+              },
+              "trustedExecutables": {
+                "type": "boolean"
+              }
+            },
+            "additionalProperties": true
+          }
+        }
+      },
+      "additionalProperties": false
+    }
+  ]
+}

package/docs/oats-package.schema.json

@@ -0,0 +1,129 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://oats.dev/schemas/oats-package.schema.json",
+  "title": "OATS distribution package manifest (oats-package.json)",
+  "description": "Manifest at a distribution-package root. A package is the source, dependency, integrity, review and atomic-update unit — it is TRANSPORT, not the installed entity. Acquisition stages the package in a temporary transaction directory, validates the whole selected payload, MATERIALIZES each declared capability into .agents/capabilities/installed/<id>/, writes the exact lock, and discards staging; there is no persistent package store. Every package must therefore export at least one capability, and each capability entry must name a DEDICATED capability root whose declared paths and symlinks all resolve inside it, so the materialized artifact is self-contained, independently hashable and independently trustable. Config templates are optional package SOURCE MATERIAL, never installed behavior: `oats install` applies none of them. Install never ambiently loads undeclared files.",
+  "type": "object",
+  "required": [
+    "package",
+    "version",
+    "description",
+    "compatibility",
+    "capabilities"
+  ],
+  "properties": {
+    "package": {
+      "description": "Package identity. Namespaced separately from capability IDs; unique at one config scope.",
+      "type": "string",
+      "pattern": "^[a-z0-9][a-z0-9._-]*$"
+    },
+    "version": {
+      "type": "string",
+      "minLength": 1
+    },
+    "description": {
+      "type": "string",
+      "minLength": 1
+    },
+    "compatibility": {
+      "type": "object",
+      "properties": {
+        "oats": {
+          "description": "OATS kernel compatibility floor. Accepted grammar exactly: >=x.y.z, ^x.y.z, or exact x.y.z.",
+          "type": "string",
+          "pattern": "^(>=|\\^)?\\d+\\.\\d+\\.\\d+$"
+        }
+      },
+      "required": [
+        "oats"
+      ],
+      "additionalProperties": false
+    },
+    "capabilities": {
+      "description": "Package-relative DEDICATED capability roots, each containing one capability oats.json. At least one is required — config-only and empty packages are rejected. A root of \".\" (the package root itself) is READ COMPATIBILITY for already-published packages only (e.g. oats.authoring@1.0.0, which is capabilities:[\".\"] and ships no templates at all): the compatibility reader accepts it whenever the manifest does not carry `configTemplates`, and rejects it as soon as it does, because a `configTemplates` manifest is unambiguously new. Authoring must never emit \".\"; newly authored packages use conventional roots such as \"capabilities/<slug>\". Paths must not escape the package root after symlink resolution, and everything the capability declares must resolve inside its OWN root — a capability that reaches package-only paths cannot be materialized and is rejected.",
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "string",
+        "minLength": 1,
+        "pattern": "^[^/].*$",
+        "not": {
+          "pattern": "(^|/)\\.\\.(/|$)"
+        }
+      },
+      "uniqueItems": true
+    },
+    "configTemplates": {
+      "description": "Named config TEMPLATES: complete reference oats-config.yaml files an adopter may explicitly adopt with `oats init --package`. A template is a recommended starting point that becomes ordinary local policy on adoption — adopters may change every copied setting, and package updates never rewrite an adopted config. Templates must stay portable: no secret, credential, account, machine path or provider-local ID. Installation applies none of them. This is the canonical spelling; a manifest may not carry both this and the legacy `configs`.",
+      "type": "object",
+      "propertyNames": {
+        "pattern": "^[a-z0-9][a-z0-9._-]*$"
+      },
+      "additionalProperties": {
+        "type": "object",
+        "required": [
+          "path"
+        ],
+        "properties": {
+          "path": {
+            "description": "Package-relative path to the template's oats-config.yaml. CANONICAL LOCATION: it must live under config-templates/ with a nonempty contained file path (e.g. config-templates/default/oats-config.yaml). The deprecated `configs` spelling is exempt so already-published 0.19 tags stay readable. Runtime validation enforces the same rule — see isCanonicalTemplatePath in lib/core.mjs.",
+            "type": "string",
+            "minLength": 1,
+            "pattern": "^config-templates/(?!\\.\\.?(/|$))[^/\\\\][^\\\\]*$",
+            "not": {
+              "pattern": "(^|/)\\.\\.(/|$)"
+            }
+          },
+          "description": {
+            "type": "string"
+          },
+          "default": {
+            "description": "At most one template may be marked default; it removes the need for --config at adoption.",
+            "type": "boolean"
+          }
+        },
+        "additionalProperties": false
+      }
+    },
+    "configs": {
+      "description": "DEPRECATED 0.19 spelling of `configTemplates`, readable only so immutable published 0.19 package tags stay consumable. Both spellings normalize to one descriptor shape; the diagnostic `legacySpelling` flag records which was used. It is NOT the discriminator for a \".\" capability root — published legacy packages exist with neither spelling. New authoring must emit `configTemplates`; carrying both spellings is an invalid manifest.",
+      "type": "object",
+      "propertyNames": {
+        "pattern": "^[a-z0-9][a-z0-9._-]*$"
+      },
+      "additionalProperties": {
+        "type": "object",
+        "required": [
+          "path"
+        ],
+        "properties": {
+          "path": {
+            "type": "string",
+            "minLength": 1,
+            "pattern": "^[^/].*$",
+            "not": {
+              "pattern": "(^|/)\\.\\.(/|$)"
+            }
+          },
+          "description": {
+            "type": "string"
+          },
+          "default": {
+            "type": "boolean"
+          }
+        },
+        "additionalProperties": false
+      }
+    },
+    "dependencies": {
+      "description": "Package source specifications (NOT capability IDs): official catalog selectors (e.g. \"oats.okf@v1.4.0\"), git:host/org/repo@ref, raw HTTPS/SSH git URLs with @ref, or local paths. No general semver ranges; the resolved closure is exact-locked.",
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      },
+      "uniqueItems": true
+    }
+  },
+  "additionalProperties": false
+}