@sixb/core 0.1.20 → 0.1.22

package/src/actions/run/execute.ts

@@ -10,7 +10,12 @@ import type { ActionRunStorage, Storage } from "../../storage"
 import type { ExecutionRecord } from "../../storage/executions"
 import { runAction } from "./run-action"
 import { ActionRunSignals } from "./signals"
-import type { ActionRunContext, ActionRunOutcome, PendingActionRun } from "./types"
+import type {
+  ActionRunContext,
+  ActionRunOutcome,
+  PendingActionRun,
+  ReadSubjectAsRequester,
+} from "./types"
 
 /** What executing a stored Action run needs from its host. */
 export interface ActionRunHost extends PrimitiveExecutionHost {
@@ -25,8 +30,7 @@ export interface ExecuteActionRunInput {
   readonly execution: ExecutionRecord
   /** Cancels the run before its irreversible boundary. */
   readonly signal?: AbortSignal
-  /** Test-only override of the 30-second deadlines of the run and of its effects. */
-  readonly timeoutMs?: number
+  readonly readSubjectAsRequester?: ReadSubjectAsRequester
 }
 
 /**
@@ -54,7 +58,6 @@ export async function executeActionRun(
     actionId: run.actionId,
     runId: run.id,
     caller: input.signal,
-    timeoutMs: input.timeoutMs,
   })
 
   try {
@@ -67,7 +70,7 @@ export async function executeActionRun(
       primitive: { kind: "action", id: run.actionId, runId: run.id },
     })
     return await runAction({
-      runtime: buildActionContext(host, actionRuns, bound),
+      runtime: buildActionContext(host, actionRuns, bound, input.readSubjectAsRequester),
       run,
       signals,
     })
@@ -91,7 +94,8 @@ function requireActionRunStorage(host: ActionRunHost, runId: string): ActionRunS
 function buildActionContext(
   host: ActionRunHost,
   actionRunsStorage: ActionRunStorage,
-  execution: BoundPrimitiveExecution
+  execution: BoundPrimitiveExecution,
+  readSubjectAsRequester: ReadSubjectAsRequester | undefined
 ): ActionRunContext {
   const sixb = {
     models: execution.sixb.models,
@@ -99,6 +103,7 @@ function buildActionContext(
     actions: execution.sixb.actions,
     connector: execution.sixb.connector,
     blobs: execution.sixb.blobs,
+    users: execution.sixb.users,
   }
   return {
     id: host.id,
@@ -109,5 +114,7 @@ function buildActionContext(
     ontologyMutations: execution.ontologyMutations,
     sixb,
     actions: host.definitions.actions,
+    requestedBy: execution.sixb.execution.requestedBy,
+    ...(readSubjectAsRequester === undefined ? {} : { readSubjectAsRequester }),
   }
 }

package/src/actions/run/executor.ts

@@ -10,7 +10,7 @@ import {
 import { type ActionRunHost, executeActionRun } from "./execute"
 import { toActionRunFailure } from "./normalize"
 import { UnrecordedActionRunError } from "./run-action"
-import type { PendingActionRun } from "./types"
+import type { PendingActionRun, ReadSubjectAsRequester } from "./types"
 
 /** A request for an Action run, handed over to execute in the requesting process. */
 export interface ActionRunRequest {
@@ -24,6 +24,8 @@ export interface ActionRunRequest {
   readonly signal?: AbortSignal
   /** Called once the run's execution exists, before the run executes. A throw starts nothing. */
   readonly onRequested?: (runId: string) => void | Promise<void>
+  /** Set when the requester views the subject's type through a condition. */
+  readonly readSubjectAsRequester?: ReadSubjectAsRequester
 }
 
 type NewActionRun = Extract<PersistedActionRun, { readonly kind: "new" }>
@@ -180,7 +182,14 @@ export class ActionRunExecutor {
 
     let outcome: Awaited<ReturnType<typeof executeActionRun>>
     try {
-      outcome = await executeActionRun(this.host, { run, execution, signal: request.signal })
+      outcome = await executeActionRun(this.host, {
+        run,
+        execution,
+        signal: request.signal,
+        ...(request.readSubjectAsRequester === undefined
+          ? {}
+          : { readSubjectAsRequester: request.readSubjectAsRequester }),
+      })
     } catch (error) {
       throw this.failRequest(run, error)
     }

package/src/actions/run/normalize.ts

@@ -6,6 +6,8 @@ import {
   toSixbFailure,
 } from "../../errors/internal"
 import { isMaterializationConflictError } from "../../materialization/errors"
+import { ActionValidationError } from "../../objects/action/errors"
+import { uniqueViolationError } from "../../objects/unique-violation"
 import { ACTION_RUN_FAILURE_CODES, type ActionRunFailure, type ActionRunPhase } from "../../storage"
 import { parseActionRunFailure } from "../../storage/action-runs/failure"
 import { isActionTimeout } from "./signals"
@@ -48,7 +50,8 @@ export async function untilAborted<T>(work: () => Promise<T>, signal: AbortSigna
  * with `action.timeout` when its deadline elapsed, and with `runtime.cancelled` when its caller
  * aborted. The handler's own error stays the cause reported to `onError`. Every expectation an
  * Action commit carries comes from the Action's own reads, so an expectation conflict at commit is
- * a read conflict: the run can be requested again against current state.
+ * a read conflict: the run can be requested again against current state. A validator's returned
+ * error is a rejection, not a crash.
  */
 export function translateActionPhaseError(
   error: unknown,
@@ -82,9 +85,14 @@ export function translateActionPhaseError(
   if (isSixbError(error) && error.code === "internal.unexpected") {
     return error
   }
+  if (error instanceof ActionValidationError) {
+    return createSixbError("action.rejected", error.message, { cause: error, details })
+  }
   if (phase === "commit" && isMaterializationConflictError(error) && error.kind === "expectation") {
     return createSixbError("action.read_conflict", error.message, { cause: error, details })
   }
+  const uniqueViolation = phase === "commit" ? uniqueViolationError(error, details) : undefined
+  if (uniqueViolation) return uniqueViolation
 
   return createSixbError(
     "action.phase_failed",
@@ -97,7 +105,9 @@ export function translateActionPhaseError(
 export function isActionPhaseFailure(error: unknown): error is SixbCodedError {
   return (
     isSixbError(error) &&
-    (error.code === "action.phase_failed" || error.code === "action.read_conflict")
+    (error.code === "action.phase_failed" ||
+      error.code === "action.read_conflict" ||
+      error.code === "action.rejected")
   )
 }
 

package/src/actions/run/phases.ts

@@ -87,6 +87,8 @@ async function commitOnce(
   try {
     objectTarget = await loadObjectTarget({ runtime, action, run: state.run })
   } catch (error) {
+    // The subject changed while its requester's view of it was read: replay as a commit would.
+    if (isReadConflict(error)) throw error
     throw translateActionPhaseError(error, replayingEdits ? "edits" : "validation", {
       ...ids,
       signal,

package/src/actions/run/run-action.ts

@@ -108,8 +108,17 @@ function runFailure(
 }
 
 /**
- * Record a failed run, and report its failure to `onError` once this request recorded it. A run its
- * caller cancelled is not reported: it did not fail on its own.
+ * Failures that are not the run's own: its caller cancelled it, or a validator rejected the request,
+ * which is a business outcome the caller reads on the run.
+ */
+const UNREPORTED_FAILURE_CODES: ReadonlySet<string> = new Set([
+  "runtime.cancelled",
+  "action.rejected",
+])
+
+/**
+ * Record a failed run, and report its failure to `onError` once this request recorded it, unless
+ * it is one of the {@link UNREPORTED_FAILURE_CODES}.
  */
 async function recordFailure(
   runtime: ActionRunContext,
@@ -117,7 +126,7 @@ async function recordFailure(
   error: unknown
 ): Promise<ActionRunOutcome> {
   const outcome = await recordRun(runtime, record)
-  if (outcome.recorded && record.error.code !== "runtime.cancelled") {
+  if (outcome.recorded && !UNREPORTED_FAILURE_CODES.has(record.error.code)) {
     reportRunFailure(runtime.errorReporterHost, unwrapActionPhaseError(error), {
       projectId: runtime.id,
       runKind: "action",

package/src/actions/run/signals.ts

@@ -18,8 +18,6 @@ export interface ActionRunSignalsInput {
   readonly runId: string
   /** The caller's cancellation. It applies before the boundary only. */
   readonly caller?: AbortSignal
-  /** Test-only override of {@link ACTION_TIMEOUT_MS}. */
-  readonly timeoutMs?: number
 }
 
 /**
@@ -89,22 +87,18 @@ export class ActionDeadline {
   readonly signal: AbortSignal
   private readonly timer: ReturnType<typeof setTimeout>
 
-  constructor(
-    input: Pick<ActionRunSignalsInput, "actionId" | "runId" | "timeoutMs">,
-    scope: "run" | "effects"
-  ) {
+  constructor(input: Pick<ActionRunSignalsInput, "actionId" | "runId">, scope: "run" | "effects") {
     const controller = new AbortController()
-    const timeoutMs = input.timeoutMs ?? ACTION_TIMEOUT_MS
     this.signal = controller.signal
     this.timer = setTimeout(() => {
       controller.abort(
         createSixbError(
           "action.timeout",
-          `[Sixb] Action run '${input.runId}' exceeded its ${timeoutMs} ms ${scope} deadline.`,
+          `[Sixb] Action run '${input.runId}' exceeded its ${ACTION_TIMEOUT_MS} ms ${scope} deadline.`,
           { details: { actionId: input.actionId, runId: input.runId } }
         )
       )
-    }, timeoutMs)
+    }, ACTION_TIMEOUT_MS)
   }
 
   /** Release the deadline timer. */

package/src/actions/run/types.ts

@@ -1,11 +1,13 @@
 import type { BlobsRuntime } from "../../blob-storage/execution"
 import type { ConnectorRuntime } from "../../connectors/execution"
+import type { AuthorizablePrincipal } from "../../execution/types"
 import type { LoggingService } from "../../logging/service"
 import type { ModelsRuntime } from "../../models/generation-types"
 import type { ObjectsRuntime } from "../../objects/execution"
 import type { SixbDefinitions } from "../../runtime/definitions"
 import type { OntologyMutationRuntime } from "../../runtime/ontology-mutations"
-import type { ActionRunRecord, ActionRunStorage, Storage } from "../../storage"
+import type { ActionRunRecord, ActionRunStorage, ObjectRow, Storage } from "../../storage"
+import type { UsersRuntime } from "../../users"
 import type { ActionsRuntime } from "../execution"
 import type { ActionRunSignals } from "./signals"
 
@@ -16,6 +18,7 @@ export interface ActionExecutionFacade {
   readonly actions: ActionsRuntime
   readonly connector: ConnectorRuntime
   readonly blobs: BlobsRuntime
+  readonly users: UsersRuntime
 }
 
 export interface ActionRunContext {
@@ -27,8 +30,21 @@ export interface ActionRunContext {
   readonly ontologyMutations: OntologyMutationRuntime
   readonly sixb: ActionExecutionFacade
   readonly actions: Pick<SixbDefinitions["actions"], "getById">
+  /** Who started the chain of executions the run belongs to, when a principal did. */
+  readonly requestedBy: AuthorizablePrincipal | undefined
+  /** Reads the subject as its requester sees it: see {@link ReadSubjectAsRequester}. */
+  readonly readSubjectAsRequester?: ReadSubjectAsRequester
 }
 
+/**
+ * Reads the run's subject through its requester's reader. Present when the requester views the
+ * subject's type only through a condition: the run then acts only on a state its requester sees.
+ */
+export type ReadSubjectAsRequester = (subject: {
+  readonly objectTypeId: string
+  readonly primaryId: string
+}) => Promise<ObjectRow | null>
+
 /**
  * A requested run that has not ended: the request it executes, under the durable execution created
  * for it. Nothing else about it is stored until its terminal record is written.

package/src/actions/run-authorization.ts

@@ -1,7 +1,102 @@
+import { type AuthorizationContext, canViewActionRun, isAllowed } from "../authorization"
+import { AuthorizationError } from "../authorization/errors"
 import type { ResolvedRuntimeAuthorization } from "../execution/authorization"
+import { type AuthorizedObjectReader, readerClearance } from "../execution/authorized-object-reader"
 import type { Storage } from "../storage"
 import type { ActionRunRecord } from "../storage/action-runs"
 import { findPrimitiveParentRequestExecution } from "../storage/executions/run-link"
+import { objectBatchKey } from "../storage/objects/keys"
+import type { ActionObjectSubject } from "./types"
+
+/**
+ * The runs among these a principal may view. `canViewActionRun` decides on the subject's type,
+ * which a type the principal views through a condition fails: a run on one is viewable while the
+ * condition shows its subject now. A deleted subject shows nothing, so its runs stay hidden.
+ */
+export async function viewableActionRuns<
+  TRun extends Pick<ActionRunRecord, "actionId" | "subject">,
+>(
+  objectReader: AuthorizedObjectReader,
+  authorization: AuthorizationContext | null | undefined,
+  runs: readonly TRun[]
+): Promise<readonly TRun[]> {
+  if (!authorization) return runs
+
+  const subjectThroughCondition = (run: TRun): ActionObjectSubject | undefined =>
+    run.subject.kind === "object" &&
+    authorization.viewConditions?.has(run.subject.objectTypeId) === true &&
+    isAllowed(authorization, { kind: "action.apply", actionId: run.actionId })
+      ? run.subject
+      : undefined
+
+  const subjects = runs.flatMap((run) => subjectThroughCondition(run) ?? [])
+  const shown = subjects.length === 0 ? new Set() : await readableSubjects(objectReader, subjects)
+
+  return runs.filter((run) => {
+    if (canViewActionRun(authorization, run)) return true
+
+    const subject = subjectThroughCondition(run)
+    return (
+      subject !== undefined && shown.has(objectBatchKey(subject.objectTypeId, subject.primaryId))
+    )
+  })
+}
+
+/**
+ * The action subjects the reader reads now, by `objectBatchKey`: object type grants, conditions,
+ * markings and existence alike. One batch per object type, as a type the reader cannot see fails
+ * its whole batch.
+ */
+export async function readableSubjects(
+  objectReader: AuthorizedObjectReader,
+  subjects: readonly ActionObjectSubject[]
+): Promise<ReadonlySet<string>> {
+  const byType = new Map<string, Map<string, ActionObjectSubject>>()
+  for (const subject of subjects) {
+    const items = byType.get(subject.objectTypeId) ?? new Map()
+    items.set(subject.primaryId, subject)
+    byType.set(subject.objectTypeId, items)
+  }
+
+  const readable = new Set<string>()
+  await Promise.all(
+    [...byType.values()].map(async (items) => {
+      try {
+        const rows = await objectReader.getByPrimaryIdBatch({ items: [...items.values()] })
+        for (const key of rows.keys()) {
+          readable.add(key)
+        }
+      } catch (error) {
+        if (!(error instanceof AuthorizationError)) {
+          throw error
+        }
+      }
+    })
+  )
+  return readable
+}
+
+/**
+ * Whether the reader can read the object type of a run's subject under the markings of the
+ * versions projections applied. A run names its subject's id, so a run on a type the reader
+ * cannot read is hidden like one on a type it has no view grant for.
+ */
+export async function canReadActionRunSubject(
+  objectReader: AuthorizedObjectReader,
+  run: Pick<ActionRunRecord, "subject">
+): Promise<boolean> {
+  if (run.subject.kind !== "object") return true
+  const clearance = await readerClearance(objectReader)
+  return clearance?.unreadableType(run.subject.objectTypeId) === undefined
+}
+
+/** The object types whose runs the reader cannot read, to leave out of a run listing. */
+export async function unreadableActionRunTypes(
+  objectReader: AuthorizedObjectReader
+): Promise<ReadonlySet<string>> {
+  const clearance = await readerClearance(objectReader)
+  return new Set(clearance?.unreadable().types.keys())
+}
 
 /** Check both current grant scope and immutable request provenance for a delegated Action run. */
 export async function canDelegationAccessActionRun(input: {

package/src/actions/types/context.ts

@@ -1,6 +1,7 @@
 import type { BlobsRuntime } from "../../blob-storage/execution"
 import type { ConnectorRuntime } from "../../connectors"
 import type { RecordEditsContext } from "../../edits"
+import type { AuthorizablePrincipal } from "../../execution/types"
 import type { Logger } from "../../logging"
 import type {
   EffectiveLinkChange,
@@ -11,7 +12,9 @@ import type { ModelsRuntime } from "../../models/generation-types"
 import type { ObjectType, Property } from "../../ontology"
 import type { InferPropertyUnit, InferPropertyValue } from "../../ontology/inference"
 import type { ObjectTypeWithPropertyTokens, PropertyToken } from "../../ontology/tokens"
+import type { UserRef } from "../../ontology/user-ref"
 import type { ObjectReader } from "../../runtime/types"
+import type { UsersRuntime } from "../../users"
 import type { ActionPrimitiveSchemaValues } from "./params"
 
 export type ActionTargetObject<TObjectType extends ObjectType = ObjectType> = {
@@ -42,9 +45,13 @@ type InferActionSnapshotPropertyValue<TPropertyToken> = TPropertyToken extends {
 
 type InferActionSnapshotSchemaValue<TSchema> = TSchema extends keyof ActionPrimitiveSchemaValues
   ? ActionPrimitiveSchemaValues[TSchema]
-  : TSchema extends { readonly type: "enum"; readonly values: readonly (infer TValue)[] }
-    ? TValue
-    : unknown
+  : TSchema extends "userRef"
+    ? UserRef
+    : TSchema extends { readonly type: "array"; readonly items: "userRef" }
+      ? readonly UserRef[]
+      : TSchema extends { readonly type: "enum"; readonly values: readonly (infer TValue)[] }
+        ? TValue
+        : unknown
 
 export type ActionSubject = { readonly kind: "none" } | ActionObjectSubject
 
@@ -158,6 +165,7 @@ export interface ActionRuntimeFacade {
   readonly blobs: ActionBlobContext
   readonly models: ModelsRuntime
   readonly connector: ConnectorRuntime
+  readonly users: UsersRuntime
   objects<const TObjectType extends ObjectTypeWithPropertyTokens>(
     objectType: TObjectType
   ): ActionTelemetryObjectSet<TObjectType>
@@ -184,6 +192,15 @@ export interface BaseActionPhaseContext<TParams extends Record<string, unknown>>
   readonly run: ActionRunPhaseInfo
   readonly params: TParams
   readonly subject: ActionSubject
+  /**
+   * On whose behalf the run happens: the user or service account that started the chain of
+   * executions it belongs to, meaning the caller, or whoever started the workflow or agent run that
+   * requested it. It does not mean they approved this exact request: an agent's request carries it
+   * too. `undefined` when no principal did, as for a schedule, an event or a shared link. Once
+   * narrowed with `requestedBy?.type === "user"`, it is a `ref.user()` value you can compare or
+   * store.
+   */
+  readonly requestedBy: AuthorizablePrincipal | undefined
   /**
    * Aborts when the caller cancels the run or it runs out of time: a run has 30 seconds until its
    * writeback succeeds or its edits commit, and its effects have 30 more after the commit. Forward

package/src/actions/validators.ts

@@ -1,3 +1,4 @@
+import { withFailureMessage } from "../errors/failure-message"
 import { ActionValidationError } from "../objects/action/errors"
 import type { ActionDefinition, ActionSubject, ActionTargetObject } from "./types"
 import { isObjectActionDefinition } from "./validation"
@@ -19,10 +20,7 @@ export async function runActionValidators<TBaseContext extends object>(input: {
     for (const validator of validators) {
       const result = await validator(input.baseContext)
       if (isValidatorErrorResult(result)) {
-        throw new ActionValidationError(result.error, {
-          actionId: input.action.id,
-          subject: input.subject,
-        })
+        throw validatorRejection(input, result.error)
       }
     }
     return
@@ -38,14 +36,27 @@ export async function runActionValidators<TBaseContext extends object>(input: {
       target: input.target,
     })
     if (isValidatorErrorResult(result)) {
-      throw new ActionValidationError(result.error, {
-        actionId: input.action.id,
-        subject: input.subject,
-      })
+      throw validatorRejection(input, result.error)
     }
   }
 }
 
+/**
+ * The run fails with `action.rejected` and this message, which the author wrote for the caller. A
+ * thrown error's message stays private: it can come from anything the handler called.
+ */
+function validatorRejection(
+  input: { readonly action: ActionDefinition; readonly subject: ActionSubject },
+  message: string
+): ActionValidationError {
+  const rejection = new ActionValidationError(message, {
+    actionId: input.action.id,
+    subject: input.subject,
+  })
+
+  return withFailureMessage(rejection, message)
+}
+
 function isValidatorErrorResult(value: unknown): value is { readonly error: string } {
   return (
     typeof value === "object" &&

package/src/activity/README.md

@@ -0,0 +1,158 @@
+# Activity
+
+Internal invariants for app usage history. For setup, see the
+[developer guide](../../../../docs/apps/activity.md).
+
+## Data model
+
+| Record | Purpose |
+| --- | --- |
+| Source | Capture state of one verified session, shared by its tabs: current visit, last activity, sequence and quota window. Unrelated to `utm_source`. |
+| Visit | Actor, session id, first and last activity, page-view and interaction counts and arrival attribution. A new visit starts after inactivity, or once the current one is a day old. |
+| Page view | Normalized route, server receipt time and sequence within the visit. |
+| Interaction | Name the app chose, normalized route, server receipt time and sequence, shared with page views. |
+
+A source is keyed by the actor type and the session id: the `SessionRecord` id for a user, the
+shared session's id for a share. Neither is a secret (a user session's token is stored as
+`tokenHash`). The visit keeps the same id, so it can be joined with the execution ledger
+(`authority_session_id`) and with the session's device. Reads never return it.
+
+`page.view` is a load or a navigation and is stored. `visit.activity` is foreground activity: it
+moves the visit's last activity and the source's state, counts toward the quota, and inserts
+nothing, except when it opens a visit (someone back on a page after inactivity): it is then stored
+as the visit's first page view, of that route. Hidden navigation is reported once visible. This is
+not audit evidence.
+
+`ui.interaction` is something the app marked, by name: it is stored, and is activity as well. Page
+views and interactions take the visit's sequence in the order a batch sends them, so the timeline
+reads both in one ordered, bounded pass. An interaction carries no attribution. One that opens a
+visit (after the day-long cap, inactivity the browser had not seen, or a deleted visit) opens it as
+activity does, on a page view of its route: that row's id is the interaction's with `.page`
+appended, outside the event-id alphabet, and the visit's arrival is direct (`{}`). A retry of the
+interaction is recognized by its own id, so neither row repeats.
+
+A visit continues while its session is active and it is younger than a day
+(`ACTIVITY_MAX_VISIT_MS`): the next event after either limit starts another. The cap is what lets a
+period read bound `started_at` on both sides. A source whose current visit was deleted starts a
+new one with its next event.
+
+## Capture and storage
+
+- **Authority:** actor and session come from verified authorization only; a browser never names
+  either. HTTP capture takes a non-bearer cookie session or a shared-link session, nothing else.
+  Every read requires `can.observe(project.activity)`.
+- **Atomic append:** providers serialize writes per source, including across replicas, and take
+  part in the storage transaction they run in. The [shared policy](../storage/activity/policy.ts)
+  owns deduplication, the quota, visit assignment, sequence and monotonic receipt time.
+- **Retries:** an event whose id the session already stored is a retry, whether it was sent as a
+  page view or as the activity that opened a visit, or is an interaction: it neither extends the
+  visit nor uses quota, and the same id with another type, name, route or attribution fails. Other
+  activity is not stored, so a retried `visit.activity` counts again: it moves last activity to the
+  retry's receipt and uses quota. The browser gives up within about a minute, so that drift is
+  bounded.
+- **Browser:** capture-config supplies enabled and the idle timeout once per authority; the server
+  stays authoritative. The in-memory queue is discarded on disposal, with at most three attempts,
+  one-minute expiry and ten seconds per request. A refusal (4xx) drops the batch; a 429 waits for
+  its `Retry-After`. Delivery and exact duration are not guaranteed.
+- **Clock:** receipt time never moves back within a session, so a server clock stepping back
+  cannot reorder a visit.
+- **Interactions:** explicit marking only, by `data-sixb-track` or `trackSixbEvent`; no
+  autocapture, element text, selector or value. Names are lowercase dotted segments, each starting
+  with a letter, at most 40 characters and without a run of four digits, 100 in all
+  (`ACTIVITY_INTERACTION_NAME_PATTERN`): what fails is usually a value. No pattern catches every
+  value; names are meant to be constants. The browser drops an invalid name and warns, for the
+  first 20 distinct ones; the API refuses the batch.
+- **Browser interactions:** one capture-phase click listener on the document, trusted events only,
+  finds the marked element on the event's composed path. A click inside a disabled or
+  `aria-disabled` part of it is ignored, and so is a click on a label whose control is inside the
+  same marked element: the click the browser forwards to the control records it once. The same
+  name within a second is recorded once. A marked click is input, so it keeps the visit going; a
+  `trackSixbEvent` call is not, and is dropped once the person has been idle for the idle timeout,
+  so background code cannot keep a visit alive. Before the capture settings load, in a hidden tab
+  or on an unrecorded page, an interaction is dropped, not queued: it would otherwise reach the
+  server before its page view.
+- **Retention:** no automatic expiration. Deleting one user's history is deleting their visits
+  (`user_id`), whose page views and interactions cascade, and the sources whose current visit was
+  one of them.
+
+## Attribution
+
+| Value | Meaning |
+| --- | --- |
+| `{ source, medium, campaign }` | Available UTM labels, each limited to 100 characters. Missing labels stay absent. |
+| `{ referrer }` | External hostname only; never a full URL. |
+| `{}` | Direct arrival. |
+| `null` | Not collected. |
+
+- The first accepted event of a visit, page view or activity, fixes its attribution. A page view
+  keeps its own attribution only to recognize a retry.
+- Later events send `{}`, so a visit started by inactivity does not inherit an old campaign. A
+  fresh document captures its own arrival. These are browser claims, not authorization evidence.
+- Sixb redirects keep sanitized arrival metadata in per-tab, API- and authority-scoped
+  `sessionStorage` for 30 minutes, consumed on return. New UTMs take priority. Blocked storage
+  falls back to the current URL and referrer without blocking navigation.
+
+## Reads and counting
+
+- **UTC everywhere.** A period `[from, to)`, at most 31 days, lists the visits it overlaps
+  (`started_at < to` and `last_seen_at >= from`) and counts the page views received in it. As a
+  visit lasts less than a day, the read also bounds `started_at >= from - 1 day`, which keeps it to
+  a range of the `started_at` indexes. A visit's own `pageViews` and `lastSeenAt` are the whole
+  visit's.
+- A visit spanning midnight counts on both days, even when one of them holds only activity.
+  Never sum daily visits into a period total. Shares never count as identified users.
+- The calendar covers one UTC year from the user's visits; days are expanded by the policy, so
+  every provider counts them alike.
+- User filters precede counts and pagination. Display names resolve only for the accounts of
+  one page; no emails or other profile fields are returned. Shared visits name their link's share
+  definition (`actor.definitionId` on `ActivityVisitView`, never on the stored actor), from one
+  grant read for the page or visit; a grant that is gone leaves the grant id alone. The timeline
+  reuses that grant for the share connection's status.
+- Visit and user cursors use last activity plus id, newest first. Ids compare byte by byte
+  (`COLLATE "C"` in PostgreSQL); generated visit ids are ASCII, so every provider orders them alike.
+  A visit's page views and interactions read by their shared sequence, the first 200 of them in
+  its timeline, which is the only read of one visit. Live activity can move a visit between pages,
+  so clients deduplicate ids and offer a refresh.
+
+## Timeline and connections
+
+A visit's timeline joins it with what its session did, by the session id alone: never by user and
+time range, so the same user's other browser, active at the same time, stays out.
+
+- **Join:** roots are the executions without a parent whose verified session is the visit's,
+  `authority_session_id` for a user and `authority_delegation_session_id` for a share. Read-only
+  requests write none. Their descendants are found through `parent_execution_id`, not
+  `correlation_id`, which a client can set. An Agent execution copies its parent's session; requiring
+  no parent keeps it from counting as a root.
+- **Window:** roots created in `[start - 30 s, last activity + 30 s)`, capped 30 s before the
+  visit's day-long limit. A click right after a return reaches the server before the activity
+  that opens the visit, and an action just before leaving may follow the last activity sent. Half
+  the shortest idle timeout keeps two visits of a session from sharing an execution. Descendants
+  are not time-filtered: a queued workflow or an Agent's tools may run long after the visit.
+- **Entries:** page views, interactions, action runs, workflow runs and conversation Agent runs, by
+  time; page views and interactions in their sequence. An action execution without a recorded run
+  is `incomplete`: in flight, or interrupted. An Agent run's cost includes everything below it,
+  subagents and tools included; a Workflow's Agent steps are not conversations and have no entry.
+  Page views and interactions are at their server receipt, executions at their creation: the
+  app's steps credit an execution to the last page view before it, so one started as the page
+  changed can land in the neighboring step.
+- **Content:** a run shows its thread's message count, never its messages. Its title, under
+  `thread`, only for a viewer who also holds `can.observe(agent.threads)`, the grant that opens
+  the conversation itself (`sixb.agent.observed`); `thread` is also what tells the app it may link
+  there. Activity alone never reveals a conversation. An action
+  names its object only when the viewer's own object reader returns it, so object type grants,
+  markings and deletion all hide it. `runVisible` says whether the viewer may read the run
+  itself, decided as the runs reads decide it (`viewableActionRuns` and the subject type's
+  markings, `canViewWorkflowRun`); the app links a run only then.
+- **Bounds:** 200 page views and interactions together, and 200 recorded executions, roots first
+  and the earliest first. Past either limit `truncated` is set and the timeline stops at the last
+  page view or interaction, or the last root, it kept: the cut leaves no gap where one source is
+  missing. One read per source: the visit, the ledger, the session, action runs, workflow runs,
+  Agent runs, costs, threads, and one object batch per object type.
+- **Connections:** a user's sessions, revoked and expired ones too, newest first, with the device
+  their user agent names (browser and system only), a native client's label, and each session's
+  visit count and latest five visits. No address, user agent or session id is returned: the
+  cursor holds a creation time and how many sessions created then were returned. A share's
+  session has no device: its connection is the link's grant, and it reads as revoked or expired
+  once either the session or the grant is.
+