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

package/src/Rooted.ts

@@ -0,0 +1,128 @@
+/**
+ * Filesystem, path and process services bound to one root directory.
+ *
+ * Node resolves a relative path against `process.cwd()`. A host serves one
+ * directory whatever the process's own, so here every relative path, and every
+ * command spawned without a `cwd`, resolves against `root`. Absolute paths pass
+ * through unchanged, and so does a symlink's target, which is relative to the
+ * link rather than to any directory.
+ *
+ * @since 1.0.0
+ */
+
+import { Context, Effect, FileSystem, Layer, Path } from "effect"
+import * as ChildProcess from "effect/unstable/process/ChildProcess"
+import * as ChildProcessSpawner from "effect/unstable/process/ChildProcessSpawner"
+import * as Containment from "./internal/Containment.ts"
+
+/**
+ * `base` with every relative path resolved against the absolute `root`.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export const path = (base: Path.Path, root: string): Path.Path => {
+  const resolve = (...segments: ReadonlyArray<string>) => base.resolve(root, ...segments)
+  return {
+    ...base,
+    resolve,
+    relative: (from, to) => base.relative(resolve(from), resolve(to)),
+    toFileUrl: (value) => base.toFileUrl(resolve(value))
+  }
+}
+
+/**
+ * `base` with every relative path resolved by `rooted`, a {@link path}.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export const fileSystem = (base: FileSystem.FileSystem, rooted: Path.Path): FileSystem.FileSystem => {
+  const at = (value: string) => rooted.resolve(value)
+  const temp = <O extends { readonly directory?: string | undefined }>(options: O | undefined) =>
+    options?.directory === undefined ? options : { ...options, directory: at(options.directory) }
+  return {
+    ...base,
+    access: (value, options) => base.access(at(value), options),
+    copy: (from, to, options) => base.copy(at(from), at(to), options),
+    copyFile: (from, to) => base.copyFile(at(from), at(to)),
+    chmod: (value, mode) => base.chmod(at(value), mode),
+    chown: (value, uid, gid) => base.chown(at(value), uid, gid),
+    glob: (pattern, options) => base.glob(pattern, { ...options, root: at(options?.root ?? ".") }),
+    exists: (value) => base.exists(at(value)),
+    link: (from, to) => base.link(at(from), at(to)),
+    makeDirectory: (value, options) => base.makeDirectory(at(value), options),
+    makeTempDirectory: (options) => base.makeTempDirectory(temp(options)),
+    makeTempDirectoryScoped: (options) => base.makeTempDirectoryScoped(temp(options)),
+    makeTempFile: (options) => base.makeTempFile(temp(options)),
+    makeTempFileScoped: (options) => base.makeTempFileScoped(temp(options)),
+    open: (value, options) => base.open(at(value), options),
+    readDirectory: (value, options) => base.readDirectory(at(value), options),
+    readFile: (value) => base.readFile(at(value)),
+    readFileString: (value, encoding) => base.readFileString(at(value), encoding),
+    readLink: (value) => base.readLink(at(value)),
+    realPath: (value) => base.realPath(at(value)),
+    remove: (value, options) => base.remove(at(value), options),
+    rename: (from, to) => base.rename(at(from), at(to)),
+    sink: (value, options) => base.sink(at(value), options),
+    stat: (value) => base.stat(at(value)),
+    stream: (value, options) => base.stream(at(value), options),
+    symlink: (target, value) => base.symlink(target, at(value)),
+    truncate: (value, length) => base.truncate(at(value), length),
+    utimes: (value, atime, mtime) => base.utimes(at(value), atime, mtime),
+    watch: (value, options) => base.watch(at(value), options),
+    writeFile: (value, data, options) => base.writeFile(at(value), data, options),
+    writeFileString: (value, data, options) => base.writeFileString(at(value), data, options)
+  }
+}
+
+/**
+ * `value` with every stage's `cwd` resolved by `rooted`, a {@link path}; its
+ * root for a stage without one.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export const command = (value: ChildProcess.Command, rooted: Path.Path): ChildProcess.Command =>
+  ChildProcess.isStandardCommand(value)
+    ? ChildProcess.setCwd(value, rooted.resolve(value.options.cwd ?? "."))
+    : ChildProcess.pipeTo(command(value.left, rooted), command(value.right, rooted), value.options)
+
+/**
+ * `base` spawning each command as {@link command} roots it. A contained `base`
+ * stays contained.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export const spawner = (
+  base: ChildProcessSpawner.ChildProcessSpawner["Service"],
+  rooted: Path.Path
+): ChildProcessSpawner.ChildProcessSpawner["Service"] =>
+  Containment.inherit(base, ChildProcessSpawner.make((value) => base.spawn(command(value, rooted))))
+
+/**
+ * Decorates the `FileSystem`, `Path` and `ChildProcessSpawner` it is provided
+ * in place, so everything downstream resolves against `root`.
+ *
+ * @category layers
+ * @since 1.0.0
+ */
+export const layer = (
+  root: string
+): Layer.Layer<
+  FileSystem.FileSystem | Path.Path | ChildProcessSpawner.ChildProcessSpawner,
+  never,
+  FileSystem.FileSystem | Path.Path | ChildProcessSpawner.ChildProcessSpawner
+> =>
+  Layer.effectContext(Effect.gen(function*() {
+    const base = yield* Path.Path
+    const rooted = path(base, base.resolve(root))
+    return Context.make(Path.Path, rooted).pipe(
+      Context.add(FileSystem.FileSystem, fileSystem(yield* FileSystem.FileSystem, rooted)),
+      Context.add(
+        ChildProcessSpawner.ChildProcessSpawner,
+        spawner(yield* ChildProcessSpawner.ChildProcessSpawner, rooted)
+      )
+    )
+  }))

package/src/Unreachable.ts

@@ -0,0 +1,30 @@
+/**
+ * Typed host connectivity failures, including failed command diagnostics.
+ *
+ * @since 1.0.0
+ */
+
+import * as Schema from "effect/Schema"
+
+/**
+ * A temporarily unreachable resolver, connection, or HTTP service.
+ *
+ * @category errors
+ * @since 1.0.0
+ */
+export class Unreachable extends Schema.TaggedError<Unreachable>()("@smthrs/kernel/Unreachable", {
+  message: Schema.String,
+  cause: Schema.optional(Schema.Unknown)
+}) {}
+
+const outage =
+  /Could not resolve host|Failed to connect to|Connection timed out|Operation timed out|Connection reset|Recv failure|Network is unreachable|Temporary failure in name resolution|SSL_ERROR_SYSCALL|The remote end hung up unexpectedly|\bEAI_AGAIN\b|\bENOTFOUND\b|\bHTTP(?:\/\d(?:\.\d)?)?\s*(?:(?:error|status|code)\s*[:=]?\s*)?[:=]?\s*(?:429|5\d{2})\b/i
+
+/**
+ * Classifies stderr from a failed host command; other exits keep their domain error.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export const classifyExit = (stderr: string): Unreachable | undefined =>
+  outage.test(stderr) ? new Unreachable({ message: stderr }) : undefined

package/src/Workspace.ts

@@ -0,0 +1,65 @@
+/**
+ * The workspace root used to make filesystem capability resources stable.
+ *
+ * It lives beside the closed host list rather than in a platform package: a
+ * workspace root is a policy decision the kernel needs before it can name a
+ * filesystem capability, not something a platform can answer.
+ *
+ * Governing design:
+ * `docs/specs/Concepts/Effect Taxonomy.md` and
+ * `docs/specs/Concepts/Permission Kernel.md`.
+ *
+ * @since 1.0.0-rc.0
+ */
+
+import { Context, Layer } from "effect"
+
+/**
+ * Workspace-root configuration.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export interface Service {
+  readonly root: string
+}
+
+/**
+ * The workspace-root service tag.
+ *
+ * @category services
+ * @since 1.0.0-rc.0
+ */
+export class Workspace extends Context.Service<Workspace, Service>()("@smthrs/kernel/Workspace") {}
+
+/**
+ * Constructs workspace-root configuration.
+ *
+ * @category constructors
+ * @since 1.0.0-rc.0
+ */
+export const make = (root: string): Service => Workspace.of({ root })
+
+/**
+ * Provides a workspace root.
+ *
+ * @category layers
+ * @since 1.0.0-rc.0
+ */
+export const layer = (root: string): Layer.Layer<Workspace> => Layer.succeed(Workspace, make(root))
+
+/**
+ * Constructs a relative workspace-root stub for tests.
+ *
+ * @category constructors
+ * @since 1.0.0-rc.0
+ */
+export const makeNoop: Service = make(".")
+
+/**
+ * Provides a relative workspace-root stub for tests.
+ *
+ * @category layers
+ * @since 1.0.0-rc.0
+ */
+export const layerNoop: Layer.Layer<Workspace> = Layer.succeed(Workspace, makeNoop)

package/src/index.ts

@@ -0,0 +1,181 @@
+/**
+ * Capability enforcement at the Host boundary.
+ *
+ * Every slot of the closed Host surface is decorated in place: a middleware
+ * `Layer` over the very tag a platform adapter provides, checking a capability
+ * against a `GrantStore` before it delegates. There is no second, protected
+ * tag, so code that never heard of the kernel is guarded the moment the layer
+ * is composed over its host.
+ *
+ * @since 1.0.0-rc.0
+ */
+
+/**
+ * Capability values, patterns, matching, and effect tiers.
+ *
+ * @category namespace exports
+ * @since 1.0.0-rc.0
+ */
+export * as Capability from "@smthrs/capability/Capability"
+
+/**
+ * Monotone ambient authority and intersection.
+ *
+ * @category namespace exports
+ * @since 1.0.0-rc.0
+ */
+export * as CapabilitySet from "./CapabilitySet.ts"
+
+/**
+ * The `proc:spawn` middleware over Effect's own `ChildProcessSpawner` tag.
+ *
+ * @category namespace exports
+ * @since 1.0.0-rc.0
+ */
+export * as ChildProcessSpawner from "./ChildProcessSpawner.ts"
+
+/**
+ * Least-authority child-process environment construction.
+ *
+ * @category namespace exports
+ * @since 1.0.0-rc.0
+ */
+export * as ChildProcessEnvironment from "./ChildProcessEnvironment.ts"
+
+/**
+ * Process containment middleware over Effect's own `ChildProcessSpawner` tag.
+ *
+ * @category namespace exports
+ * @since 1.0.0-rc.0
+ */
+export * as ContainedSpawner from "./ContainedSpawner.ts"
+
+/**
+ * Rendering `ChildProcess` commands back to command lines.
+ *
+ * @category namespace exports
+ * @since 1.0.0-rc.0
+ */
+export * as CommandLine from "./CommandLine.ts"
+
+/**
+ * The `fs:read`/`fs:write` middleware over Effect's own `FileSystem` tag.
+ *
+ * @category namespace exports
+ * @since 1.0.0-rc.0
+ */
+export * as FileSystem from "./FileSystem.ts"
+
+/**
+ * Durable grant decision schemas.
+ *
+ * @category namespace exports
+ * @since 1.0.0-rc.0
+ */
+export * as GrantEvent from "./GrantEvent.ts"
+
+/**
+ * Attended and unattended grant-store services.
+ *
+ * @category namespace exports
+ * @since 1.0.0-rc.0
+ */
+export * as GrantStore from "./GrantStore.ts"
+
+/**
+ * The union of failures the closed Host surface is allowed to produce.
+ *
+ * A type, not a namespace: process execution now fails with Effect's own
+ * `PlatformError`, so nothing is left here to construct.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export type { HostError } from "./HostError.ts"
+
+/**
+ * The closed protected Host service layer.
+ *
+ * @category namespace exports
+ * @since 1.0.0-rc.0
+ */
+export * as HostServices from "./HostServices.ts"
+
+/**
+ * The `net:get`/`net:post`/`model:call` middleware over Effect's own
+ * `HttpClient` tag.
+ *
+ * @category namespace exports
+ * @since 1.0.0-rc.0
+ */
+export * as HttpClient from "./HttpClient.ts"
+
+/**
+ * The jj capability middleware over `@smthrs/jj`'s own `Jj` tag.
+ *
+ * @category namespace exports
+ * @since 1.0.0-rc.0
+ */
+export * as Jj from "./Jj.ts"
+
+/**
+ * Journal-backed grant persistence.
+ *
+ * @category namespace exports
+ * @since 1.0.0-rc.0
+ */
+export * as JournalGrantStore from "./JournalGrantStore.ts"
+
+/**
+ * The explicit pure path-service decision.
+ *
+ * @category namespace exports
+ * @since 1.0.0-rc.0
+ */
+export * as Path from "./Path.ts"
+
+/**
+ * Typed permission errors and policy rules.
+ *
+ * @category namespace exports
+ * @since 1.0.0-rc.0
+ */
+export * as Permission from "@smthrs/capability/Permission"
+
+/**
+ * The host's durable record of the processes it started.
+ *
+ * @category namespace exports
+ * @since 1.0.0-rc.0
+ */
+export * as ProcessLedger from "./ProcessLedger.ts"
+
+/**
+ * Filesystem, path and process services bound to one root directory.
+ *
+ * @category namespace exports
+ * @since 1.0.0
+ */
+export * as Rooted from "./Rooted.ts"
+
+/**
+ * The shared workspace-root service.
+ *
+ * @category namespace exports
+ * @since 1.0.0-rc.0
+ */
+export * as Workspace from "./Workspace.ts"
+
+/** Host process confinement.
+ * @category namespace exports
+ * @since 1.0.0-rc.1
+ */
+export * as ProcessConfinement from "./ProcessConfinement.ts"
+
+/**
+ * Typed connectivity failures and host command exit classification.
+ *
+ * @category namespace exports
+ * @since 1.0.0
+ */
+export * as Unreachable from "./Unreachable.ts"

package/src/internal/Containment.ts

@@ -0,0 +1,37 @@
+/**
+ * Trusted composition metadata shared by contained and permission-aware spawners.
+ * @since 1.0.0
+ */
+
+import type { ChildProcessSpawner } from "effect/unstable/process/ChildProcessSpawner"
+
+// The registry key also works when a service crosses the ESM/CJS projections.
+// This declares a trusted lifecycle contract; it cannot prove a supplied
+// lifecycle is honest or turn process containment into a security sandbox.
+const key = Symbol.for("@smthrs/kernel/ContainedSpawner/Lifecycle/v1")
+
+/**
+ * Reads only an own data property, without invoking an accessor.
+ * @private
+ * @since 1.0.0
+ */
+export const isContained = (spawner: ChildProcessSpawner["Service"]): boolean =>
+  Object.getOwnPropertyDescriptor(spawner, key)?.value === true
+
+/**
+ * Marks a newly constructed service without copying through object spreads.
+ * @private
+ * @since 1.0.0
+ */
+export const mark = (spawner: ChildProcessSpawner["Service"]): ChildProcessSpawner["Service"] =>
+  Object.defineProperty(spawner, key, { value: true, enumerable: false, writable: false, configurable: false })
+
+/**
+ * Preserves the declaration on a wrapper that delegates its process lifetime.
+ * @private
+ * @since 1.0.0
+ */
+export const inherit = (
+  source: ChildProcessSpawner["Service"],
+  wrapper: ChildProcessSpawner["Service"]
+): ChildProcessSpawner["Service"] => isContained(source) ? mark(wrapper) : wrapper

package/src/internal/Pipeline.ts

@@ -0,0 +1,85 @@
+/**
+ * Pipeline wiring around a per-process spawner, so every leg has its own lifecycle.
+ * @since 1.0.0
+ */
+
+import * as Effect from "effect/Effect"
+import * as Exit from "effect/Exit"
+import type * as PlatformError from "effect/PlatformError"
+import type * as Scope from "effect/Scope"
+import * as Stream from "effect/Stream"
+import * as ChildProcess from "effect/unstable/process/ChildProcess"
+import { type ChildProcessHandle, makeHandle } from "effect/unstable/process/ChildProcessSpawner"
+
+type Spawn = (
+  command: ChildProcess.StandardCommand
+) => Effect.Effect<ChildProcessHandle, PlatformError.PlatformError, Scope.Scope>
+
+const source = (handle: ChildProcessHandle, from: ChildProcess.PipeFromOption | undefined) => {
+  if (from === "stderr") return handle.stderr
+  if (from === "all") return handle.all
+  const fd = from === undefined ? undefined : ChildProcess.parseFdName(from)
+  return fd === undefined ? handle.stdout : handle.getOutputFd(fd)
+}
+
+/** An edge feeds the first process of its destination, including a nested pipeline. */
+const withInput = (
+  command: ChildProcess.Command,
+  stream: Stream.Stream<Uint8Array, PlatformError.PlatformError>,
+  to: ChildProcess.PipeToOption | undefined
+): ChildProcess.Command => {
+  if (command._tag === "PipedCommand") {
+    return ChildProcess.pipeTo(withInput(command.left, stream, to), command.right, command.options)
+  }
+  const fd = to === undefined ? undefined : ChildProcess.parseFdName(to)
+  if (fd !== undefined) {
+    return ChildProcess.make(command.command, command.args, {
+      ...command.options,
+      additionalFds: {
+        ...command.options.additionalFds,
+        [ChildProcess.fdName(fd)]: { type: "input", stream }
+      }
+    })
+  }
+  const stdin = command.options.stdin
+  return ChildProcess.make(command.command, command.args, {
+    ...command.options,
+    stdin: {
+      ...(typeof stdin === "object" && !Stream.isStream(stdin) ? stdin : {}),
+      stream
+    }
+  })
+}
+
+/**
+ * Preserve Effect's rightmost output/status and reverse-order kill/reref semantics.
+ * @private
+ * @since 1.0.0
+ */
+export const spawn = (
+  command: ChildProcess.Command,
+  standard: Spawn
+): Effect.Effect<ChildProcessHandle, PlatformError.PlatformError, Scope.Scope> =>
+  Effect.gen(function*() {
+    if (command._tag === "StandardCommand") return yield* standard(command)
+    const left = yield* spawn(command.left, standard)
+    const right = yield* spawn(
+      withInput(command.right, source(left, command.options.from), command.options.to),
+      standard
+    )
+    return makeHandle({
+      ...right,
+      kill: (options) =>
+        Effect.gen(function*() {
+          const rightExit = yield* Effect.exit(right.kill(options))
+          const leftExit = yield* Effect.exit(left.kill(options))
+          if (Exit.isFailure(rightExit)) return yield* Effect.failCause(rightExit.cause)
+          return yield* leftExit
+        }),
+      unref: Effect.gen(function*() {
+        const leftReref = yield* left.unref
+        const rightReref = yield* right.unref
+        return Effect.andThen(rightReref, leftReref)
+      })
+    })
+  })

package/src/internal/makeCapability.ts

@@ -0,0 +1,26 @@
+/**
+ * Typed capability construction for host decorators.
+ *
+ * @since 1.0.0-rc.0
+ */
+
+import * as Capability from "@smthrs/capability/Capability"
+import { GrantStoreError } from "@smthrs/capability/Permission"
+import { Effect } from "effect"
+
+/**
+ * Constructs decorator requests without leaking schema failures as defects.
+ *
+ * @category constructors
+ * @since 1.0.0-rc.0
+ */
+export const makeCapability = (action: Capability.Action, resource: string) =>
+  Effect.try({
+    try: () => Capability.make(action, resource),
+    catch: () =>
+      new GrantStoreError({
+        code: "invalid_resolution",
+        message:
+          `capability requires a valid action and a resource within maximumCapabilityResourceLength (${Capability.maxResourceLength} UTF-16 code units)`
+      })
+  })

package/src/test/FileSystemBatchContract.ts

@@ -0,0 +1,59 @@
+/**
+ * The optional atomic batch portion of the shared host contract.
+ *
+ * @since 1.0.0
+ */
+
+import { expect } from "@effect/vitest"
+import { Effect, type FileSystem, Option, Path, Result } from "effect"
+import * as KernelFileSystem from "../FileSystem.ts"
+
+/**
+ * Exercises every advertised batch implementation over the host contract's
+ * fresh `source.txt` fixture. Isolated volumes may omit this optimization.
+ *
+ * @since 1.0.0
+ * @category testing
+ */
+export const check = (fs: FileSystem.FileSystem, root: string) =>
+  Effect.gen(function*() {
+    const atomic = (fs as Partial<KernelFileSystem.AtomicHostFileSystem>)[KernelFileSystem.AtomicFileSystemTypeId]
+    if (atomic?.batchLimits === undefined) {
+      expect(KernelFileSystem.batch(fs)).toBeUndefined()
+      return
+    }
+    const path = yield* Path.Path
+    const boundaryRoot = yield* fs.realPath(root)
+    const rootIdentity = atomic.identifyRoot === undefined
+      ? yield* Effect.map(fs.stat(root), (info) => `${info.dev}:${Option.getOrThrow(info.ino)}`)
+      : yield* atomic.identifyRoot(boundaryRoot)
+    const response = yield* atomic.execute({
+      operation: "batch",
+      boundaryRoot,
+      logicalRoot: root,
+      rootIdentity,
+      requests: [
+        { operation: "digest", path: path.join(root, "source.txt"), content: true },
+        { operation: "stat", path: path.join(root, "source.txt") },
+        { operation: "readDirectory", path: root },
+        { operation: "glob", path: path.join(root, "*.txt"), root },
+        { operation: "digest", path: path.join(root, "absent") }
+      ]
+    })
+    expect(response.rootIdentity).toBe(rootIdentity)
+    expect(response.entries.map((entry) => entry.index)).toEqual([2, 3, 4, 0, 1])
+    const entries = [...response.entries].sort((a, b) => a.index - b.index)
+    expect(Result.getOrThrow(entries[0]!.result)).toEqual({
+      operation: "digest",
+      digest: "0e1c618211c39c03726d50ee05e7e520ca6d8a2a3619b17983adc574e3ca34bf",
+      sizeBytes: 13,
+      bytes: new TextEncoder().encode("host-contract")
+    })
+    expect(Result.getOrThrow(entries[1]!.result)).toMatchObject({
+      operation: "stat",
+      info: { type: "File", size: 13n }
+    })
+    expect(Result.getOrThrow(entries[2]!.result)).toEqual({ operation: "readDirectory", paths: ["source.txt"] })
+    expect(Result.getOrThrow(entries[3]!.result)).toEqual({ operation: "glob", paths: [path.join(root, "source.txt")] })
+    expect(entries[4]!.result).toMatchObject({ _tag: "Failure", failure: { reason: { _tag: "NotFound" } } })
+  })