@almadar/std 17.0.2 → 17.1.0

package/behaviors/lolo/spec/cli/mcp-server.replay.goldens.json

@@ -10,12 +10,13 @@
           "from": "serving",
           "event": "MCP_LINE_IN",
           "payload": {
-            "line": "   "
+            "line": "   ",
+            "seq": 0
           },
           "expect": {
             "emits": [
               {
-                "event": "MCP_PUMP",
+                "event": "MCP_INPUT_NEXT",
                 "payload": {}
               }
             ]
@@ -31,12 +32,13 @@
           "from": "serving",
           "event": "MCP_LINE_IN",
           "payload": {
-            "line": "{\"jsonrpc\":\"2.0\",\"method\":\"notifications/initialized\"}"
+            "line": "{\"jsonrpc\":\"2.0\",\"method\":\"notifications/initialized\"}",
+            "seq": 0
           },
           "expect": {
             "emits": [
               {
-                "event": "MCP_PUMP",
+                "event": "MCP_INPUT_NEXT",
                 "payload": {}
               }
             ]
@@ -52,7 +54,8 @@
           "from": "serving",
           "event": "MCP_LINE_IN",
           "payload": {
-            "line": "not json"
+            "line": "not json",
+            "seq": 0
           },
           "expect": {
             "emits": [
@@ -63,7 +66,7 @@
                 }
               },
               {
-                "event": "MCP_PUMP",
+                "event": "MCP_INPUT_NEXT",
                 "payload": {}
               }
             ]
@@ -79,7 +82,8 @@
           "from": "serving",
           "event": "MCP_LINE_IN",
           "payload": {
-            "line": "{\"jsonrpc\":\"2.0\",\"id\":7,\"method\":\"ping\",\"params\":{}}"
+            "line": "{\"jsonrpc\":\"2.0\",\"id\":7,\"method\":\"ping\",\"params\":{}}",
+            "seq": 0
           },
           "expect": {
             "emits": [
@@ -90,7 +94,7 @@
                 }
               },
               {
-                "event": "MCP_PUMP",
+                "event": "MCP_INPUT_NEXT",
                 "payload": {}
               }
             ]
@@ -106,7 +110,8 @@
           "from": "serving",
           "event": "MCP_LINE_IN",
           "payload": {
-            "line": "{\"jsonrpc\":\"2.0\",\"id\":7,\"method\":\"resources/subscribe\",\"params\":{}}"
+            "line": "{\"jsonrpc\":\"2.0\",\"id\":7,\"method\":\"resources/subscribe\",\"params\":{}}",
+            "seq": 0
           },
           "expect": {
             "emits": [
@@ -117,7 +122,7 @@
                 }
               },
               {
-                "event": "MCP_PUMP",
+                "event": "MCP_INPUT_NEXT",
                 "payload": {}
               }
             ]
@@ -133,7 +138,8 @@
           "from": "serving",
           "event": "MCP_LINE_IN",
           "payload": {
-            "line": "{\"jsonrpc\":\"2.0\",\"id\":7,\"method\":\"prompts/get\",\"params\":{\"name\":\"nope\"}}"
+            "line": "{\"jsonrpc\":\"2.0\",\"id\":7,\"method\":\"prompts/get\",\"params\":{\"name\":\"nope\"}}",
+            "seq": 0
           },
           "expect": {
             "emits": [
@@ -144,7 +150,7 @@
                 }
               },
               {
-                "event": "MCP_PUMP",
+                "event": "MCP_INPUT_NEXT",
                 "payload": {}
               }
             ]
@@ -160,7 +166,8 @@
           "from": "serving",
           "event": "MCP_LINE_IN",
           "payload": {
-            "line": "{\"jsonrpc\":\"2.0\",\"id\":7,\"method\":\"prompts/list\",\"params\":{}}"
+            "line": "{\"jsonrpc\":\"2.0\",\"id\":7,\"method\":\"prompts/list\",\"params\":{}}",
+            "seq": 0
           },
           "expect": {
             "emits": [
@@ -171,7 +178,7 @@
                 }
               },
               {
-                "event": "MCP_PUMP",
+                "event": "MCP_INPUT_NEXT",
                 "payload": {}
               }
             ]
@@ -187,7 +194,8 @@
           "from": "serving",
           "event": "MCP_LINE_IN",
           "payload": {
-            "line": "{\"jsonrpc\":\"2.0\",\"id\":7,\"method\":\"tools/call\",\"params\":{\"name\":\"make_coffee\",\"arguments\":{}}}"
+            "line": "{\"jsonrpc\":\"2.0\",\"id\":7,\"method\":\"tools/call\",\"params\":{\"name\":\"make_coffee\",\"arguments\":{}}}",
+            "seq": 0
           },
           "expect": {
             "emits": [
@@ -198,7 +206,7 @@
                 }
               },
               {
-                "event": "MCP_PUMP",
+                "event": "MCP_INPUT_NEXT",
                 "payload": {}
               }
             ]
@@ -214,7 +222,8 @@
           "from": "serving",
           "event": "MCP_LINE_IN",
           "payload": {
-            "line": "{\"jsonrpc\":\"2.0\",\"id\":\"abc\",\"method\":\"ping\",\"params\":{}}"
+            "line": "{\"jsonrpc\":\"2.0\",\"id\":\"abc\",\"method\":\"ping\",\"params\":{}}",
+            "seq": 0
           },
           "expect": {
             "emits": [
@@ -225,7 +234,7 @@
                 }
               },
               {
-                "event": "MCP_PUMP",
+                "event": "MCP_INPUT_NEXT",
                 "payload": {}
               }
             ]
@@ -257,7 +266,8 @@
           "from": "serving",
           "event": "MCP_LINE_IN",
           "payload": {
-            "line": "{\"jsonrpc\":\"2.0\",\"id\":7,\"method\":\"initialize\",\"params\":{\"protocolVersion\":\"2025-06-18\"}}"
+            "line": "{\"jsonrpc\":\"2.0\",\"id\":7,\"method\":\"initialize\",\"params\":{\"protocolVersion\":\"2025-06-18\"}}",
+            "seq": 0
           },
           "expect": {
             "emits": [
@@ -268,7 +278,7 @@
                 }
               },
               {
-                "event": "MCP_PUMP",
+                "event": "MCP_INPUT_NEXT",
                 "payload": {}
               }
             ]
@@ -300,7 +310,8 @@
           "from": "serving",
           "event": "MCP_LINE_IN",
           "payload": {
-            "line": "{\"jsonrpc\":\"2.0\",\"id\":7,\"method\":\"initialize\",\"params\":{\"protocolVersion\":\"1999-01-01\"}}"
+            "line": "{\"jsonrpc\":\"2.0\",\"id\":7,\"method\":\"initialize\",\"params\":{\"protocolVersion\":\"1999-01-01\"}}",
+            "seq": 0
           },
           "expect": {
             "emits": [
@@ -311,7 +322,7 @@
                 }
               },
               {
-                "event": "MCP_PUMP",
+                "event": "MCP_INPUT_NEXT",
                 "payload": {}
               }
             ]
@@ -343,7 +354,8 @@
           "from": "serving",
           "event": "MCP_LINE_IN",
           "payload": {
-            "line": "{\"jsonrpc\":\"2.0\",\"id\":7,\"method\":\"tools/list\",\"params\":{}}"
+            "line": "{\"jsonrpc\":\"2.0\",\"id\":7,\"method\":\"tools/list\",\"params\":{}}",
+            "seq": 0
           },
           "expect": {
             "emits": [
@@ -353,32 +365,11 @@
                   "line": "{\"jsonrpc\":\"2.0\",\"id\":7,\"result\":{\"tools\":[{\"name\":\"validate\",\"description\":\"Validate a .lolo or .orb program with the full compiler pipeline. The bar is 0 errors and 0 warnings; each finding has a code, a path and a suggested fix.\",\"inputSchema\":{\"type\":\"object\",\"properties\":{\"path\":{\"type\":\"string\",\"description\":\"The .lolo or .orb file\"},\"final\":{\"type\":\"boolean\",\"description\":\"Also run the finished-app checks\"}},\"required\":[\"path\"]}},{\"name\":\"complete\",\"description\":\"What is valid at a character offset in a .lolo file: keywords, effect operators, pattern tags and props, installed behaviors' import paths, traits, orbitals and typed config keys.\",\"inputSchema\":{\"type\":\"object\",\"properties\":{\"path\":{\"type\":\"string\",\"description\":\"The .lolo file\"},\"offset\":{\"type\":\"integer\",\"minimum\":0,\"description\":\"Byte offset of the cursor\"}},\"required\":[\"path\",\"offset\"]}},{\"name\":\"format\",\"description\":\"Pretty-print a .lolo or .orb file in the syntax it is written in. Returns the text; `write: true` also rewrites the file.\",\"inputSchema\":{\"type\":\"object\",\"properties\":{\"path\":{\"type\":\"string\"},\"write\":{\"type\":\"boolean\",\"description\":\"Rewrite the file in place\"}},\"required\":[\"path\"]}},{\"name\":\"operators\",\"description\":\"The language's operators (the only functions and effects a program can call). With `name`: that operator's full entry (params, return type, examples). Without: every operator's name, category and description, optionally for one `category`.\",\"inputSchema\":{\"type\":\"object\",\"properties\":{\"name\":{\"type\":\"string\"},\"category\":{\"type\":\"string\"}},\"required\":[]}},{\"name\":\"patterns\",\"description\":\"The UI patterns `render-ui` accepts. With `name`: that pattern's full entry (every prop with its types and enum values). Without: every pattern's name, category and description, optionally for one `category`.\",\"inputSchema\":{\"type\":\"object\",\"properties\":{\"name\":{\"type\":\"string\"},\"category\":{\"type\":\"string\"}},\"required\":[]}},{\"name\":\"behaviors\",\"description\":\"The installed behaviors you compose with `uses`. With no `scopes`: every installed package's behaviors, a package that does not lower listed under `skipped`. With `scopes` (e.g. `almadar-std/ui/core` or a `<prefix>/<topic>`): every behavior there with its description, capabilities, level and traits.\",\"inputSchema\":{\"type\":\"object\",\"properties\":{\"scopes\":{\"type\":\"array\",\"items\":{\"type\":\"string\"}},\"exposure\":{\"type\":\"array\",\"items\":{\"type\":\"string\",\"enum\":[\"app\",\"experience\",\"palette\",\"both\",\"internal\"]}}},\"required\":[]}},{\"name\":\"describe_behavior\",\"description\":\"One behavior's contract: its knobs (typed config), events, transitions and pages. `spec` is `<prefix>/<name>`, `<prefix>/<name>.traits.<Trait>` or `<prefix>/<name>.orbitals.<Orbital>`.\",\"inputSchema\":{\"type\":\"object\",\"properties\":{\"spec\":{\"type\":\"string\"}},\"required\":[\"spec\"]}},{\"name\":\"read_behavior\",\"description\":\"A behavior's source file, to read as a worked example of the language. `spec` as in `describe_behavior`.\",\"inputSchema\":{\"type\":\"object\",\"properties\":{\"spec\":{\"type\":\"string\"}},\"required\":[\"spec\"]}},{\"name\":\"play\",\"description\":\"Fire events through a program's state machines in the real kernel, in order. Each step names a `trait` and an `event`, with an optional `payload` and an optional `from` state to start that trait in. Returns, per step, every trait that moved: the transition, the guards tried, the effects run and the events emitted, plus each trait's state after the step.\",\"inputSchema\":{\"type\":\"object\",\"properties\":{\"path\":{\"type\":\"string\"},\"steps\":{\"type\":\"array\",\"items\":{\"type\":\"object\",\"properties\":{\"trait\":{\"type\":\"string\"},\"event\":{\"type\":\"string\"},\"payload\":{\"type\":\"object\"},\"from\":{\"type\":\"string\"}},\"required\":[\"trait\",\"event\"]}}},\"required\":[\"path\",\"steps\"]}},{\"name\":\"test\",\"description\":\"The exhaustive walk: every transition of every trait, generated from the graph and played headlessly from the initial state. Returns passed/failed/skipped counts and each case's outcome; a failure names the state it expected and the one it got.\",\"inputSchema\":{\"type\":\"object\",\"properties\":{\"path\":{\"type\":\"string\"}},\"required\":[\"path\"]}},{\"name\":\"reference\",\"description\":\"The language reference, generated from the compiler. With no `topic`: every construct, the vocabulary (keywords, tags, sigils, effects, types) and the validation-code topics. With a construct `topic` (e.g. `Trait`, `Entity`, `Listen`, `Page`): its description, its fields and real examples from the installed std. Also `vocabulary` and `codes/<category>` (every code with what it rejects).\",\"inputSchema\":{\"type\":\"object\",\"properties\":{\"topic\":{\"type\":\"string\"}},\"required\":[]}},{\"name\":\"evaluate\",\"description\":\"Evaluate one S-expression (as JSON, e.g. ['+', 2, 3]) with the language's evaluator, with optional `entity` and `payload` bindings for @entity and @payload.\",\"inputSchema\":{\"type\":\"object\",\"properties\":{\"expr\":{\"description\":\"The S-expression as JSON\"},\"entity\":{\"type\":\"object\"},\"payload\":{\"type\":\"object\"}},\"required\":[\"expr\"]}}]}}"
                 }
               },
-              {
-                "event": "MCP_PUMP",
-                "payload": {}
-              }
-            ]
-          }
-        }
-      ]
-    },
-    {
-      "id": "pump-asks-std-stdio-lines-for-the-next-line",
-      "note": "Line framing is std-stdio-lines' (spec/connect/stdio-lines.replay.goldens.json); the server acknowledges each line with INPUT_NEXT.",
-      "steps": [
-        {
-          "trait": "McpServer",
-          "from": "serving",
-          "event": "MCP_PUMP",
-          "payload": {},
-          "expect": {
-            "emits": [
               {
                 "event": "MCP_INPUT_NEXT",
                 "payload": {}
               }
-            ],
-            "state": "serving"
+            ]
           }
         }
       ]
@@ -1775,7 +1766,8 @@
           "from": "serving",
           "event": "MCP_LINE_IN",
           "payload": {
-            "line": "[1,2]"
+            "line": "[1,2]",
+            "seq": 0
           },
           "expect": {
             "emits": [
@@ -1786,7 +1778,7 @@
                 }
               },
               {
-                "event": "MCP_PUMP",
+                "event": "MCP_INPUT_NEXT",
                 "payload": {}
               }
             ]
@@ -1802,7 +1794,8 @@
           "from": "serving",
           "event": "MCP_LINE_IN",
           "payload": {
-            "line": "42"
+            "line": "42",
+            "seq": 0
           },
           "expect": {
             "emits": [
@@ -1813,7 +1806,7 @@
                 }
               },
               {
-                "event": "MCP_PUMP",
+                "event": "MCP_INPUT_NEXT",
                 "payload": {}
               }
             ]
@@ -1829,7 +1822,8 @@
           "from": "serving",
           "event": "MCP_LINE_IN",
           "payload": {
-            "line": "\"hello\""
+            "line": "\"hello\"",
+            "seq": 0
           },
           "expect": {
             "emits": [
@@ -1840,7 +1834,7 @@
                 }
               },
               {
-                "event": "MCP_PUMP",
+                "event": "MCP_INPUT_NEXT",
                 "payload": {}
               }
             ]
@@ -1856,7 +1850,8 @@
           "from": "serving",
           "event": "MCP_LINE_IN",
           "payload": {
-            "line": "{\"jsonrpc\":\"2.0\"}"
+            "line": "{\"jsonrpc\":\"2.0\"}",
+            "seq": 0
           },
           "expect": {
             "emits": [
@@ -1867,7 +1862,7 @@
                 }
               },
               {
-                "event": "MCP_PUMP",
+                "event": "MCP_INPUT_NEXT",
                 "payload": {}
               }
             ]
@@ -1883,12 +1878,13 @@
           "from": "serving",
           "event": "MCP_LINE_IN",
           "payload": {
-            "line": "{\"jsonrpc\":\"2.0\",\"method\":\"notifications/cancelled\",\"params\":{\"requestId\":3}}"
+            "line": "{\"jsonrpc\":\"2.0\",\"method\":\"notifications/cancelled\",\"params\":{\"requestId\":3}}",
+            "seq": 0
           },
           "expect": {
             "emits": [
               {
-                "event": "MCP_PUMP",
+                "event": "MCP_INPUT_NEXT",
                 "payload": {}
               }
             ]

package/behaviors/lolo/spec/cli/orb-compile.replay.goldens.json

@@ -70,6 +70,12 @@
            "takesValue": true,
            "repeatable": false
           },
+          {
+           "name": "renderer",
+           "aliases": [],
+           "takesValue": true,
+           "repeatable": false
+          },
           {
            "name": "patterns",
            "aliases": [],
@@ -250,7 +256,7 @@
         "payload": {
          "status": 400,
          "body": "",
-         "stderr": "usage: orb compile <FILE> [-o|--output DIR] [-s|--shell SHELL] [-m|--mode MODE] [--frontend SHELL] [--backend SHELL] [--backend-url URL] [--patterns PATH] [--dev-logs] [--host HOST] [--emit-orb PATH] [--web-client] [--skip-lint]"
+         "stderr": "usage: orb compile <FILE> [-o|--output DIR] [-s|--shell SHELL] [-m|--mode MODE] [--frontend SHELL] [--backend SHELL] [--backend-url URL] [--renderer RENDERER] [--patterns PATH] [--dev-logs] [--host HOST] [--emit-orb PATH] [--web-client] [--skip-lint]"
         }
        }
       ]
@@ -295,7 +301,7 @@
         "payload": {
          "status": 400,
          "body": "",
-         "stderr": "usage: orb compile <FILE> [-o|--output DIR] [-s|--shell SHELL] [-m|--mode MODE] [--frontend SHELL] [--backend SHELL] [--backend-url URL] [--patterns PATH] [--dev-logs] [--host HOST] [--emit-orb PATH] [--web-client] [--skip-lint]"
+         "stderr": "usage: orb compile <FILE> [-o|--output DIR] [-s|--shell SHELL] [-m|--mode MODE] [--frontend SHELL] [--backend SHELL] [--backend-url URL] [--renderer RENDERER] [--patterns PATH] [--dev-logs] [--host HOST] [--emit-orb PATH] [--web-client] [--skip-lint]"
         }
        }
       ]
@@ -341,7 +347,7 @@
         "payload": {
          "status": 400,
          "body": "",
-         "stderr": "usage: orb compile <FILE> [-o|--output DIR] [-s|--shell SHELL] [-m|--mode MODE] [--frontend SHELL] [--backend SHELL] [--backend-url URL] [--patterns PATH] [--dev-logs] [--host HOST] [--emit-orb PATH] [--web-client] [--skip-lint]"
+         "stderr": "usage: orb compile <FILE> [-o|--output DIR] [-s|--shell SHELL] [-m|--mode MODE] [--frontend SHELL] [--backend SHELL] [--backend-url URL] [--renderer RENDERER] [--patterns PATH] [--dev-logs] [--host HOST] [--emit-orb PATH] [--web-client] [--skip-lint]"
         }
        }
       ]
@@ -840,7 +846,7 @@
         "payload": {
          "status": 400,
          "body": "",
-         "stderr": "usage: orb compile <FILE> [-o|--output DIR] [-s|--shell SHELL] [-m|--mode MODE] [--frontend SHELL] [--backend SHELL] [--backend-url URL] [--patterns PATH] [--dev-logs] [--host HOST] [--emit-orb PATH] [--web-client] [--skip-lint]"
+         "stderr": "usage: orb compile <FILE> [-o|--output DIR] [-s|--shell SHELL] [-m|--mode MODE] [--frontend SHELL] [--backend SHELL] [--backend-url URL] [--renderer RENDERER] [--patterns PATH] [--dev-logs] [--host HOST] [--emit-orb PATH] [--web-client] [--skip-lint]"
         }
        }
       ]

package/behaviors/lolo/spec/cli/orb-packages.lolo

@@ -1,6 +1,6 @@
 app orb-packages-spec [
   version: "1.0.0",
-  description: "Design contract for `orb add|update|remove|list [--global]` and `orb engines add|update|remove|list`, the client of the npm registry. Golden = orbital-cli packages.rs and engines_cmd.rs today; the change is that a package is installed at one exact version from its npm tarball and the lockfile {name, version, url, integrity} replaces bun (ranges are refused with ORB_PACKAGE_RANGE). Tarballs are valid sources only under the registry knob (default https://registry.npmjs.org; the origin the composed std-http-client trait is configured with, its host a net grant) or the sourceOrigin knob; any other host is refused ORB_PACKAGE_SOURCE. A name resolves through the registry knob: GET /<name> (the packument, slash encoded %2f) for update, GET /<name>/<version> for add. Integrity is dist.integrity, `sha512-` plus the base64 sha512 of the downloaded gzip tarball; a mismatch installs nothing. The tarball is gunzipped and read as ustar by the kernel (a codec refusal is ORB_PACKAGE_ARCHIVE (<code>)), every entry must sit under package/ (ORB_PACKAGE_LAYOUT), the files are written into node_modules/.orb-staging/<name>@<version>, the old package is removed, the staging directory is renamed into place and only then is the lock entry recorded and the lockfile written. A package kind is read from its package.json: orbLanguage = language, orb = behaviors, orbVocabulary = language pack, orbProgram.kind shell|desktop = shell|desktop; no kind is refused ORB_PACKAGE_NOT_ORB with `<name>: not an orb package (its package.json declares none of orbLanguage, orb, orbVocabulary, orbProgram)`. add: installs, then checks each named or newly appeared package; a clean one prints `added <name>@<version> (<kinds joined by , >)`; one that declares no kind or does not load is refused and, if this call added it, removed again; any refusal fails with `not added:` and one indented `<name>: <problem>` line per refusal; an install that yields no package fails `installed nothing for <specs>`. update: resolves every non-linked orb package and every missing baseline package (the `baseline` knob: {name, registry} entries; core, std, the language packs, the typescript shell) like an upgrade from nothing, moving each to the highest non-deprecated stable version by semver order that is language-compatible (core: its orbLanguage.version satisfies the range this orb reads; every other package: its language range, orb, orbLanguage, orbVocabulary or orbProgram .language, the first present in the packument, is satisfied by the target core language, the orbLanguage.version of the core version this update installs, else of the installed core; core resolves first); a missing baseline package with no compatible version fails the update (the range this orb reads is the R of the `orb X.Y.Z (language R)` answer of `orb --version`, any other answer refuses the update; checks use std-semver; a version whose manifest records no language is treated as incompatible, never guessed, and named on stderr as `<name>@<version>: ORB_PACKAGE_NO_LANGUAGE (...)`, an unsatisfied one as `ORB_PACKAGE_INCOMPATIBLE`, only for versions newer than the installed one), written exact into the lockfile (a workspace-linked package is never updated), prints the list rows and, after them, one `<severity> update: <name> <from> → <to>: <advisory>` line for every applied version whose registry manifest carries orbRelease severity security or critical, removes again what this call added and does not load, records the update check, and fails `these packages do not load for this orb:` with one indented `<name>: <problem>` line each. update --global also keeps this host's orb binary package installed (the orbPlatforms knob maps the os/uname sysname and machine to @almadar/orb-darwin-arm64, -darwin-x64, -linux-x64, -linux-arm64 or -windows-x64), resolved like a baseline package in the registry knob but on its own compatibility rule: an orb platform package has no language range, so its newest stable, non-deprecated version is taken whose package.json declares orbReads, a range of core languages the target core language satisfies (no orbReads: skipped ORB_PACKAGE_NO_LANGUAGE; its orb and orbProgram blocks are not read); a package declaring orbReads is listed with kind `orb`; a host with no matching entry or whose os/uname fails gets one ORB_PACKAGE_PLATFORM line on stderr and no orb package is considered (the Windows host does not implement os/uname today). update --urgent (update only; any other command is refused with the usage line): every version may carry a top-level orbRelease { severity security|critical|normal, advisory (one line), fixes (a semver range of earlier versions it fixes) } in its registry manifest (none, or an unknown severity word, is normal); a package is urgent when a stable, non-deprecated version newer than the installed one is security or critical, declares fixes, the installed version satisfies fixes (std-semver) and the version passes the language check above; only urgent packages are updated, to the newest such version, through the same integrity check, staging swap and lockfile write; a baseline package that is not installed is never urgent; stdout is only the applied `<severity> update:` lines; an urgent version that fails the language check (ORB_PACKAGE_INCOMPATIBLE or ORB_PACKAGE_NO_LANGUAGE), whose fixes range std-semver refuses (ORB_PACKAGE_RELEASE), or whose download, integrity or install fails is not applied: the installed version stays, the call answers 500 and stderr names each refusal and each confirmed-urgent advisory, the vulnerable version is never replaced by a half-written one. remove: a workspace-linked package is refused ORB_PACKAGE_LINKED and its link is never deleted; a behavior package whose prefix a .lolo or .orb file still imports (skipping node_modules, .git, dist, target) is refused `refusing to remove '<name>': N file(s) still import '<prefix>/':` plus the files, one per line; otherwise prints `removed <name>` per name. list: one row per installed orb package, sorted by name, columns package (34), version (12), kinds joined by `, ` (26), then `ok` or the problem, ` (linked)` for a workspace link, and ` [<prefix>/, N behaviors]` for a behavior package; --json prints the rows { package, kinds, version, path, link, prefix?, behaviors?, problem } as pretty JSON; with no rows the table is empty and stderr says `orb: nothing is installed in <dir> (no @almadar/core or @almadar/std); run `orb update --global` to set the language up`. Without --global the project directory is used, falling back to the user store when there is no project. Engines: `engines add|update` install the pinned runtime-verify/compiled engine packages at the exact pinned version (`installed <package>@<version> (entry <bin> → <path>)`; a wrong version fails `<package>: expected version <v>, got <w>`, a missing bin entry `<package>: installed package has no `<bin>` bin entry`, a package not found after install `<package>: install reported success but the package was not found`), update prints `updated <package>: <old> → <new>` or `<package>@<old> already up to date` or `installed <package>@<version>`, remove prints `removed <package>`, list prints rows engine (16), package (32), version (12), link (6), path, or `not installed — <hint>`, --json the rows { engine, package, version, entry, path, installed, link }."
+  description: "Design contract for `orb add|update|remove|list [--global]` and `orb engines add|update|remove|list`, the client of the npm registry. Golden = orbital-cli packages.rs and engines_cmd.rs today; the change is that a package is installed at one exact version from its npm tarball and the lockfile {name, version, url, integrity} replaces bun (ranges are refused with ORB_PACKAGE_RANGE). Tarballs are valid sources only under the registry knob (default https://registry.npmjs.org; the origin the composed std-http-client trait is configured with, its host a net grant) or the sourceOrigin knob; any other host is refused ORB_PACKAGE_SOURCE. A name resolves through the registry knob: GET /<name> (the packument, slash encoded %2f) for update, GET /<name>/<version> for add. Integrity is dist.integrity, `sha512-` plus the base64 sha512 of the downloaded gzip tarball; a mismatch installs nothing. The tarball is gunzipped and read as ustar by the kernel (a codec refusal is ORB_PACKAGE_ARCHIVE (<code>)), every entry must sit under package/ (ORB_PACKAGE_LAYOUT), the files are written into node_modules/.orb-staging/<name>@<version>, the old package is removed, the staging directory is renamed into place and only then is the lock entry recorded and the lockfile written. A package kind is read from its package.json: orbLanguage = language, orb = behaviors, orbVocabulary = language pack, orbProgram.kind shell|desktop = shell|desktop; no kind is refused ORB_PACKAGE_NOT_ORB with `<name>: not an orb package (its package.json declares none of orbLanguage, orb, orbVocabulary, orbProgram)`. add: installs, then checks each named or newly appeared package; a clean one prints `added <name>@<version> (<kinds joined by , >)`; one that declares no kind or does not load is refused and, if this call added it, removed again; any refusal fails with `not added:` and one indented `<name>: <problem>` line per refusal; an install that yields no package fails `installed nothing for <specs>`. update: resolves every non-linked orb package and every missing baseline package (the `baseline` knob: {name, registry} entries; core, std, the language packs, the typescript shell) like an upgrade from nothing, moving each to the highest non-deprecated stable version by semver order that is language-compatible (core: its orbLanguage.version satisfies the range this orb reads; every other package: its language range, orb, orbLanguage, orbVocabulary or orbProgram .language, the first present in the packument, is satisfied by the target core language, the orbLanguage.version of the core version this update installs, else of the installed core; core resolves first); a missing baseline package with no compatible version fails the update (the range this orb reads is the R of the `orb X.Y.Z (language R)` answer of `orb --version`, any other answer refuses the update; checks use std-semver; a version whose manifest records no language is treated as incompatible, never guessed, and named on stderr as `<name>@<version>: ORB_PACKAGE_NO_LANGUAGE (...)`, an unsatisfied one as `ORB_PACKAGE_INCOMPATIBLE`, only for versions newer than the installed one), written exact into the lockfile (a workspace-linked package is never updated), prints the list rows and, after them, one `<severity> update: <name> <from> → <to>: <advisory>` line for every applied version whose registry manifest carries orbRelease severity security or critical, removes again what this call added and does not load, records the update check, and fails `these packages do not load for this orb:` with one indented `<name>: <problem>` line each. update --global also keeps this host's orb binary package installed (the orbPlatforms knob maps the os/uname sysname and machine to @almadar/orb-darwin-arm64, -darwin-x64, -linux-x64, -linux-arm64 or -windows-x64), resolved like a baseline package in the registry knob but on its own compatibility rule: an orb platform package has no language range, so its newest stable, non-deprecated version is taken whose package.json declares orbReads, a range of core languages the target core language satisfies (no orbReads: skipped ORB_PACKAGE_NO_LANGUAGE; its orb and orbProgram blocks are not read); a package declaring orbReads is listed with kind `orb`; a host with no matching entry or whose os/uname fails gets one ORB_PACKAGE_PLATFORM line on stderr and no orb package is considered (the Windows host does not implement os/uname today). A package whose package.json declares orbProgram also installs each of its optionalDependencies at its exact version whose registry manifest os and cpu include this host's (the os and cpu of the orbPlatforms entry os/uname matched, the npm platform rule; every add and update asks os/uname); a host os/uname cannot place installs none of them. Every file the package.json bin map names is written executable. update --urgent (update only; any other command is refused with the usage line): every version may carry a top-level orbRelease { severity security|critical|normal, advisory (one line), fixes (a semver range of earlier versions it fixes) } in its registry manifest (none, or an unknown severity word, is normal); a package is urgent when a stable, non-deprecated version newer than the installed one is security or critical, declares fixes, the installed version satisfies fixes (std-semver) and the version passes the language check above; only urgent packages are updated, to the newest such version, through the same integrity check, staging swap and lockfile write; a baseline package that is not installed is never urgent; stdout is only the applied `<severity> update:` lines; an urgent version that fails the language check (ORB_PACKAGE_INCOMPATIBLE or ORB_PACKAGE_NO_LANGUAGE), whose fixes range std-semver refuses (ORB_PACKAGE_RELEASE), or whose download, integrity or install fails is not applied: the installed version stays, the call answers 500 and stderr names each refusal and each confirmed-urgent advisory, the vulnerable version is never replaced by a half-written one. remove: a workspace-linked package is refused ORB_PACKAGE_LINKED and its link is never deleted; a behavior package whose prefix a .lolo or .orb file still imports (skipping node_modules, .git, dist, target) is refused `refusing to remove '<name>': N file(s) still import '<prefix>/':` plus the files, one per line; otherwise prints `removed <name>` per name. list: one row per installed orb package, sorted by name, columns package (34), version (12), kinds joined by `, ` (26), then `ok` or the problem, ` (linked)` for a workspace link, and ` [<prefix>/, N behaviors]` for a behavior package; --json prints the rows { package, kinds, version, path, link, prefix?, behaviors?, problem } as pretty JSON; with no rows the table is empty and stderr says `orb: nothing is installed in <dir> (no @almadar/core or @almadar/std); run `orb update --global` to set the language up`. Without --global the project directory is used, falling back to the user store when there is no project. Engines: `engines add|update` install the pinned runtime-verify/compiled engine packages at the exact pinned version (`installed <package>@<version> (entry <bin> → <path>)`; a wrong version fails `<package>: expected version <v>, got <w>`, a missing bin entry `<package>: installed package has no `<bin>` bin entry`, a package not found after install `<package>: install reported success but the package was not found`), update prints `updated <package>: <old> → <new>` or `<package>@<old> already up to date` or `installed <package>@<version>`, remove prints `removed <package>`, list prints rows engine (16), package (32), version (12), link (6), path, or `not installed — <hint>`, --json the rows { engine, package, version, entry, path, installed, link }."
 ]
 
 type PackageKind = "language" | "behaviors" | "language pack" | "shell" | "desktop" | "orb"