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

package/src/FileSystemBatch.ts

@@ -0,0 +1,90 @@
+/**
+ * Optional, bounded read batches on the existing filesystem host slot.
+ *
+ * @since 1.0.0
+ */
+
+import type { Effect, FileSystem, PlatformError, Result } from "effect"
+
+/** Maximum operations admitted by one batch.
+ * @since 1.0.0
+ * @category constants
+ */
+export const maxBatchSize = 128
+
+/** Bounded concurrency for hosts without batching.
+ * @since 1.0.0
+ * @category constants
+ */
+export const fallbackConcurrency = 4
+
+/** Read operations supported by a confined batch.
+ * @since 1.0.0
+ * @category models
+ */
+export type BatchRequest =
+  | { readonly operation: "stat"; readonly path: string }
+  | { readonly operation: "readDirectory"; readonly path: string; readonly options?: { readonly recursive?: boolean } }
+  | { readonly operation: "digest"; readonly path: string; readonly content?: boolean }
+  | {
+    readonly operation: "glob"
+    readonly path: string
+    readonly root: string
+    readonly options?: { readonly exclude?: ReadonlyArray<string> }
+  }
+
+/** A successful per-path observation. SHA-256 hashes raw bytes.
+ * @since 1.0.0
+ * @category models
+ */
+export type BatchValue =
+  | { readonly operation: "stat"; readonly info: FileSystem.File.Info }
+  | { readonly operation: "readDirectory" | "glob"; readonly paths: ReadonlyArray<string> }
+  | {
+    readonly operation: "digest"
+    readonly digest: string
+    readonly sizeBytes: number
+    readonly bytes?: Uint8Array
+  }
+
+/** A result names its original request index, including failures.
+ * @since 1.0.0
+ * @category models
+ */
+export interface BatchEntry {
+  readonly index: number
+  readonly path: string
+  readonly result: Result.Result<BatchValue, PlatformError.PlatformError>
+}
+
+/** Results sorted by path, then request index, bound to one root inode.
+ * @since 1.0.0
+ * @category models
+ */
+export interface BatchResponse {
+  readonly rootIdentity: string
+  readonly entries: ReadonlyArray<BatchEntry>
+}
+
+/** The guarded extension, never a second service tag.
+ * @since 1.0.0
+ * @category models
+ */
+export interface FileSystemBatch {
+  readonly maxSize: number
+  readonly maxResponseBytes: number
+  readonly execute: (requests: ReadonlyArray<BatchRequest>) => Effect.Effect<BatchResponse, PlatformError.PlatformError>
+}
+
+/** Host extension identity on the guarded filesystem.
+ * @since 1.0.0
+ * @category constants
+ */
+export const FileSystemBatchTypeId = Symbol.for("@smthrs/kernel/FileSystemBatch")
+
+/** Discover the guarded batch extension when the host supports it.
+ * @since 1.0.0
+ * @category accessors
+ */
+export const batch = (fs: FileSystem.FileSystem): FileSystemBatch | undefined =>
+  (fs as FileSystem.FileSystem & { readonly [FileSystemBatchTypeId]?: FileSystemBatch })[FileSystemBatchTypeId]

package/src/GrantEvent.ts

@@ -0,0 +1,174 @@
+/**
+ * Durable grant decision events.
+ *
+ * Governing design:
+ * `docs/specs/Concepts/Permission Kernel.md` and
+ * `docs/specs/Concepts/Journal Queue.md`.
+ *
+ * @since 1.0.0-rc.0
+ */
+
+import { Capability, CapabilityPattern } from "@smthrs/capability/Capability"
+import * as Schema from "effect/Schema"
+
+/**
+ * The tier at which a capability decision was made.
+ *
+ * @category schemas
+ * @since 1.0.0-rc.0
+ */
+export const GrantTier = Schema.Literals(["sealed", "compensable", "irreversible"])
+
+/**
+ * The scope selected for a permission grant.
+ *
+ * @category schemas
+ * @since 1.0.0-rc.0
+ */
+export const GrantScope = Schema.Literals(["once", "run", "remembered"])
+
+/**
+ * A one-call grant.
+ *
+ * It is durable audit evidence but is deliberately never replayed as active
+ * authority.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export class OnceGrant extends Schema.TaggedClass<OnceGrant>()("@smthrs/kernel/GrantEvent/OnceGrant", {
+  eventType: Schema.Literal("flows.kernel.grant.once.v1"),
+  requestId: Schema.String,
+  runId: Schema.String,
+  planDigest: Schema.optional(Schema.String),
+  capability: Capability,
+  pattern: CapabilityPattern,
+  scope: Schema.Literal("once"),
+  tier: GrantTier
+}) {}
+
+/**
+ * A grant remembered across runs.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export class RememberedGrant extends Schema.TaggedClass<RememberedGrant>()(
+  "@smthrs/kernel/GrantEvent/RememberedGrant",
+  {
+    eventType: Schema.Literal("flows.kernel.grant.remembered.v1"),
+    requestId: Schema.String,
+    runId: Schema.String,
+    planDigest: Schema.optional(Schema.String),
+    capability: Capability,
+    pattern: CapabilityPattern,
+    scope: Schema.Literal("remembered"),
+    tier: GrantTier
+  }
+) {}
+
+/**
+ * A grant scoped to the current run.
+ *
+ * Version 2 captures the requesting fiber's normalized conjunction of any-of
+ * capability-pattern groups. Replay intersects it with the constructor ceiling.
+ * Version 1 omitted this boundary and cannot safely activate authority.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export class RunGrant extends Schema.TaggedClass<RunGrant>()("@smthrs/kernel/GrantEvent/RunGrant", {
+  eventType: Schema.Literal("flows.kernel.grant.run.v2"),
+  requestId: Schema.String,
+  runId: Schema.String,
+  planDigest: Schema.String,
+  capability: Capability,
+  pattern: CapabilityPattern,
+  ceiling: Schema.Array(Schema.Array(CapabilityPattern)),
+  scope: Schema.Literal("run"),
+  tier: GrantTier
+}) {}
+
+/**
+ * A denied permission request.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export class DeniedGrant extends Schema.TaggedClass<DeniedGrant>()("@smthrs/kernel/GrantEvent/DeniedGrant", {
+  eventType: Schema.Literal("flows.kernel.grant.denied.v1"),
+  requestId: Schema.String,
+  runId: Schema.String,
+  planDigest: Schema.optional(Schema.String),
+  capability: Capability,
+  pattern: CapabilityPattern,
+  scope: Schema.Literal("once"),
+  tier: GrantTier
+}) {}
+
+/**
+ * A capability envelope grant.
+ *
+ * Envelope grants are not attached to an individual request. `planDigest`
+ * binds the decision to exactly the plan shown to the approver. A `run`
+ * envelope is replayed only for that run and digest; a `remembered` envelope
+ * becomes remembered predicate grants for future plans while retaining its
+ * origin digest as audit evidence.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export class EnvelopeGrant extends Schema.TaggedClass<EnvelopeGrant>()(
+  "@smthrs/kernel/GrantEvent/EnvelopeGrant",
+  {
+    eventType: Schema.Literal("flows.kernel.grant.envelope.v1"),
+    runId: Schema.String,
+    planDigest: Schema.String,
+    patterns: Schema.Array(CapabilityPattern),
+    scope: Schema.Literals(["run", "remembered"])
+  }
+) {}
+
+/**
+ * All durable grant events understood by the kernel.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export const GrantEventSchema = Schema.Union([
+  OnceGrant,
+  RememberedGrant,
+  DeniedGrant,
+  EnvelopeGrant,
+  RunGrant
+])
+
+/**
+ * All durable grant events understood by the kernel.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export type GrantEvent = typeof GrantEventSchema.Type
+
+/**
+ * Decodes one JSON-compatible journal payload into a grant event.
+ *
+ * Excess payload keys are rejected rather than stripped. Grant payloads are
+ * replayed as active permission authority, so a payload that mixes fields
+ * from two grant variants — for example an envelope carrying request-only
+ * fields — is treated as corrupt instead of silently narrowed to whichever
+ * variant its declared keys happen to satisfy.
+ *
+ * @category decoding
+ * @since 1.0.0-rc.0
+ */
+export const decode = Schema.decodeUnknownResult(GrantEventSchema, { onExcessProperty: "error" })
+
+/**
+ * Encodes a grant event into its JSON-compatible journal payload.
+ *
+ * @category encoding
+ * @since 1.0.0-rc.0
+ */
+export const encode = Schema.encodeUnknownResult(GrantEventSchema)