@sixb/core 0.1.20 → 0.1.21

package/src/runtime/create.ts

@@ -1,5 +1,6 @@
 import { resolve } from "node:path"
 import type { ActionDefinition } from "../actions"
+import type { ActivityOptions } from "../activity/service"
 import type { AgentToolDefinition } from "../agents"
 import { assertNoAgentDefinitions } from "../agents/retired-config"
 import type { SixbAuthConfig } from "../auth"
@@ -59,6 +60,8 @@ export interface CreateSixbOptions<in out TParams extends ParamsConfig = ParamsC
   logger?: LoggerProvider
   /** Broker capture controls, independent from the output provider. */
   observability?: ObservabilityOptions
+  /** Records visits and page views in the project's app. Off by default. */
+  activity?: ActivityOptions
   /** Observes runtime failures without changing their outcome. */
   onError?: SixbErrorHandler
   /** Recovery and retention settings. The runtime constructor never starts maintenance timers. */
@@ -135,6 +138,7 @@ export async function createSixb<const TParams extends ParamsConfig = ParamsConf
     sandboxes: options.sandboxes,
     logger: options.logger,
     observability: options.observability,
+    activity: options.activity,
     onError: options.onError,
     ontologyMaintenance: options.ontologyMaintenance,
     projectRoot,

package/src/runtime/host.ts

@@ -8,6 +8,7 @@
 import { resolve } from "node:path"
 import { ActionRunExecutor, registerActionRunExecutor } from "../actions/run/executor"
 import type { ActionDefinition } from "../actions/types"
+import { type ActivityOptions, ActivityService } from "../activity/service"
 import type { AgentDefinitionsInput, AgentToolDefinition } from "../agents"
 import {
   AuthRuntime,
@@ -70,7 +71,9 @@ import {
   createSandboxDefinition,
   type InferSandboxParams,
   type SandboxDefinition,
+  sandboxCredentialIssue,
 } from "../sandboxes/configuration"
+import { SandboxError } from "../sandboxes/errors"
 import { type SchedulerController, SchedulerRuntime } from "../scheduler"
 import type { ScheduleDefinition } from "../schedules"
 import type {
@@ -80,6 +83,13 @@ import type {
   RoleDefinition,
   SecurityDefinitionCatalog,
 } from "../security"
+import { type AppliedMarkings, createAppliedMarkings } from "../security/applied-markings"
+import { registerAppliedMarkings } from "../security/applied-markings-host"
+import {
+  createDatasetVersionMarkings,
+  type DatasetVersionMarkings,
+  registerDatasetVersionMarkings,
+} from "../security/dataset-version-markings"
 import type { ParamsConfig } from "../shared/params/types"
 import type { ShareDefinition } from "../shares"
 import type { Storage } from "../storage"
@@ -122,6 +132,8 @@ export interface SixbHostOptions<in out TParams extends ParamsConfig = ParamsCon
   logger?: LoggerProvider
   /** Broker capture controls, independent from the output provider. */
   observability?: ObservabilityOptions
+  /** Records visits and page views in the project's app. Off by default. */
+  activity?: ActivityOptions
   /** Observes runtime failures without changing their outcome. */
   onError?: SixbErrorHandler
   /** Recovery and retention settings. The runtime constructor never starts maintenance timers. */
@@ -170,11 +182,14 @@ export class SixbHost<in out TParams extends ParamsConfig = ParamsConfig> {
   private readonly storageReadiness: StorageReadiness
   private readonly connectorService: ConnectorService
   private readonly materializer: OntologyMaterializerContract
+  private readonly datasetVersionMarkings: DatasetVersionMarkings
+  private readonly appliedMarkings: AppliedMarkings
   readonly sandboxDefinition?: SandboxDefinition
   readonly definitions: SixbDefinitions
   readonly broker: Broker
   readonly events: DomainEventLog
   readonly logging: LoggingService
+  readonly activity: ActivityService
   readonly storage: Storage
   readonly lakeStorage: LakeStorage
   readonly blobStorage: BlobStorage
@@ -203,6 +218,7 @@ export class SixbHost<in out TParams extends ParamsConfig = ParamsConfig> {
       observability: options.observability?.logs,
     })
     this.storage = options.storage
+    this.activity = new ActivityService(this.projectId, this.storage.activity, options.activity)
     this.storageReadiness = new StorageReadiness(this.storage)
     this.lakeStorage = options.lakeStorage
     this.blobStorage = options.blobStorage
@@ -216,8 +232,28 @@ export class SixbHost<in out TParams extends ParamsConfig = ParamsConfig> {
       options.sandboxes?.configuration === undefined
         ? undefined
         : createSandboxDefinition(options.sandboxes.configuration, definitions.ontology)
+    assertSandboxCredentials(options.sandboxes)
     registerProjectionRegistry(this, definitions.projections)
 
+    this.datasetVersionMarkings = createDatasetVersionMarkings({
+      datasets: definitions.datasets,
+      lakeStorage: this.lakeStorage,
+    })
+    registerDatasetVersionMarkings(this, this.datasetVersionMarkings)
+
+    this.appliedMarkings = createAppliedMarkings({
+      projectId: this.projectId,
+      ontology: definitions.ontology,
+      projections: definitions.projections,
+      revisionOf: (projectionId) =>
+        definitions.projections.resolveDispatch(projectionId).projectionRevision,
+      pipelines: definitions.pipelines.list(),
+      versionMarkings: this.datasetVersionMarkings,
+      lakeStorage: this.lakeStorage,
+      sources: this.storage.ontology.sources,
+    })
+    registerAppliedMarkings(this, this.appliedMarkings)
+
     this.auth = new AuthRuntime({
       projectId: this.projectId,
       storage: this.storage,
@@ -330,6 +366,7 @@ export class SixbHost<in out TParams extends ParamsConfig = ParamsConfig> {
       objectStorage: this.storage.objects,
       embeddingModels,
       rerankingModels,
+      appliedMarkings: this.appliedMarkings,
     })
 
     const runtime: SixbRuntimeContext = {
@@ -349,6 +386,8 @@ export class SixbHost<in out TParams extends ParamsConfig = ParamsConfig> {
           this.committedFacts.notify()
           this.vectorIndexing?.notify()
         },
+        // A projection this process applies is visible to its next read.
+        onProjectionApplied: () => this.appliedMarkings.invalidate(),
       })
     )
     return createBoundSixb<InferSandboxParams<TParams>>(
@@ -417,6 +456,7 @@ export class SixbHost<in out TParams extends ParamsConfig = ParamsConfig> {
         supportsPersistence: typeof this.sandboxes?.resume === "function",
       },
       logging: this.logging,
+      activity: this.activity,
       connectorService: this.connectorService,
       ...(this.connectorService.connectionProcess === undefined
         ? {}
@@ -424,6 +464,7 @@ export class SixbHost<in out TParams extends ParamsConfig = ParamsConfig> {
       blobStorage: this.blobStorage,
       apiPublicOrigin: () => getApiPublicOrigin(this),
       lakeStorage: this.lakeStorage,
+      datasetVersionMarkings: this.datasetVersionMarkings,
     }
   }
 }
@@ -494,3 +535,17 @@ function assertWebhookRunStorage(
     }
   }
 }
+
+/** Reject source access the factory cannot provide: a run checks what `resolve` returns. */
+function assertSandboxCredentials<TParams extends ParamsConfig>(
+  sandboxes: SandboxFactory<TParams> | undefined
+): void {
+  if (!sandboxes) return
+
+  const issue = sandboxCredentialIssue({
+    supportsRequestCredentials: sandboxes.supportsRequestCredentials,
+    auth: sandboxes.configuration?.auth,
+    source: sandboxes.configuration?.source,
+  })
+  if (issue) throw new SandboxError(`[Sixb] ${issue}`)
+}

package/src/runtime/internal.ts

@@ -1,3 +1,5 @@
+export type { ActivityCaptureRuntime } from "../activity/execution"
+export { getActivityCaptureRuntime } from "../activity/execution"
 export { getConnectorConnectionsRuntime } from "../connectors/connections/capability"
 export type {
   CompleteConnectorAuthorizationInput,

package/src/runtime/ontology-mutations.ts

@@ -56,17 +56,24 @@ export function shareOntologyMutationRuntime(source: object, target: object): vo
 export function createOntologyMutationRuntime(input: {
   readonly materializer: BoundOntologyMaterializer
   readonly notifyCommittedFacts: () => void
+  /** Called once a projection may have changed the dataset version its source applied. */
+  readonly onProjectionApplied?: () => void
 }): OntologyMutationRuntime {
+  const applied = <TResult>(work: Promise<TResult>): Promise<TResult> =>
+    work.finally(() => notifyWithoutAffecting(input.onProjectionApplied))
+
   const runtime: OntologyMutationRuntime = {
     getProjectionSource: (source) => input.materializer.projections.getActive(source),
     commitEdits: (command) =>
       commitAndNotify(() => input.materializer.edits.commit(command), input.notifyCommittedFacts),
     replaceProjection: (command) =>
-      commitAndNotify(
-        () => input.materializer.projections.replace(command),
-        input.notifyCommittedFacts
+      applied(
+        commitAndNotify(
+          () => input.materializer.projections.replace(command),
+          input.notifyCommittedFacts
+        )
       ),
-    finishProjection: (command) => input.materializer.projections.finishRun(command),
+    finishProjection: (command) => applied(input.materializer.projections.finishRun(command)),
     appendTelemetry: (command) =>
       commitAndNotify(
         () => input.materializer.telemetry.append(command),
@@ -94,3 +101,11 @@ function notifyWithoutAffectingCommit(notify: () => void): void {
     console.error("[Sixb] Failed to wake the ontology outbox dispatcher:", error)
   }
 }
+
+function notifyWithoutAffecting(notify: (() => void) | undefined): void {
+  try {
+    notify?.()
+  } catch (error) {
+    console.error("[Sixb] Failed to report an applied projection:", error)
+  }
+}

package/src/runtime/resolve-definitions.ts

@@ -5,6 +5,8 @@ import { assertNoAgentDefinitions } from "../agents/retired-config"
 import { createAgentSkillCatalog } from "../agents/skills"
 import { createAgentToolCatalog } from "../agents/tool-catalog"
 import type { ConnectorDefinition } from "../connectors"
+import { isDatasetPick } from "../datasets/builders"
+import { columnsByName } from "../datasets/column-index"
 import type { DatasetDefinition } from "../datasets/types"
 import { assertDatasetDefinition } from "../datasets/validation"
 import { createModelCatalog, type ModelCatalogInput } from "../models"
@@ -116,12 +118,15 @@ export function resolveDefinitions(options: DefinitionOptions): ResolvedDefiniti
   for (const sync of options.syncs ?? []) {
     assertUniqueDefinitionId("sync", sync.id, syncsById)
 
-    if (!datasetsById.has(sync.target.dataset.id)) {
+    const target = datasetsById.get(sync.target.dataset.id)
+    if (!target) {
       throw new RuntimeError(
         `Sync '${sync.id}' targets unknown dataset '${sync.target.dataset.id}'. Add it to 'datasets' in createSixb() or export it from 'datasets/'.`
       )
     }
 
+    assertRegisteredColumns(`Sync '${sync.id}' target '${target.id}'`, sync.target.dataset, target)
+
     syncsById.set(sync.id, sync)
   }
 
@@ -265,18 +270,76 @@ function validatePipelineDatasets(
     stepIds.add(step.id)
 
     for (const [inputName, dataset] of Object.entries(step.inputs)) {
-      if (!datasetsById.has(dataset.id)) {
+      const registered = datasetsById.get(dataset.id)
+      if (!registered) {
         throw new RuntimeError(
           `Pipeline '${pipeline.id}' step '${step.id}' input '${inputName}' references unknown dataset '${dataset.id}'. Add it to 'datasets' in createSixb() or export it from 'datasets/'.`
         )
       }
+
+      assertRegisteredColumns(
+        `Pipeline '${pipeline.id}' step '${step.id}' input '${inputName}'`,
+        dataset,
+        registered,
+        { pick: "allowed" }
+      )
     }
 
-    if (!datasetsById.has(step.output.id)) {
+    const output = datasetsById.get(step.output.id)
+    if (!output) {
       throw new RuntimeError(
         `Pipeline '${pipeline.id}' step '${step.id}' outputs unknown dataset '${step.output.id}'. Add it to 'datasets' in createSixb() or export it from 'datasets/'.`
       )
     }
+
+    assertRegisteredColumns(
+      `Pipeline '${pipeline.id}' step '${step.id}' output '${output.id}'`,
+      step.output,
+      output
+    )
+  }
+}
+
+/**
+ * A definition with a registered id stands for the whole dataset unless `pick()` made it, and only
+ * a step input may be a pick. Comparing columns catches a stale copy of a definition, which would
+ * read or write other columns than the registered ones.
+ */
+function assertRegisteredColumns(
+  subject: string,
+  dataset: DatasetDefinition,
+  registered: DatasetDefinition,
+  options: { readonly pick?: "allowed" } = {}
+): void {
+  // The registered definition itself, as almost every step and sync uses.
+  if (dataset === registered) return
+
+  const pick = isDatasetPick(dataset)
+  if (pick && options.pick !== "allowed") {
+    throw new RuntimeError(`${subject} must be the whole dataset, not a pick.`)
+  }
+
+  const registeredColumns = columnsByName(registered)
+  for (const column of dataset.schema.columns) {
+    const declared = registeredColumns.get(column.name)
+    if (!declared) {
+      throw new RuntimeError(
+        `${subject} has column '${column.name}', which dataset '${registered.id}' does not declare. Use the registered definition.`
+      )
+    }
+
+    if (declared.type !== column.type) {
+      throw new RuntimeError(
+        `${subject} has column '${column.name}' as '${column.type}', but dataset '${registered.id}' declares it as '${declared.type}'. Use the registered definition.`
+      )
+    }
+  }
+
+  if (!pick && dataset.schema.columns.length !== registeredColumns.size) {
+    const hint = options.pick === "allowed" ? ", or .pick(...) to read some of its columns" : ""
+    throw new RuntimeError(
+      `${subject} lacks columns of dataset '${registered.id}'. Use the registered definition${hint}.`
+    )
   }
 }
 

package/src/runtime/sixb.ts

@@ -1,6 +1,14 @@
 import { type ActionsRuntime, createActionsRuntime } from "../actions/execution"
+import {
+  type ActivityRuntime,
+  createActivityCaptureRuntime,
+  createActivityRuntime,
+  registerActivityCaptureRuntime,
+} from "../activity/execution"
+import type { ActivityService } from "../activity/service"
 import { type AgentRuntime, createAgentRuntime } from "../agents/execution"
 import { type AiUsageRuntime, createAiUsageRuntime } from "../ai-usage"
+import { type ArtifactsRuntime, createArtifactsRuntime } from "../artifacts/execution"
 import { type BlobsRuntime, createBlobsRuntime } from "../blob-storage/execution"
 import type { BlobStorage } from "../blob-storage/types"
 import { registerConnectorConnectionsRuntime } from "../connectors/connections/capability"
@@ -24,6 +32,7 @@ import { createProjectionsRuntime, type ProjectionsRuntime } from "../projection
 import { createRulesRuntime, type RulesRuntime } from "../rules/execution"
 import type { SandboxDefinition } from "../sandboxes/configuration"
 import { createSchedulesRuntime, type SchedulesRuntime } from "../schedules/execution"
+import type { DatasetVersionMarkings } from "../security/dataset-version-markings"
 import { createSharesRuntime, type SharesRuntime } from "../shares/execution"
 import { createSyncsRuntime, type SyncsRuntime } from "../syncs/execution"
 import { createWorkflowsRuntime, type WorkflowsRuntime } from "../workflows/execution"
@@ -43,10 +52,12 @@ export interface Sixb<TParams extends Record<string, unknown> = Record<string, u
   readonly projections: ProjectionsRuntime
   readonly rules: RulesRuntime
   readonly agent: AgentRuntime<TParams>
+  readonly artifacts: ArtifactsRuntime
   readonly models: ModelsRuntime
   readonly aiUsage: AiUsageRuntime
   readonly events: EventsRuntime
   readonly logs: LogsRuntime
+  readonly activity: ActivityRuntime
   readonly schedules: SchedulesRuntime
   readonly shares: SharesRuntime
   readonly connector: ConnectorRuntime
@@ -62,11 +73,13 @@ export interface SixbDependencies {
   }
   readonly definitions: SixbDefinitions
   readonly logging: LoggingService
+  readonly activity: ActivityService
   readonly connectorService: ConnectorService
   readonly connectorConnections?: ConnectorConnectionProcess
   readonly blobStorage: BlobStorage
   readonly apiPublicOrigin: () => string | undefined
   readonly lakeStorage: LakeStorage
+  readonly datasetVersionMarkings: DatasetVersionMarkings
 }
 
 export function createBoundSixb<TParams extends Record<string, unknown> = Record<string, unknown>>(
@@ -87,6 +100,7 @@ export function createBoundSixb<TParams extends Record<string, unknown> = Record
     ...createExecutionFacades<TParams>(runtime, execution, dependencies),
   }
   shareOntologyMutationRuntime(runtime, sixb)
+  registerActivityCaptureRuntime(sixb, createActivityCaptureRuntime(runtime, dependencies.activity))
   if (dependencies.connectorConnections) {
     registerConnectorConnectionsRuntime(
       sixb,
@@ -117,7 +131,8 @@ function createExecutionFacades<TParams extends Record<string, unknown>>(
       execution,
       dependencies.definitions.datasets,
       dependencies.lakeStorage,
-      dependencies.blobStorage
+      dependencies.blobStorage,
+      dependencies.datasetVersionMarkings
     ),
     workflows: createWorkflowsRuntime(runtime, execution, dependencies.definitions.workflows),
     syncs: createSyncsRuntime(runtime, execution, dependencies.definitions.syncs),
@@ -130,6 +145,7 @@ function createExecutionFacades<TParams extends Record<string, unknown>>(
       dependencies.definitions.models,
       dependencies.sandbox
     ),
+    artifacts: createArtifactsRuntime(runtime, dependencies.blobStorage),
     models: createModelsRuntime(
       runtime,
       execution,
@@ -139,6 +155,7 @@ function createExecutionFacades<TParams extends Record<string, unknown>>(
     aiUsage: createAiUsageRuntime(runtime, dependencies.definitions.security),
     events: createEventsRuntime(runtime),
     logs: createLogsRuntime(runtime, dependencies.logging),
+    activity: createActivityRuntime(runtime, dependencies.activity),
     schedules: createSchedulesRuntime(runtime, dependencies.definitions.schedules),
     shares: createSharesRuntime(runtime, execution, dependencies.definitions.shares),
     connector: createConnectorRuntime(runtime, execution, dependencies.connectorService),

package/src/sandboxes/README.md

@@ -6,8 +6,21 @@ Factories define environments; threads retain immutable parameters; runs provide
   Dynamic recipes require an execution-resolved environment; providers never invoke resolvers.
 - Selection and validation happen before provisioning. Initial source access must be allowed by
   the session network policy. Creation runs setup once; resume never replays it.
+- One rule decides whether source access can work (`sandboxCredentialIssue` in
+  [configuration](./configuration.ts)): write access needs `auth`, and `auth` a provider with
+  `supportsRequestCredentials`, even for a recipe without a source. `SixbHost` applies it to the
+  factory's static recipe at construction. The worker applies it again to each recipe a run
+  resolves: `resolve` results are unknown at startup, and a worker host is structural.
 - Runs without a thread binding explicitly select `{}`; shared env/network defaults remain session
   settings, not an implicit project binding. Unsupported provider capabilities fail explicitly.
+- The exception is a workflow step's own `sandbox`: its factory's static recipe (source, setup,
+  env, network, auth) applies to a fresh ephemeral sandbox per node run. `params`/`resolve`, a
+  `none` network and source access that fails `sandboxCredentialIssue` are rejected when the step
+  is defined and again at startup. Before the node's terminal write, also when provisioning
+  fails, is cancelled or times out, the worker waits for one attempt to remove injection and
+  revoke every grant, and destroys the sandbox only after it. A refused revocation is logged and
+  does not fail the node: that grant stays valid until it expires. A lost execution records
+  nothing, and its failed acquisition or its release still revokes.
 
 - [Configuration](./configuration.ts) validates and snapshots recipes, sharing Action parameter
   schemas. Resolvers receive the execution-scoped SDK. Only parameters are stored in `sandbox_params`.
@@ -24,8 +37,11 @@ Factories define environments; threads retain immutable parameters; runs provide
   This prevents accidental staging, not deliberate publication with `git add -f`.
 - Confirmed missing/expired state allows one replacement attempt under the current execution fence.
   A durable reset timestamp informs subsequent model calls; conversation history is preserved.
-- Omitted network policy permits API/source access. Explicit policies are never widened; incompatible
-  policies fail before provisioning. Guest-readable `env` is not a Git credential channel.
+- Sixb always adds the API, source and auth request origins to a run's network: an omitted policy
+  allows only those, a restricted one lists what the project adds. `none` fails before
+  provisioning. Guest-readable `env` is not a Git credential channel.
+- Request origins are read from the first grant, so renewals must keep to the same origins: a
+  provider rejects a credential for an origin the network does not allow.
 
 ## V1 limits
 
@@ -33,9 +49,15 @@ Vercel requests can outlive their worker: storage fencing cannot cancel provider
 Uncertain sandboxes stay blocked; explicit recreation uses a new name without deleting old state.
 Saved files remain subject to provider retention.
 
-Source `auth` stays host-side. Named providers advertising `supportsRequestCredentials` must apply
+Source `auth` stays host-side. Providers advertising `supportsRequestCredentials` must apply
 execution-prepared credentials; direct create/resume never invoke `auth` implicitly. They apply
-initial credentials before setup and expose session-scoped renewal. Unsupported providers reject
-credentials before provisioning. During initial provisioning/setup, the worker aborts before token
-expiry if no session handle is available yet; renewal begins after acquisition. Normal teardown
-removes injection and revokes grants. A crash cannot guarantee immediate revocation.
+initial credentials before setup and expose session-scoped renewal, for ephemeral and named
+sandboxes alike. Unsupported providers reject credentials before provisioning. During initial
+provisioning/setup, the worker aborts before token expiry if no session handle is available yet;
+renewal begins after acquisition. Normal teardown removes injection and revokes grants. A crash
+cannot guarantee immediate revocation.
+
+A grant may also carry a guest-readable `env` (identities, placeholders), validated like recipe
+`env` before provisioning; an invalid one fails authentication. It applies on creation and resume
+under the recipe's own `env`. Only the first grant of a run is read: the session environment
+cannot change once acquired, so renewals rotate requests and their `env` is ignored.

package/src/sandboxes/auth.ts

@@ -3,13 +3,29 @@ import type { SandboxRequestCredential } from "./sandbox"
 
 /** Per-run source access. Never persist these grants or expose them to the guest. */
 export interface SandboxSourceCredentials {
+  /**
+   * Sixb opens these origins in the run's network, whether the recipe omits `network` or
+   * restricts it, so each must be one exact `https://` origin: a wildcard host is rejected. The
+   * network is set from the first grant of a session: return requests for the same origins on
+   * renewal.
+   */
   readonly requests: readonly SandboxRequestCredential[]
+  /**
+   * Guest-readable variables the integration needs in the sandbox, such as identities or the
+   * placeholder a tool requires before the host replaces its Authorization header. Never a
+   * credential: commands, files and snapshots can read these values.
+   *
+   * Applied from the first grant of a session; the recipe's own `env` wins on collision. Return
+   * the same values on renewal: renewals only rotate `requests`, so later values are ignored.
+   */
+  readonly env?: Readonly<Record<string, string>>
   readonly expiresAt: Date
   revoke(): Promise<void>
 }
 
 /** Integration-owned authentication; grant source.access (read by default), or reject. */
 export interface SandboxSourceAuth {
+  /** A thrown error is reported to onError: it and its causes must never contain a credential. */
   authorize(input: {
     readonly source: SandboxSource
     readonly signal: AbortSignal

package/src/sandboxes/config.ts

@@ -1,5 +1,5 @@
 import type { ParamsConfig } from "../shared/params/types"
-import { captureEnvironment, type SandboxConfig } from "./configuration"
+import { type SandboxConfig, staticSandboxRecipe } from "./configuration"
 import { SandboxError } from "./errors"
 
 /** Extract only the common recipe; provider credentials and infrastructure stay on the factory. */
@@ -22,12 +22,7 @@ export function sandboxConfig<TParams extends ParamsConfig>(
   ) {
     throw new SandboxError("[Sixb] Use either static source/setup or resolve, not both.")
   }
-  const environment = captureEnvironment({
-    ...(options.source === undefined ? {} : { source: options.source }),
-    ...(options.setup === undefined ? {} : { setup: options.setup }),
-    ...(options.env === undefined ? {} : { env: options.env }),
-    ...(options.network === undefined ? {} : { network: options.network }),
-  })
+  const environment = staticSandboxRecipe(options)
   return Object.freeze({
     ...(authorize ? { auth: Object.freeze({ authorize }) } : {}),
     ...environment,

package/src/sandboxes/configuration.ts

@@ -112,12 +112,7 @@ export function createSandboxDefinition<TParams extends ParamsConfig>(
     }
   }
   const params = structuredClone(config.params ?? {}) as ParamsConfig
-  const environment = captureEnvironment({
-    ...(config.source === undefined ? {} : { source: config.source }),
-    ...(config.setup === undefined ? {} : { setup: config.setup }),
-    ...(config.env === undefined ? {} : { env: config.env }),
-    ...(config.network === undefined ? {} : { network: config.network }),
-  })
+  const environment = staticSandboxRecipe(config)
   // Capture the function too: later mutation of application config must not change this host.
   // Erase inference only after capturing its schema; every invocation validates and coerces below.
   const resolve = config.resolve as SandboxConfig["resolve"]
@@ -144,6 +139,51 @@ export function createSandboxDefinition<TParams extends ParamsConfig>(
   })
 }
 
+/** What the source access rule reads: the provider's capability and one recipe's source. */
+interface SandboxCredentialRuleInput {
+  readonly supportsRequestCredentials?: boolean
+  /** The factory's source auth; it applies to every recipe the factory resolves. */
+  readonly auth?: unknown
+  readonly source?: SandboxSource
+}
+
+/**
+ * Why a recipe cannot get the source access it declares, as a whole message, or undefined.
+ *
+ * Write access needs source auth. Source auth needs a provider that injects request credentials
+ * outside the sandbox, even for a recipe without a source: auth is the factory's, so startup and
+ * every run give the same answer. Source auth without a source is otherwise fine; that recipe
+ * does not use it.
+ */
+export function sandboxCredentialIssue(input: SandboxCredentialRuleInput): string | undefined {
+  const { supportsRequestCredentials, auth, source } = input
+
+  if (source?.access === "write" && auth === undefined) {
+    return 'Sandbox write access needs source auth: add auth to the sandbox factory or use access "read".'
+  }
+  if (auth !== undefined && !supportsRequestCredentials) {
+    return "Sandbox source auth needs a provider that injects request credentials outside the sandbox: use @sixb/sandboxes-vercel, or remove auth."
+  }
+
+  return undefined
+}
+
+/** The static part of a recipe, captured: all a run without thread params can apply. */
+export function staticSandboxRecipe(configuration: {
+  readonly source?: unknown
+  readonly setup?: unknown
+  readonly env?: unknown
+  readonly network?: unknown
+}): SandboxEnvironment {
+  const { source, setup, env, network } = configuration
+  return captureEnvironment({
+    ...(source === undefined ? {} : { source }),
+    ...(setup === undefined ? {} : { setup }),
+    ...(env === undefined ? {} : { env }),
+    ...(network === undefined ? {} : { network }),
+  })
+}
+
 /** Capture declarative data only; never retain caller-owned objects or include values in errors. */
 export function captureEnvironment(value: unknown): SandboxEnvironment {
   if (
@@ -177,6 +217,10 @@ function validateSource(source: unknown): void {
   if (url.protocol !== "https:" || url.username || url.password || url.search || url.hash) {
     fail("source URL: expected credential-free HTTPS")
   }
+
+  // The repository host joins the run's network, where "*" would open every matching domain.
+  if (url.hostname.includes("*")) fail("source URL: wildcard hosts are not allowed")
+
   if (
     source.revision !== undefined &&
     (typeof source.revision !== "string" ||
@@ -202,7 +246,13 @@ function validateSetup(setup: unknown): void {
   }
 }
 
-function validateEnv(env: unknown): void {
+/** Snapshot guest-readable variables under the recipe `env` rules; never include values in errors. */
+export function captureSandboxEnv(value: unknown): Readonly<Record<string, string>> {
+  validateEnv(value)
+  return structuredClone(value)
+}
+
+function validateEnv(env: unknown): asserts env is Record<string, string> {
   if (
     !isPlainRecord(env) ||
     Object.entries(env).some(
@@ -248,6 +298,10 @@ function validateNetworkTarget(target: unknown): void {
   if (!["http:", "https:"].includes(url.protocol) || url.origin !== target.origin) {
     fail("network origin")
   }
+
+  // Providers such as Vercel read "*" in a domain as a wildcard: one target would open every
+  // matching domain. List each domain instead.
+  if (url.hostname.includes("*")) fail("network origin: wildcard hosts are not allowed")
 }
 
 function parseUrl(value: string, field: string): URL {

package/src/sandboxes/index.ts

@@ -32,6 +32,7 @@ export type {
   SandboxNetworkPolicy,
   SandboxNetworkTarget,
   SandboxRequestCredential,
+  SandboxRequestMethod,
   SandboxSessionOptions,
   SandboxStatus,
 } from "./sandbox"