docs: frozen v1.0 bundle format specs (manifest, agent-card, o1 package structure)

2026-08-03 19:56:51 +03:00
commit e2f76e4027
4 changed files with 221 additions and 0 deletions
@@ -0,0 +1,74 @@
+# Depo Package Manifest — Spec v1.0 (DRAFT)
+
+One tag = one releasable business. The manifest is the contract between the
+authoring machine and any target that pulls the package.
+
+## File
+
+`manifest.json` at package root.
+
+## Schema
+
+```json
+{
+  "schema_version": "1.0",
+  "package_id": "hitridge-business-o1",
+  "display_name": "O1 — Consignment Refurbished Electronics",
+  "version": "0.1.0",
+  "license": "proprietary",
+  "requires": {
+    "odoo": ">=18.0",
+    "agent_runtime": ">=1.0"
+  },
+  "layers": {
+    "odoo_modules": ["aura_business_core", "hitridge_venture_o1"],
+    "agents": ["o1-sellers-recruiter", "o1-test-operator", "o1-closer", "o1-compliance"],
+    "docs": ["docs/playbook.md", "docs/agreement-template.odt", "docs/test-checklist.md"],
+    "config": ["config/channels.json", "config/pricing-rules.json"]
+  },
+  "install": {
+    "order": ["odoo_modules", "config", "agents", "docs"],
+    "verify": [
+      "all odoo_modules installed",
+      "all agents registered in runtime",
+      "venture menu visible",
+      "no secrets in package (secrets_scan)"
+    ]
+  },
+  "rollback": {
+    "strategy": "install previous tag; reverse install order"
+  }
+}
+```
+
+## Rules
+
+1. **Versioning** — semver. Every change to any layer bumps the version. A tag
+   in the depot repo = the release.
+2. **Signing** — manifest is hashed (SHA-256) and signed (ed25519). Targets
+   verify the signature before anything is applied. No signature = refuse.
+3. **Idempotency** — installing the same version twice is a no-op; upgrading
+   follows the module version-bump path.
+4. **Never ships in a package**:
+   - env secrets / credentials / API keys (env vars injected at target only)
+   - live data (rows are generated by the target, never imported from authoring)
+   - learned memories (brain capabilities ship; memories are empty seeds)
+   - anything target-specific (URLs, IDs, absolute paths)
+5. **Fresh-target assumption** — target must be the Aura tower Odoo (or the
+   manifest declares the base modules it needs).
+6. **Rollback is designed in** — reverse install order; each layer must be
+   undoable atomically.
+
+## Install sequence (target side, pull model)
+
+1. Fetch package (from depot git tag or registry).
+2. Verify signature + hash.
+3. Run `install.order` in sequence, each step verified before the next.
+4. Run `install.verify` checklist. Any failure = abort + rollback, target
+   reports state, never silently continues.
+
+## Local mirror (authoring side)
+
+`depot-state.json` (SQLite or JSON): which package version is deployed to which
+target, when, by whom, verification result. This is what enables diff, upgrade,
+and rollback decisions. It never deploys anything itself.