@sixb/core 0.1.20 → 0.1.22

package/src/runtime/types.ts

@@ -10,6 +10,7 @@ import type { AuthorizationContext } from "../authorization"
 import type { OpenedFileRef } from "../blob-storage"
 import type { Broker } from "../broker"
 import type { DomainEventLog } from "../events"
+import type { ObjectEventHistory } from "../events/service"
 import type { RuntimeAuthorization } from "../execution"
 import type { AuthorizedObjectReader } from "../execution/authorized-object-reader"
 import type { EmbeddingModelCatalog, RerankingModelCatalog, RerankingModelRef } from "../models"
@@ -43,8 +44,10 @@ import type {
   ObjectTypeWithPropertyTokens,
   PropertyToken,
 } from "../ontology/tokens"
+import type { CurrentUserRef, UserRef } from "../ontology/user-ref"
 import type { Queues } from "../queues"
 import type { ActionRunRecord, ObjectLinkRow, Redactions, Storage } from "../storage"
+import type { UserProfile } from "../users"
 // ── Shared runtime context ──────────────────────────────────
 
 /**
@@ -60,7 +63,7 @@ export interface SixbHostContext {
   readonly broker: Broker
   readonly ontology: OntologyRegistry
   readonly actionRegistry: ActionDefinitionCatalog
-  readonly events: DomainEventLog
+  readonly events: DomainEventLog & ObjectEventHistory
   readonly storage: Storage
   readonly queues: Queues
 }
@@ -168,6 +171,17 @@ type PropertyWhereValue<
   TPropertyId extends TObjectType["properties"][number]["id"],
 > = InferPropertyValue<PropertyById<TObjectType, TPropertyId>>
 
+/** A value a predicate compares with a user reference may be `currentUser()` instead. */
+type WithCurrentUser<TValue> = [Extract<NonNullable<TValue>, UserRef>] extends [never]
+  ? TValue
+  : TValue | CurrentUserRef
+
+/** The value `eq`, `neq` and `in` compare: the property's, or the reading user's. */
+type PropertyWhereEqualityValue<
+  TObjectType extends ObjectTypeWithPropertyTokens,
+  TPropertyId extends TObjectType["properties"][number]["id"],
+> = WithCurrentUser<PropertyWhereValue<TObjectType, TPropertyId>>
+
 type PropertyWhereContainsValue<
   TObjectType extends ObjectTypeWithPropertyTokens,
   TPropertyId extends TObjectType["properties"][number]["id"],
@@ -175,15 +189,25 @@ type PropertyWhereContainsValue<
   NonNullable<PropertyWhereValue<TObjectType, TPropertyId>> extends string
     ? string
     : NonNullable<PropertyWhereValue<TObjectType, TPropertyId>> extends readonly (infer TItem)[]
-      ? TItem
+      ? WithCurrentUser<TItem>
       : NonNullable<PropertyWhereValue<TObjectType, TPropertyId>> extends Record<string, unknown>
         ? string
         : never
 
+type PropertyWhereEqualityClause<
+  TObjectType extends ObjectTypeWithPropertyTokens,
+  TPropertyId extends TObjectType["properties"][number]["id"],
+> = Omit<ObjectQueryPredicateComparison, "op" | "propertyId" | "value"> & {
+  op: "eq" | "neq"
+  propertyId: TPropertyId
+  value: PropertyWhereEqualityValue<TObjectType, TPropertyId>
+}
+
 type PropertyWhereComparisonClause<
   TObjectType extends ObjectTypeWithPropertyTokens,
   TPropertyId extends TObjectType["properties"][number]["id"],
-> = Omit<ObjectQueryPredicateComparison, "propertyId" | "value"> & {
+> = Omit<ObjectQueryPredicateComparison, "op" | "propertyId" | "value"> & {
+  op: "lt" | "lte" | "gt" | "gte"
   propertyId: TPropertyId
   value: PropertyWhereValue<TObjectType, TPropertyId>
 }
@@ -193,7 +217,7 @@ type PropertyWhereInClause<
   TPropertyId extends TObjectType["properties"][number]["id"],
 > = Omit<ObjectQueryPredicateIn, "propertyId" | "values"> & {
   propertyId: TPropertyId
-  values: readonly PropertyWhereValue<TObjectType, TPropertyId>[]
+  values: readonly PropertyWhereEqualityValue<TObjectType, TPropertyId>[]
 }
 
 type PropertyWhereExistsClause<
@@ -217,11 +241,11 @@ type PropertyPredicate<
   TPropertyId extends TObjectType["properties"][number]["id"],
 > = {
   eq(
-    value: PropertyWhereValue<TObjectType, TPropertyId>
-  ): PropertyWhereComparisonClause<TObjectType, TPropertyId> & { op: "eq" }
+    value: PropertyWhereEqualityValue<TObjectType, TPropertyId>
+  ): PropertyWhereEqualityClause<TObjectType, TPropertyId> & { op: "eq" }
   neq(
-    value: PropertyWhereValue<TObjectType, TPropertyId>
-  ): PropertyWhereComparisonClause<TObjectType, TPropertyId> & { op: "neq" }
+    value: PropertyWhereEqualityValue<TObjectType, TPropertyId>
+  ): PropertyWhereEqualityClause<TObjectType, TPropertyId> & { op: "neq" }
   lt(
     value: PropertyWhereValue<TObjectType, TPropertyId>
   ): PropertyWhereComparisonClause<TObjectType, TPropertyId> & { op: "lt" }
@@ -235,7 +259,7 @@ type PropertyPredicate<
     value: PropertyWhereValue<TObjectType, TPropertyId>
   ): PropertyWhereComparisonClause<TObjectType, TPropertyId> & { op: "gte" }
   in(
-    values: readonly PropertyWhereValue<TObjectType, TPropertyId>[]
+    values: readonly PropertyWhereEqualityValue<TObjectType, TPropertyId>[]
   ): PropertyWhereInClause<TObjectType, TPropertyId>
   exists(value?: boolean): PropertyWhereExistsClause<TObjectType, TPropertyId>
   contains(
@@ -252,6 +276,7 @@ type PropertyWhereClause<TObjectType extends ObjectTypeWithPropertyTokens> =
         | ObjectQueryPredicateContains
     : {
         [TPropertyId in TObjectType["properties"][number]["id"]]:
+          | PropertyWhereEqualityClause<TObjectType, TPropertyId>
           | PropertyWhereComparisonClause<TObjectType, TPropertyId>
           | PropertyWhereInClause<TObjectType, TPropertyId>
           | PropertyWhereExistsClause<TObjectType, TPropertyId>
@@ -628,6 +653,32 @@ type WithExpansion<
     : TRow
   : TRow
 
+/** A `ref.user()` property, or an array of them: the properties `.expand()` resolves to profiles. */
+type UserPropertyToken<TObjectTypeId extends string> = PropertyToken<
+  TObjectTypeId,
+  string,
+  Property & {
+    readonly schema: "userRef" | { readonly type: "array"; readonly items: "userRef" }
+  }
+>
+
+/** One profile, or `null` when empty or no member has the id; the members found for an array. */
+type UserExpansionValue<TToken extends UserPropertyToken<string>> =
+  TToken["property"]["schema"] extends "userRef" ? UserProfile | null : UserProfile[]
+
+/**
+ * Add the `users` entry of one expanded user property to `TRow`, distributing over a polymorphic
+ * row like {@link WithExpansion}. The entry is optional: it is absent when the reader may not view
+ * the member directory or cannot read the property.
+ */
+type WithUserExpansion<TRow, TToken extends UserPropertyToken<string>> = TRow extends {
+  objectTypeId: infer TObjectTypeId
+}
+  ? TToken["objectTypeId"] extends TObjectTypeId
+    ? TRow & { users: { [K in TToken["id"]]?: UserExpansionValue<TToken> } }
+    : TRow
+  : TRow
+
 /**
  * The nested-expansion callback for a link token's resolved target type. `TChildRow`
  * is inferred from the returned builder, recovering the nested `.links` shape.
@@ -652,6 +703,10 @@ export interface ObjectExpandBuilder<
   in out TObjectType extends ObjectTypeWithPropertyTokens,
   out TRow = ExpandedTargetRow<TObjectType>,
 > {
+  /** Attach the profiles of the members a `ref.user()` property names, under `users`. */
+  expand<TToken extends UserPropertyToken<TObjectType["id"]>>(
+    property: TToken
+  ): ObjectExpandBuilder<TObjectType, WithUserExpansion<TRow, TToken>>
   expand<
     TLinkToken extends LinkToken<TObjectType["id"], string, LinkTargetObjectTypeIdValue>,
     TChildRow = ExpandedTargetRow<ObjectTypeForLinkTarget<TObjectType, TLinkToken>>,
@@ -727,7 +782,15 @@ export interface ObjectQueryBuilder<
    * optional `linkProperties` and its own nested `.links`). Targets are precise
    * when they are registered or linked directly, and otherwise degrade to the
    * loose base.
+   *
+   * Given a `ref.user()` property, or an array of them, it attaches the members' profiles
+   * under `users` instead (`row.users.assignee`): a profile or `null` for one reference, the
+   * members found for an array. The entry is absent unless the reader has
+   * `can.view(project.users)`, and for a value the reader cannot read.
    */
+  expand<TToken extends UserPropertyToken<TObjectType["id"]>>(
+    property: TToken
+  ): ObjectQueryBuilder<TObjectType, WithUserExpansion<TRow, TToken>>
   expand<
     TLinkToken extends LinkToken<TObjectType["id"], string, LinkTargetObjectTypeIdValue>,
     TChildRow = ExpandedTargetRow<ObjectTypeForLinkTarget<TObjectType, TLinkToken>>,
@@ -806,6 +869,24 @@ export interface ObjectReadByIdHandle<out TObjectType extends ObjectTypeWithProp
   file(property: FileListPropertyToken<TObjectType>, index: number): ObjectFileHandle
 }
 
+/**
+ * The token of a property declared `unique: true`. A type whose id is only `string` accepts any of
+ * its tokens: the property is then checked when the lookup runs.
+ */
+export type UniquePropertyToken<TObjectType extends ObjectTypeWithPropertyTokens> =
+  string extends TObjectType["id"]
+    ? TObjectType["p"][keyof TObjectType["p"]]
+    : Extract<
+        TObjectType["p"][keyof TObjectType["p"]],
+        { readonly property: { readonly unique: true } }
+      >
+
+/** The value `getBy` takes for a unique property: the value a write gives it, never `null`. */
+export type UniquePropertyValue<
+  TObjectType extends ObjectTypeWithPropertyTokens,
+  TToken extends UniquePropertyToken<TObjectType>,
+> = NonNullable<ObjectTypeProperties<TObjectType>[TToken["id"]]>
+
 /**
  * The reads of an object set, declared once: `sixb.objects(Type)`, a Workflow step's
  * `sixb.objects(Type)` and an Action's `read.objects(Type)` add only their own writes on top.
@@ -814,6 +895,15 @@ export interface ObjectReadSet<in out TObjectType extends ObjectTypeWithProperty
   /** Get an object by id, or null if it doesn't exist. */
   get(id: string): Promise<TwinObject<TObjectType> | null>
 
+  /**
+   * Get the object of exactly this type holding a value of a unique property, or null. Values
+   * compare as writes store them, exactly; `null` belongs to no object.
+   */
+  getBy<TToken extends UniquePropertyToken<TObjectType>>(
+    property: TToken,
+    value: UniquePropertyValue<TObjectType, TToken>
+  ): Promise<TwinObject<TObjectType> | null>
+
   /** Build an executable provider-neutral object query rooted at this object type. */
   query(): ObjectQueryBuilder<TObjectType>
 

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"

package/src/sandboxes/sandbox.ts

@@ -78,13 +78,33 @@ export interface SandboxNetworkTarget {
   readonly origin: string
 }
 
-/** Host-only credentials injected outside the guest into one exact HTTPS request target.
- * This selects authenticated requests, not the sandbox's general egress allowlist.
+/** HTTP methods a request credential can be injected into. HEAD and OPTIONS never are. */
+export type SandboxRequestMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE"
+
+/**
+ * Host-only credentials injected outside the guest into matching HTTPS requests.
+ *
+ * A credential selects which requests receive its Authorization header. It does not decide what
+ * the guest can reach, which is the network policy, nor which resources the token can act on:
+ * the token's own permissions are the boundary, so issue it with the narrowest scope that works.
+ *
+ * Providers apply the same rules so that a credential means the same thing everywhere:
+ * - `origin` is one `https://` domain: no port, path, user info, IP address, loopback host or
+ *   `*` wildcard.
+ * - A path is matched case-sensitively against the raw request path. It starts with a single
+ *   "/" and is printable ASCII without spaces, control characters, "?", "#", "%", "\\", or "."
+ *   and ".." segments. A prefix also ends with "/", so it stops at a segment boundary.
+ * - Two credentials must not match the same request: one credential per request, so providers
+ *   reject the overlap instead of picking one.
+ * - Only Authorization can be set, and the provider forces the request's Host header to
+ *   `origin`'s domain.
  */
 export interface SandboxRequestCredential {
   readonly origin: string
-  readonly path: string
-  readonly method: "GET" | "POST"
+  /** One exact path, or every path under `prefix`. */
+  readonly path: string | { readonly prefix: string }
+  /** One method, or a non-empty list of distinct methods. */
+  readonly method: SandboxRequestMethod | readonly SandboxRequestMethod[]
   readonly headers: { readonly Authorization: string }
 }
 
@@ -123,6 +143,8 @@ export interface Sandbox {
   /** Optional secure injection capability. Replaces all credentials on this session only.
    * An empty list removes injection. Secrets must never enter guest files, env or snapshots.
    * Must not resume a stopped session or change defaults inherited by future sessions.
+   * Renewal, ephemeral or persistent, targets the handle's session; after stop() it rejects.
+   * A thrown error is reported to onError: it and its causes must never contain a credential.
    */
   readonly setRequestCredentials?: (
     credentials: readonly SandboxRequestCredential[]
@@ -166,7 +188,7 @@ export interface Sandbox {
  * Credentials and current authority must be supplied again, never inferred from saved files.
  */
 export interface SandboxFactory<in out TParams extends ParamsConfig = ParamsConfig> {
-  /** Supports initial and renewable host-only credentials on named persistent sessions. */
+  /** Supports initial and renewable host-only credentials on ephemeral and named sessions. */
   readonly supportsRequestCredentials?: boolean
   /** Common host-side environment recipe. Never a discovered Agent definition. */
   readonly configuration?: SandboxConfig<TParams>

package/src/schedules/builders.ts

@@ -178,9 +178,11 @@ function assertEventSource(source: EventSelectorSpec): void {
     case "pipelines":
       assertNonEmpty(source.pipelineId ?? "", "event source pipelineId")
       return
+    case "users":
+      return
     default:
       throw new ScheduleValidationError(
-        "Schedule event source must select object, link, rule, dataset, sync, or pipeline events."
+        "Schedule event source must select object, link, rule, dataset, sync, pipeline, or member events."
       )
   }
 }

package/src/schedules/runtime.ts

@@ -106,6 +106,12 @@ export function buildEventScheduleContext(event: DomainEvent): RuntimeEventSched
       return { ...event.payload }
     case "pipeline.run.finished":
       return { ...event.payload }
+    case "user.joined":
+    case "user.suspended":
+    case "user.reactivated":
+    case "user.invited":
+    case "user.profile.updated":
+      return { ...event.payload }
     default:
       return null
   }

package/src/schedules/validation.ts

@@ -11,6 +11,13 @@ const ruleEventTypes = new Set(["rule.triggered", "rule.resolved"])
 const datasetEventTypes = new Set(["dataset.version.committed"])
 const syncEventTypes = new Set(["sync.run.finished"])
 const pipelineEventTypes = new Set(["pipeline.run.finished"])
+const userEventTypes = new Set([
+  "user.joined",
+  "user.suspended",
+  "user.reactivated",
+  "user.invited",
+  "user.profile.updated",
+])
 const runStatuses = new Set(["succeeded", "failed", "cancelled"])
 const linkIdentityFields = new Set(["target.objectTypeId", "target.primaryId"])
 
@@ -147,9 +154,11 @@ function assertEventSourceShape(
       assertNonEmptyString(value.pipelineId, `${path} pipelineId`, createError)
       assertRunStatus(value.runStatus, path, createError)
       return
+    case "users":
+      return
     default:
       throw createError(
-        `${path} must select object, link, rule, dataset, sync, or pipeline events.`
+        `${path} must select object, link, rule, dataset, sync, pipeline, or member events.`
       )
   }
 }
@@ -234,6 +243,9 @@ function validateEventSchedule(
         "pipeline"
       )
       return
+    case "users":
+      validateMemberSource(schedule)
+      return
   }
 }
 
@@ -295,6 +307,16 @@ function validateRegisteredSource(
   }
 }
 
+// The project has one member directory, so a member event source names nothing to look up.
+function validateMemberSource(schedule: EventScheduleDefinition): void {
+  validateEventTypes(schedule, userEventTypes, "member")
+  if (schedule.trigger.condition) {
+    throw new ScheduleValidationError(
+      `Schedule "${schedule.id}": member event sources do not support .where() conditions.`
+    )
+  }
+}
+
 function validateEventTypes(
   schedule: EventScheduleDefinition,
   supportedTypes: ReadonlySet<string>,

package/src/security/README.md

@@ -0,0 +1,62 @@
+# View conditions
+
+`can.view(Type).where(...)` grants a principal only the objects of `Type` its condition matches.
+This note follows a condition from the role that declares it to every surface that names an
+object. The public contract is in `docs/auth/authorization.md`.
+
+## Startup
+
+1. `view-conditions.ts` validates each condition as a filter over the type and the subtypes the
+   grant covers. It refuses marked properties and ordered text comparisons, and keeps the
+   validated predicate, scalar kinds resolved and frozen.
+2. `registry.ts` resolves them per role with `resolveRoleViewConditions`
+   (`authorization/resolve.ts`): one predicate per concrete type, subtypes included, `or` across
+   the role's conditions. A type the role also views whole drops them.
+3. The `SixbHost` constructor compiles each one through the object storage's conditional scope
+   (`assertViewConditionsReadable`), so a predicate the provider cannot read fails startup and
+   not every read of its type.
+
+## Resolution: closed by default
+
+`resolveAuthorizationContext` (`authorization/resolve.ts`) unions roles. A conditional grant never
+reaches `view:object`: its types land in `viewConditions`, one predicate per role, and a type any
+role views whole leaves `viewConditions`.
+
+Every check that decides on `view:object` therefore denies a conditioned type. That is the safe
+default: a surface that does not know about conditions shows nothing, never everything.
+
+## Reading through the reader
+
+`ObjectReaderSecurity` (`execution/object-reader-security.ts`) turns the context's conditions into
+one compiled conditional scope, `or` across roles. `currentUser()` binds to the context's principal
+when it is a user, and to no one otherwise: never to `execution.requestedBy`, the user an agent's
+service account may run for. Queries keep binding it to the requester.
+
+`AuthorizedObjectReader` reads through `createConditionalReadScope` for that scope, so get, list,
+query, count, facets, search, links and traversals see only matching objects, before `LIMIT` and
+totals. A condition reading a property the reader's clearance hides (a marking a
+dataset version applied) hides the whole type.
+
+`viewsThroughCondition(type)` tells the other surfaces when to read through the reader instead of
+deciding on the type:
+
+| Surface | Where | How |
+| --- | --- | --- |
+| Events | `events/view-conditions.ts` | Object events match the state they carry with `matchesPredicate`; an update that reveals an object loses the values it replaced. Link, telemetry and rule events read their objects through the reader, one batch per call (`visibleObjects`). One of them since deleted is decided on what it held when the event happened: storage tells which unseen objects still exist, and the log's last event of each other one gives its state then (`ObjectEventHistory`). |
+| Telemetry reads | `execution/authorized-object-reader.ts` | Property checks by id read the objects through the reader. |
+| Action runs | `actions/run-authorization.ts`, `actions/execution.ts` | A run shows while its subject reads. Run storage cannot filter by a condition: a listing that names the subject reads it first; any other listing leaves the type out. |
+| Rule matches | `rules/execution.ts` | Same rule as runs: listed per object. |
+| Actions | `actions/request.ts`, `actions/run/context.ts`, `actions/execution.ts` | The subject and `ref()` params must read, or the request fails as not found. Each attempt of the run confirms its requester sees the subject at the version it loaded, so handlers never run on a hidden state. Actions on the type are listed as the reader's ontology lists it. |
+| Writes | `objects/conditional-writes.ts` | Each named object is read first; the commit expects it as read, so one hidden meanwhile is never written. A hidden id reports as taken. |
+| Share issuance | `shares/execution.ts` | The target is read through the issuer's reader; a hidden one is not found. Each type the share's links reach needs `view:object`: a link keeps showing whatever it reaches. The issued link holds its own grants, so it keeps the target after the target stops matching. |
+
+Restores, telemetry appends and projection runs keep deciding on `view:object`, so they stay
+closed to a conditioned type.
+
+## Adding a surface
+
+A surface that names an object must never treat a conditioned type as viewable by its type alone:
+neither `isAllowed(..., { kind: "object.view" })` nor a type list built from `view:object` can
+answer for one object of it. Read the object through the principal's `AuthorizedObjectReader`, as
+the surfaces above do, or leave the type closed. Readers that view a type whole should keep
+answering without a read.