@smthrs/kernel 0.0.0-stage → 1.0.0-rc.4

package/package.json

@@ -1,6 +1,347 @@
 {
   "name": "@smthrs/kernel",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "type": "module",
+  "version": "1.0.0-rc.4",
+  "license": "MIT",
+  "smthrs": {
+    "group": "engine"
+  },
+  "description": "Capability kernel: effect tiers, monotone capability sets, grant store, and permission-decorating layers over the Host services",
+  "homepage": "https://github.com/smithersai/smithers",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/smithersai/smithers.git",
+    "directory": "packages/smithers/flows/kernel"
+  },
+  "bugs": {
+    "url": "https://github.com/smithersai/smithers/issues"
+  },
+  "tags": [
+    "typescript",
+    "effect",
+    "flow",
+    "capabilities"
+  ],
+  "keywords": [
+    "typescript",
+    "effect",
+    "flow",
+    "capabilities"
+  ],
+  "engines": {
+    "node": ">=26.4.0"
+  },
+  "sideEffects": [],
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    },
+    "./test/contract": {
+      "import": {
+        "types": "./dist/esm/test/HostContract.d.ts",
+        "default": "./dist/esm/test/HostContract.js"
+      },
+      "require": {
+        "types": "./dist/cjs/test/HostContract.d.ts",
+        "default": "./dist/cjs/test/HostContract.js"
+      }
+    },
+    "./internal/*": null,
+    "./*/index": null,
+    "./CapabilitySet": {
+      "import": {
+        "types": "./dist/esm/CapabilitySet.d.ts",
+        "default": "./dist/esm/CapabilitySet.js"
+      },
+      "require": {
+        "types": "./dist/cjs/CapabilitySet.d.ts",
+        "default": "./dist/cjs/CapabilitySet.js"
+      }
+    },
+    "./ChildProcessSpawner": {
+      "import": {
+        "types": "./dist/esm/ChildProcessSpawner.d.ts",
+        "default": "./dist/esm/ChildProcessSpawner.js"
+      },
+      "require": {
+        "types": "./dist/cjs/ChildProcessSpawner.d.ts",
+        "default": "./dist/cjs/ChildProcessSpawner.js"
+      }
+    },
+    "./CommandLine": {
+      "import": {
+        "types": "./dist/esm/CommandLine.d.ts",
+        "default": "./dist/esm/CommandLine.js"
+      },
+      "require": {
+        "types": "./dist/cjs/CommandLine.d.ts",
+        "default": "./dist/cjs/CommandLine.js"
+      }
+    },
+    "./ContainedSpawner": {
+      "import": {
+        "types": "./dist/esm/ContainedSpawner.d.ts",
+        "default": "./dist/esm/ContainedSpawner.js"
+      },
+      "require": {
+        "types": "./dist/cjs/ContainedSpawner.d.ts",
+        "default": "./dist/cjs/ContainedSpawner.js"
+      }
+    },
+    "./FileSystem": {
+      "import": {
+        "types": "./dist/esm/FileSystem.d.ts",
+        "default": "./dist/esm/FileSystem.js"
+      },
+      "require": {
+        "types": "./dist/cjs/FileSystem.d.ts",
+        "default": "./dist/cjs/FileSystem.js"
+      }
+    },
+    "./GrantEvent": {
+      "import": {
+        "types": "./dist/esm/GrantEvent.d.ts",
+        "default": "./dist/esm/GrantEvent.js"
+      },
+      "require": {
+        "types": "./dist/cjs/GrantEvent.d.ts",
+        "default": "./dist/cjs/GrantEvent.js"
+      }
+    },
+    "./GrantStore": {
+      "import": {
+        "types": "./dist/esm/GrantStore.d.ts",
+        "default": "./dist/esm/GrantStore.js"
+      },
+      "require": {
+        "types": "./dist/cjs/GrantStore.d.ts",
+        "default": "./dist/cjs/GrantStore.js"
+      }
+    },
+    "./HostError": {
+      "import": {
+        "types": "./dist/esm/HostError.d.ts",
+        "default": "./dist/esm/HostError.js"
+      },
+      "require": {
+        "types": "./dist/cjs/HostError.d.ts",
+        "default": "./dist/cjs/HostError.js"
+      }
+    },
+    "./HostServices": {
+      "import": {
+        "types": "./dist/esm/HostServices.d.ts",
+        "default": "./dist/esm/HostServices.js"
+      },
+      "require": {
+        "types": "./dist/cjs/HostServices.d.ts",
+        "default": "./dist/cjs/HostServices.js"
+      }
+    },
+    "./HttpClient": {
+      "import": {
+        "types": "./dist/esm/HttpClient.d.ts",
+        "default": "./dist/esm/HttpClient.js"
+      },
+      "require": {
+        "types": "./dist/cjs/HttpClient.d.ts",
+        "default": "./dist/cjs/HttpClient.js"
+      }
+    },
+    "./Jj": {
+      "import": {
+        "types": "./dist/esm/Jj.d.ts",
+        "default": "./dist/esm/Jj.js"
+      },
+      "require": {
+        "types": "./dist/cjs/Jj.d.ts",
+        "default": "./dist/cjs/Jj.js"
+      }
+    },
+    "./JournalGrantStore": {
+      "import": {
+        "types": "./dist/esm/JournalGrantStore.d.ts",
+        "default": "./dist/esm/JournalGrantStore.js"
+      },
+      "require": {
+        "types": "./dist/cjs/JournalGrantStore.d.ts",
+        "default": "./dist/cjs/JournalGrantStore.js"
+      }
+    },
+    "./Path": {
+      "import": {
+        "types": "./dist/esm/Path.d.ts",
+        "default": "./dist/esm/Path.js"
+      },
+      "require": {
+        "types": "./dist/cjs/Path.d.ts",
+        "default": "./dist/cjs/Path.js"
+      }
+    },
+    "./ProcessLedger": {
+      "import": {
+        "types": "./dist/esm/ProcessLedger.d.ts",
+        "default": "./dist/esm/ProcessLedger.js"
+      },
+      "require": {
+        "types": "./dist/cjs/ProcessLedger.d.ts",
+        "default": "./dist/cjs/ProcessLedger.js"
+      }
+    },
+    "./Rooted": {
+      "import": {
+        "types": "./dist/esm/Rooted.d.ts",
+        "default": "./dist/esm/Rooted.js"
+      },
+      "require": {
+        "types": "./dist/cjs/Rooted.d.ts",
+        "default": "./dist/cjs/Rooted.js"
+      }
+    },
+    "./Workspace": {
+      "import": {
+        "types": "./dist/esm/Workspace.d.ts",
+        "default": "./dist/esm/Workspace.js"
+      },
+      "require": {
+        "types": "./dist/cjs/Workspace.d.ts",
+        "default": "./dist/cjs/Workspace.js"
+      }
+    },
+    "./index": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    },
+    "./test/HostContract": {
+      "import": {
+        "types": "./dist/esm/test/HostContract.d.ts",
+        "default": "./dist/esm/test/HostContract.js"
+      },
+      "require": {
+        "types": "./dist/cjs/test/HostContract.d.ts",
+        "default": "./dist/cjs/test/HostContract.js"
+      }
+    },
+    "./test/TestGrantStore": {
+      "import": {
+        "types": "./dist/esm/test/TestGrantStore.d.ts",
+        "default": "./dist/esm/test/TestGrantStore.js"
+      },
+      "require": {
+        "types": "./dist/cjs/test/TestGrantStore.d.ts",
+        "default": "./dist/cjs/test/TestGrantStore.js"
+      }
+    },
+    "./ChildProcessEnvironment": {
+      "import": {
+        "types": "./dist/esm/ChildProcessEnvironment.d.ts",
+        "default": "./dist/esm/ChildProcessEnvironment.js"
+      },
+      "require": {
+        "types": "./dist/cjs/ChildProcessEnvironment.d.ts",
+        "default": "./dist/cjs/ChildProcessEnvironment.js"
+      }
+    },
+    "./ProcessConfinement": {
+      "import": {
+        "types": "./dist/esm/ProcessConfinement.d.ts",
+        "default": "./dist/esm/ProcessConfinement.js"
+      },
+      "require": {
+        "types": "./dist/cjs/ProcessConfinement.d.ts",
+        "default": "./dist/cjs/ProcessConfinement.js"
+      }
+    },
+    "./Unreachable": {
+      "import": {
+        "types": "./dist/esm/Unreachable.d.ts",
+        "default": "./dist/esm/Unreachable.js"
+      },
+      "require": {
+        "types": "./dist/cjs/Unreachable.d.ts",
+        "default": "./dist/cjs/Unreachable.js"
+      }
+    }
+  },
+  "files": [
+    "src/**/*.ts",
+    "dist/**/*.js",
+    "dist/**/*.js.map",
+    "dist/**/*.d.ts",
+    "dist/**/*.d.ts.map",
+    "dist/**/package.json",
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md",
+    "docs/"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true,
+    "tag": "next"
+  },
+  "dependencies": {
+    "@smthrs/capability": "1.0.0-rc.4",
+    "@smthrs/crypto": "1.0.0-rc.4",
+    "@smthrs/jj": "1.0.0-rc.4",
+    "@smthrs/journal": "1.0.0-rc.4"
+  },
+  "peerDependencies": {
+    "@effect/vitest": "4.0.0-rc.115",
+    "effect": "4.0.0-rc.115",
+    "vitest": "5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@effect/vitest": {
+      "optional": true
+    },
+    "vitest": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@effect/language-service": "0.87.2",
+    "@effect/platform-node": "4.0.0-rc.115",
+    "@effect/vitest": "4.0.0-rc.115",
+    "@eslint/js": "9.39.5",
+    "@smthrs/database": "1.0.0-rc.4",
+    "@types/node": "26.4.1",
+    "@vitest/coverage-v8": "5.0.0",
+    "dprint": "0.57.1",
+    "effect": "4.0.0-rc.115",
+    "esbuild": "0.28.2",
+    "eslint": "9.39.5",
+    "eslint-import-resolver-typescript": "4.4.5",
+    "eslint-plugin-import": "2.32.0",
+    "eslint-plugin-jsdoc": "64.3.4",
+    "eslint-plugin-unicorn": "65.0.0",
+    "madge": "8.0.0",
+    "typescript": "5.9.3",
+    "typescript-eslint": "8.69.0",
+    "vitest": "5.0.0",
+    "fast-check": "4.9.0"
+  },
+  "scripts": {
+    "lint": "eslint src --max-warnings=0 && dprint check",
+    "format": "dprint fmt",
+    "build": "node scripts/build.mjs",
+    "check": "tsc -b tsconfig.json && tsc -p tsconfig.test.json --noEmit",
+    "circular": "node scripts/circular.mjs",
+    "test": "vitest",
+    "coverage": "vitest --coverage"
+  }
 }

package/src/CapabilitySet.ts

@@ -0,0 +1,6 @@
+/**
+ * The shared monotone authority implementation used by declarations and guards.
+ * @since 1.0.0
+ */
+
+export * from "@smthrs/capability/CapabilitySet"

package/src/ChildProcessEnvironment.ts

@@ -0,0 +1,98 @@
+/**
+ * Least-authority environment construction for child processes.
+ *
+ * @since 1.0.0-rc.0
+ */
+
+/**
+ * Credential-bearing field names shared with the model request boundary.
+ *
+ * `token`, `key` (optionally followed by a separated `id`), and `pat` are
+ * anchored to complete or separator-delimited suffixes so names such as
+ * `TOKEN_COUNT` and `KEYBOARD` remain ordinary diagnostics. Keeping this rule
+ * below the model and process layers gives request validation and child
+ * spawning one definition of a sensitive name.
+ *
+ * @category constants
+ * @since 1.0.0-rc.0
+ */
+export const credentialNamePattern =
+  /authorization|api[-_]?key|access[-_]?token|refresh[-_]?token|id[-_]?token|auth[-_]?token|api[-_]?token|session[-_]?token|bearer|(?:^|[-_])token$|(?:^|[-_])key(?:[-_]id)?$|(?:^|[-_])pat$|secret|credential|password|passphrase|passwd|signature|x-amz-signature|cookie|set[-_]?cookie|chatgpt[-_]?account[-_]?id/i
+
+/**
+ * Reports whether a field name conventionally carries credentials.
+ *
+ * @category predicates
+ * @since 1.0.0-rc.0
+ */
+export const isCredentialName = (name: string): boolean => credentialNamePattern.test(name)
+
+/**
+ * Ambient variables a child may inherit for executable lookup, identity,
+ * locale, terminal behavior, temporary files, and its shell.
+ *
+ * Locale category variables are admitted separately by their `LC_` prefix.
+ *
+ * @category constants
+ * @since 1.0.0-rc.0
+ */
+export const inheritedNames: ReadonlyArray<string> = Object.freeze([
+  "PATH",
+  "HOME",
+  "USER",
+  "LANG",
+  "TERM",
+  "TMPDIR",
+  "SHELL"
+])
+
+const inherited = new Set(inheritedNames)
+
+/**
+ * Reports whether a variable belongs to the bootstrap set {@link make}
+ * inherits: one of {@link inheritedNames} or a locale `LC_` category,
+ * compared case-insensitively.
+ *
+ * @category predicates
+ * @since 1.0.0-rc.1
+ */
+export const isInheritedName = (name: string): boolean => {
+  const canonical = name.toUpperCase()
+  return inherited.has(canonical) || canonical.startsWith("LC_")
+}
+
+const remove = (environment: Record<string, string>, name: string): void => {
+  const canonical = name.toUpperCase()
+  for (const present of Object.keys(environment)) {
+    if (present.toUpperCase() === canonical) delete environment[present]
+  }
+}
+
+/**
+ * Selects the bootstrap allowlist from an ambient environment and overlays
+ * caller-declared names.
+ *
+ * Sensitive-looking ambient names are withheld even if a future bootstrap
+ * list grows to include one. A caller declaration is applied last because it
+ * is the explicit authority for that child; an `undefined` declaration
+ * removes an inherited name. The returned null-prototype record is always
+ * suitable as a replacement environment and never asks the spawner to merge
+ * the rest of the host process environment.
+ *
+ * @category constructors
+ * @since 1.0.0-rc.0
+ */
+export const make = (
+  ambient: Readonly<Record<string, string | undefined>>,
+  declared: Readonly<Record<string, string | undefined>> = {}
+): Record<string, string> => {
+  const environment = Object.create(null) as Record<string, string>
+  for (const [name, value] of Object.entries(ambient)) {
+    if (value !== undefined && isInheritedName(name) && !isCredentialName(name)) environment[name] = value
+  }
+  for (const [name, value] of Object.entries(declared)) {
+    remove(environment, name)
+    if (value !== undefined) environment[name] = value
+  }
+  return environment
+}