@sixb/core 0.1.6 → 0.1.8

package/src/security/grants.ts

@@ -7,12 +7,20 @@
  * checks stay simple `set.has(id)` lookups.
  */
 
-import type { ActionDefinition } from "../actions/types"
-import type { AgentDefinition } from "../agents/types"
+import type { ActionDefinition, ObjectActionDefinition } from "../actions/types"
+import { isObjectActionDefinition } from "../actions/validation"
+import type { AgentReference, AgentUsageReference } from "../agents/types"
 import type { ConnectorDefinition } from "../connectors"
 import type { DatasetDefinition } from "../datasets"
 import type { ObjectType } from "../ontology"
 import type { PipelineDefinition } from "../pipelines"
+import { createShareActionGrant, createShareViewGrant, isShareTarget } from "../shares/builders"
+import type {
+  ShareActionGrantBuilder,
+  ShareDefinition,
+  ShareTarget,
+  ShareViewGrantBuilder,
+} from "../shares/types"
 import type { SyncDefinition } from "../syncs"
 import type { WorkflowDefinition } from "../workflows/types"
 import { SecurityValidationError } from "./errors"
@@ -24,6 +32,7 @@ import {
 } from "./every"
 import type {
   AccessGrant,
+  AgentRunGrant,
   AppendGrant,
   ApplicationDefinition,
   ApplyGrant,
@@ -32,6 +41,7 @@ import type {
   ObserveGrant,
   RunGrant,
   Selection,
+  ShareGrant,
   ViewGrant,
 } from "./types"
 
@@ -41,7 +51,7 @@ type GrantInput<TDefinition, TTarget extends BreadthTarget> =
   | BreadthSelector<TTarget>
 
 const VIEW_TARGETS = ["object", "dataset"] as const
-const RUN_TARGETS = ["workflow", "sync", "pipeline", "agent"] as const
+const RUN_TARGETS = ["workflow", "sync", "pipeline"] as const
 
 /**
  * Seven of the nine targets carry a `kind` discriminant naming themselves. The other two — an
@@ -52,10 +62,10 @@ const TARGET_BY_DEFINITION_KIND: Readonly<Partial<Record<string, BreadthTarget>>
   dataset: "dataset",
   sync: "sync",
   pipeline: "pipeline",
-  agent: "agent",
   workflow: "workflow",
   application: "application",
   connector: "connector",
+  share: "share",
 }
 
 const UNDISCRIMINATED_TARGETS: readonly BreadthTarget[] = ["object", "action"]
@@ -153,9 +163,15 @@ function access(input: GrantInput<ApplicationDefinition, "application">): Access
   return { kind: "grant", capability: "access", target: "application", selection }
 }
 
+function view<const TObjectTypeId extends string>(
+  input: ShareTarget<TObjectTypeId>
+): ShareViewGrantBuilder<TObjectTypeId>
 function view(input: GrantInput<ObjectType, "object">): ViewGrant<"object">
 function view(input: GrantInput<DatasetDefinition, "dataset">): ViewGrant<"dataset">
-function view(input: GrantInput<ObjectType | DatasetDefinition, "object" | "dataset">): ViewGrant {
+function view(
+  input: ShareTarget | GrantInput<ObjectType | DatasetDefinition, "object" | "dataset">
+): ViewGrant | ShareViewGrantBuilder {
+  if (isShareTarget(input)) return createShareViewGrant(input)
   const { target, selection } = resolveGrant(input, "can.view", VIEW_TARGETS)
   return { kind: "grant", capability: "view", target, selection }
 }
@@ -176,29 +192,85 @@ function append(input: GrantInput<ObjectType, "object">): AppendGrant {
   }
 }
 
+function apply<const TAction extends ObjectActionDefinition>(
+  input: TAction
+): ApplyGrant & ShareActionGrantBuilder<TAction>
+function apply(input: GrantInput<ActionDefinition, "action">): ApplyGrant
 function apply(input: GrantInput<ActionDefinition, "action">): ApplyGrant {
-  return {
+  const grant: ApplyGrant = {
     kind: "grant",
     capability: "apply",
     selection: resolveGrant(input, "can.apply", ["action"]).selection,
   }
+  // `Array.isArray` does not narrow a readonly array. This cast restores the branch already proved
+  // above; every non-selector, non-array GrantInput is one Action definition.
+  const one: ActionDefinition | undefined =
+    Array.isArray(input) || isBreadthSelector(input) ? undefined : (input as ActionDefinition)
+  if (one && isObjectActionDefinition(one)) {
+    Object.defineProperty(grant, "on", {
+      configurable: false,
+      enumerable: false,
+      writable: false,
+      value: (target: ShareTarget) => createShareActionGrant(one, target),
+    })
+  }
+  return grant
+}
+
+function share(input: GrantInput<ShareDefinition, "share">): ShareGrant {
+  return {
+    kind: "grant",
+    capability: "share",
+    selection: resolveGrant(input, "can.share", ["share"]).selection,
+  }
 }
 
 function run(input: GrantInput<WorkflowDefinition, "workflow">): RunGrant<"workflow">
 function run(input: GrantInput<SyncDefinition, "sync">): RunGrant<"sync">
 function run(input: GrantInput<PipelineDefinition, "pipeline">): RunGrant<"pipeline">
-function run(input: GrantInput<AgentDefinition, "agent">): RunGrant<"agent">
+function run(input: AgentReference): AgentRunGrant
 function run(
-  input: GrantInput<
-    WorkflowDefinition | SyncDefinition | PipelineDefinition | AgentDefinition,
-    "workflow" | "sync" | "pipeline" | "agent"
-  >
-): RunGrant {
+  input:
+    | AgentReference
+    | GrantInput<
+        WorkflowDefinition | SyncDefinition | PipelineDefinition,
+        "workflow" | "sync" | "pipeline"
+      >
+): RunGrant | AgentRunGrant {
+  if (isAgentReference(input)) {
+    return { kind: "grant", capability: "run", target: "agent" }
+  }
   const { target, selection } = resolveGrant(input, "can.run", RUN_TARGETS)
   return { kind: "grant", capability: "run", target, selection }
 }
 
-function observe(target: "logs"): ObserveGrant {
+function isAgentReference(input: unknown): input is AgentReference {
+  return (
+    typeof input === "object" &&
+    input !== null &&
+    !Array.isArray(input) &&
+    !isBreadthSelector(input) &&
+    "kind" in input &&
+    input.kind === "agent"
+  )
+}
+
+function isAgentUsageReference(input: unknown): input is AgentUsageReference {
+  return (
+    typeof input === "object" &&
+    input !== null &&
+    !Array.isArray(input) &&
+    !isBreadthSelector(input) &&
+    "kind" in input &&
+    input.kind === "aiUsage"
+  )
+}
+
+function observe(input: "logs" | AgentUsageReference): ObserveGrant {
+  if (input !== "logs" && !isAgentUsageReference(input)) {
+    throw new SecurityValidationError('[Sixb] can.observe accepts "logs" or agent.usage.')
+  }
+  const target = input === "logs" ? "logs" : "aiUsage"
   return {
     kind: "grant",
     capability: "observe",
@@ -207,10 +279,23 @@ function observe(target: "logs"): ObserveGrant {
   }
 }
 
-function manage(input: GrantInput<ConnectorDefinition, "connector">): ManageGrant {
+function manage(input: GrantInput<ConnectorDefinition, "connector">): ManageGrant<"connector">
+function manage(input: AgentUsageReference): ManageGrant<"aiUsage">
+function manage(
+  input: GrantInput<ConnectorDefinition, "connector"> | AgentUsageReference
+): ManageGrant {
+  if (isAgentUsageReference(input)) {
+    return {
+      kind: "grant",
+      capability: "manage",
+      target: "aiUsage",
+      selection: { all: false, ids: ["aiUsage"] },
+    }
+  }
   return {
     kind: "grant",
     capability: "manage",
+    target: "connector",
     selection: resolveGrant(input, "can.manage", ["connector"]).selection,
   }
 }
@@ -221,6 +306,7 @@ export const can = {
   edit,
   append,
   apply,
+  share,
   run,
   observe,
   manage,

package/src/security/index.ts

@@ -20,6 +20,7 @@ export type { SecurityDefinitionCatalog, SecurityRegistryOptions } from "./regis
 export { SecurityRegistry } from "./registry"
 export type {
   AccessGrant,
+  AgentRunGrant,
   AppendGrant,
   ApplicationDefinition,
   ApplyGrant,
@@ -29,6 +30,7 @@ export type {
   GroupDefinition,
   GroupReference,
   ManageGrant,
+  ManageGrantTarget,
   MembershipOperation,
   MembershipPolicyDefinition,
   ObserveGrant,
@@ -38,6 +40,7 @@ export type {
   RunGrant,
   RunGrantTarget,
   Selection,
+  ShareGrant,
   ViewGrant,
   ViewGrantTarget,
 } from "./types"

package/src/security/registry.ts

@@ -25,8 +25,9 @@ export interface SecurityRegistryOptions {
   readonly workflowIds?: ReadonlySet<string>
   readonly syncIds?: ReadonlySet<string>
   readonly pipelineIds?: ReadonlySet<string>
-  readonly agentIds?: ReadonlySet<string>
+  readonly agentAvailable?: boolean
   readonly connectorIds?: ReadonlySet<string>
+  readonly shareIds?: ReadonlySet<string>
   readonly getSubTypes?: (objectTypeId: string) => readonly string[]
 }
 
@@ -48,9 +49,11 @@ export class SecurityRegistry implements SecurityDefinitionCatalog {
       workflowIds: input.workflowIds,
       syncIds: input.syncIds,
       pipelineIds: input.pipelineIds,
-      agentIds: input.agentIds,
+      agentAvailable: input.agentAvailable,
       connectorIds: input.connectorIds,
-      observableIds: new Set(["logs"]),
+      observableIds: new Set(["logs", "aiUsage"]),
+      manageableIds: new Set(["aiUsage"]),
+      shareIds: input.shareIds,
     })
 
     const universe = {
@@ -61,9 +64,10 @@ export class SecurityRegistry implements SecurityDefinitionCatalog {
       workflowIds: input.workflowIds ?? new Set<string>(),
       syncIds: input.syncIds ?? new Set<string>(),
       pipelineIds: input.pipelineIds ?? new Set<string>(),
-      agentIds: input.agentIds ?? new Set<string>(),
       connectorIds: input.connectorIds ?? new Set<string>(),
-      observableIds: new Set(["logs"]),
+      observableIds: new Set(["logs", "aiUsage"]),
+      manageableIds: new Set(["aiUsage"]),
+      shareIds: input.shareIds ?? new Set<string>(),
       getSubTypes: input.getSubTypes ?? (() => []),
     }
 

package/src/security/types.ts

@@ -86,7 +86,14 @@ export interface ApplyGrant {
   readonly selection: Selection
 }
 
-export type RunGrantTarget = "workflow" | "sync" | "pipeline" | "agent"
+/** Issue, list, and revoke grants created from the selected Share definitions. */
+export interface ShareGrant {
+  readonly kind: "grant"
+  readonly capability: "share"
+  readonly selection: Selection
+}
+
+export type RunGrantTarget = "workflow" | "sync" | "pipeline"
 
 export interface RunGrant<TTarget extends RunGrantTarget = RunGrantTarget> {
   readonly kind: "grant"
@@ -95,7 +102,14 @@ export interface RunGrant<TTarget extends RunGrantTarget = RunGrantTarget> {
   readonly selection: Selection
 }
 
-export type ObserveGrantTarget = "logs"
+/** Run the project's single conversational Agent. */
+export interface AgentRunGrant {
+  readonly kind: "grant"
+  readonly capability: "run"
+  readonly target: "agent"
+}
+
+export type ObserveGrantTarget = "logs" | "aiUsage"
 
 export interface ObserveGrant {
   readonly kind: "grant"
@@ -104,10 +118,13 @@ export interface ObserveGrant {
   readonly selection: Selection
 }
 
-/** Manage the OAuth connection lifecycle for selected connector definitions. */
-export interface ManageGrant {
+export type ManageGrantTarget = "connector" | "aiUsage"
+
+/** Manage a selected connector or the project's AI usage-limit policies. */
+export interface ManageGrant<TTarget extends ManageGrantTarget = ManageGrantTarget> {
   readonly kind: "grant"
   readonly capability: "manage"
+  readonly target: TTarget
   readonly selection: Selection
 }
 
@@ -117,7 +134,9 @@ export type GrantDefinition =
   | EditGrant
   | AppendGrant
   | ApplyGrant
+  | ShareGrant
   | RunGrant
+  | AgentRunGrant
   | ObserveGrant
   | ManageGrant
 

package/src/security/validation.ts

@@ -8,10 +8,13 @@ import type {
   MembershipPolicyDefinition,
   RegisteredSecurityDefinitions,
   RoleDefinition,
+  Selection,
 } from "./types"
 
-/** Registered id universes keyed as the grant-kind table expects them. */
-type RegisteredUniverses = Partial<Record<GrantUniverseKey, ReadonlySet<string>>>
+/** Registered id universes and singleton capabilities available to role grants. */
+type RegisteredUniverses = Partial<Record<GrantUniverseKey, ReadonlySet<string>>> & {
+  readonly agentAvailable?: boolean
+}
 
 /**
  * Every grant capability, for validating grants that arrive from untyped code.
@@ -27,6 +30,7 @@ const GRANT_CAPABILITIES = Object.keys({
   edit: true,
   append: true,
   apply: true,
+  share: true,
   run: true,
   observe: true,
   manage: true,
@@ -220,12 +224,19 @@ export function assertGrantDefinition(
     )
   }
 
-  if (value.capability === "observe" && value.target !== "logs") {
-    throw createError(`[Sixb] ${field} observe grant target must be 'logs'.`)
+  if (value.capability === "observe" && value.target !== "logs" && value.target !== "aiUsage") {
+    throw createError(`[Sixb] ${field} observe grant target must be 'logs' or 'aiUsage'.`)
+  }
+
+  if (value.capability === "manage" && value.target !== "connector" && value.target !== "aiUsage") {
+    throw createError(`[Sixb] ${field} manage grant target must be 'connector' or 'aiUsage'.`)
   }
 
-  if (value.capability === "manage" && value.target !== undefined) {
-    throw createError(`[Sixb] ${field} manage grant must not declare a target.`)
+  if (value.capability === "run" && value.target === "agent") {
+    if (value.selection !== undefined) {
+      throw createError(`[Sixb] ${field} agent run grant must not declare a selection.`)
+    }
+    return
   }
 
   assertSelection(value.selection, field, createError)
@@ -235,7 +246,7 @@ function assertSelection(
   value: unknown,
   field: string,
   createError: CreateSecurityError
-): asserts value is GrantDefinition["selection"] {
+): asserts value is Selection {
   if (!isRecord(value) || typeof value.all !== "boolean") {
     throw createError(`[Sixb] ${field} grant must carry a selection from 'can' or a scope.`)
   }
@@ -303,12 +314,16 @@ export function validateSecurityDefinitionsAtStartup(input: {
   readonly syncIds?: ReadonlySet<string>
   /** Registered pipeline ids — when provided, pipeline run grants must reference them. */
   readonly pipelineIds?: ReadonlySet<string>
-  /** Registered agent ids — when provided, agent run grants must reference them. */
-  readonly agentIds?: ReadonlySet<string>
+  /** Whether the project's single conversational Agent is configured. */
+  readonly agentAvailable?: boolean
   /** Registered observability surfaces. */
   readonly observableIds?: ReadonlySet<string>
+  /** Registered singleton management surfaces. */
+  readonly manageableIds?: ReadonlySet<string>
   /** Registered connector ids — when provided, manage grants must reference them. */
   readonly connectorIds?: ReadonlySet<string>
+  /** Registered Share ids — when provided, share grants must reference them. */
+  readonly shareIds?: ReadonlySet<string>
 }): RegisteredSecurityDefinitions {
   const groupsById = new Map<string, GroupDefinition>()
   const rolesById = new Map<string, RoleDefinition>()
@@ -415,6 +430,15 @@ function assertGrantReferences(
   grant: GrantDefinition,
   registered: RegisteredUniverses
 ): void {
+  if (grant.capability === "run" && grant.target === "agent") {
+    const spec = GRANT_KINDS[grantKindOf(grant)]
+    if (!registered.agentAvailable) {
+      throw new SecurityValidationError(
+        `[Sixb] Role '${roleId}' grants ${grant.capability} on the project Agent, but it is unavailable. ${spec.fix}`
+      )
+    }
+    return
+  }
   const spec = GRANT_KINDS[grantKindOf(grant)]
   const universe = registered[spec.universeKey]
 

package/src/shares/access-plan.ts

@@ -0,0 +1,225 @@
+import type { ObjectRef } from "../ontology"
+import {
+  captureSelectedObjectReadScope,
+  compileSelectedObjectReadScope,
+} from "../storage/objects/read-scope"
+import type { ObjectReadRoot, SelectedObjectReadScope } from "../storage/objects/types"
+
+const MAX_SCOPED_GRANTS = 1_024
+const MAX_SCOPED_VIEW_ROOTS_BEFORE_COMPILATION = 1_024
+const MAX_SCOPED_ACTION_SUBJECTS = 4_096
+const MAX_SCOPED_ACTION_IDENTIFIER_CHARACTERS = 1_000_000
+
+/** One capability paired with the exact resources it authorizes. */
+export type ShareScopedGrant = ShareScopedViewGrant | ShareScopedActionGrant
+
+export interface ShareScopedViewGrant {
+  readonly kind: "object.view"
+  readonly selection: SelectedObjectReadScope
+}
+
+export interface ShareScopedActionGrant {
+  readonly kind: "action.apply"
+  readonly actionId: string
+  readonly subjects: readonly ObjectRef[]
+}
+
+/** Internal authority compiled from a delegation such as a shared-access grant. */
+export interface ShareAccessPlan {
+  readonly grants: readonly ShareScopedGrant[]
+}
+
+interface CapturedViewGrant {
+  readonly kind: "object.view"
+  readonly rootStart: number
+  readonly rootCount: number
+}
+
+type CapturedGrant = CapturedViewGrant | ShareScopedActionGrant
+
+interface ActionCaptureBudget {
+  subjectCount: number
+  identifierCharacters: number
+}
+
+/** Validate and detach an access plan before registering process-local authority. */
+export function snapshotShareAccessPlan(input: ShareAccessPlan): ShareAccessPlan {
+  const captured = captureAccessPlanGrants(input)
+  const selection = validateMergedViewSelection(captured.viewRoots)
+  return assembleAccessPlanSnapshot(captured.grants, selection)
+}
+
+function captureAccessPlanGrants(input: ShareAccessPlan): {
+  readonly grants: readonly CapturedGrant[]
+  readonly viewRoots: readonly ObjectReadRoot[]
+} {
+  if (!isRecord(input)) {
+    throw new Error("[Sixb] Share access plan must contain scoped grants.")
+  }
+  const authoredGrants = input.grants
+  if (!Array.isArray(authoredGrants)) {
+    throw new Error("[Sixb] Share access plan must contain scoped grants.")
+  }
+  const grantCount = authoredGrants.length
+  if (grantCount > MAX_SCOPED_GRANTS) {
+    throw new Error(
+      `[Sixb] Share access plan exceeds the maximum of ${MAX_SCOPED_GRANTS} scoped grants.`
+    )
+  }
+
+  // Share budgets across grants and capture caller-controlled fields exactly once.
+  const budget: ActionCaptureBudget = { subjectCount: 0, identifierCharacters: 0 }
+  const viewRoots: ObjectReadRoot[] = []
+  const grants: CapturedGrant[] = []
+  for (let index = 0; index < grantCount; index += 1) {
+    const grant = authoredGrants[index]
+    if (!isRecord(grant)) {
+      throw new Error(`[Sixb] Scoped grant ${index} must be an object.`)
+    }
+    const kind = grant.kind
+    switch (kind) {
+      case "object.view":
+        grants.push(captureViewGrant(grant, index, viewRoots))
+        break
+      case "action.apply":
+        grants.push(captureActionGrant(grant, index, budget))
+        break
+      default:
+        throw new Error(`[Sixb] Unknown scoped grant kind '${String(kind)}'.`)
+    }
+  }
+  return { grants, viewRoots }
+}
+
+function captureViewGrant(
+  grant: Record<string, unknown>,
+  index: number,
+  viewRoots: ObjectReadRoot[]
+): CapturedViewGrant {
+  const selection = grant.selection
+  if (!isRecord(selection)) {
+    throw new Error(`[Sixb] Scoped grant ${index} requires a selected object read scope.`)
+  }
+  const selectionKind = selection.kind
+  const roots = selection.roots
+  if (selectionKind !== "selected" || !Array.isArray(roots)) {
+    throw new Error(`[Sixb] Scoped grant ${index} requires a selected object read scope.`)
+  }
+  const rootCount = roots.length
+  if (rootCount > MAX_SCOPED_VIEW_ROOTS_BEFORE_COMPILATION - viewRoots.length) {
+    throw new Error(
+      `[Sixb] Share access plan exceeds the maximum of ${MAX_SCOPED_VIEW_ROOTS_BEFORE_COMPILATION} raw scoped view roots.`
+    )
+  }
+  const rootStart = viewRoots.length
+  for (let rootIndex = 0; rootIndex < rootCount; rootIndex += 1) {
+    viewRoots.push(roots[rootIndex] as ObjectReadRoot)
+  }
+  return { kind: "object.view", rootStart, rootCount }
+}
+
+function captureActionGrant(
+  grant: Record<string, unknown>,
+  index: number,
+  budget: ActionCaptureBudget
+): ShareScopedActionGrant {
+  const authoredActionId = grant.actionId
+  const authoredSubjects = grant.subjects
+  const actionId = nonEmpty(authoredActionId, `Scoped grant ${index} action id`)
+  addActionIdentifierCharacters(budget, actionId.length)
+  if (!Array.isArray(authoredSubjects)) {
+    throw new Error(`[Sixb] Scoped grant ${index} action subjects must be an array.`)
+  }
+  const subjectCount = authoredSubjects.length
+  budget.subjectCount += subjectCount
+  if (budget.subjectCount > MAX_SCOPED_ACTION_SUBJECTS) {
+    throw new Error(
+      `[Sixb] Share access plan exceeds the maximum of ${MAX_SCOPED_ACTION_SUBJECTS} scoped action subjects.`
+    )
+  }
+  const subjects: ObjectRef[] = []
+  for (let subjectIndex = 0; subjectIndex < subjectCount; subjectIndex += 1) {
+    const subject = captureActionSubject(authoredSubjects[subjectIndex], index, subjectIndex)
+    addActionIdentifierCharacters(budget, subject.objectTypeId.length + subject.primaryId.length)
+    subjects.push(subject)
+  }
+  return Object.freeze({ kind: "action.apply", actionId, subjects: Object.freeze(subjects) })
+}
+
+function captureActionSubject(
+  subject: unknown,
+  grantIndex: number,
+  subjectIndex: number
+): ObjectRef {
+  if (!isRecord(subject)) {
+    throw new Error(`[Sixb] Scoped grant ${grantIndex} subject ${subjectIndex} must be an object.`)
+  }
+  const authoredObjectTypeId = subject.objectTypeId
+  const authoredPrimaryId = subject.primaryId
+  const objectTypeId = nonEmpty(
+    authoredObjectTypeId,
+    `Scoped grant ${grantIndex} subject ${subjectIndex} object type id`
+  )
+  const primaryId = nonEmpty(
+    authoredPrimaryId,
+    `Scoped grant ${grantIndex} subject ${subjectIndex} primary id`
+  )
+  return Object.freeze({ objectTypeId, primaryId })
+}
+
+function addActionIdentifierCharacters(budget: ActionCaptureBudget, count: number): void {
+  budget.identifierCharacters += count
+  if (budget.identifierCharacters > MAX_SCOPED_ACTION_IDENTIFIER_CHARACTERS) {
+    throw new Error(
+      `[Sixb] Share access plan exceeds the maximum of ${MAX_SCOPED_ACTION_IDENTIFIER_CHARACTERS} scoped action identifier characters.`
+    )
+  }
+}
+
+function validateMergedViewSelection(roots: readonly ObjectReadRoot[]): SelectedObjectReadScope {
+  // Snapshot all roots together so the provider's limits apply globally across view grants.
+  const selection = captureSelectedObjectReadScope({ kind: "selected", roots })
+  // Compile the exact immutable snapshot, without rereading caller-controlled data.
+  compileSelectedObjectReadScope(selection)
+  return selection
+}
+
+function assembleAccessPlanSnapshot(
+  capturedGrants: readonly CapturedGrant[],
+  selection: SelectedObjectReadScope
+): ShareAccessPlan {
+  const grants = capturedGrants.map((grant): ShareScopedGrant => {
+    if (grant.kind === "action.apply") return grant
+    const roots = Object.freeze(
+      selection.roots.slice(grant.rootStart, grant.rootStart + grant.rootCount)
+    )
+    return Object.freeze({
+      kind: "object.view",
+      selection: Object.freeze({ kind: "selected", roots }),
+    })
+  })
+  return Object.freeze({ grants: Object.freeze(grants) })
+}
+
+/** Merge view grants only; capability/resource pairing remains intact for every other grant. */
+export function objectReadScopeForAccessPlan(plan: ShareAccessPlan): SelectedObjectReadScope {
+  return Object.freeze({
+    kind: "selected",
+    roots: Object.freeze(
+      plan.grants.flatMap((grant) =>
+        grant.kind === "object.view" ? [...grant.selection.roots] : []
+      )
+    ),
+  })
+}
+
+function nonEmpty(value: unknown, label: string): string {
+  if (typeof value !== "string" || !value.trim()) {
+    throw new Error(`[Sixb] ${label} must not be empty.`)
+  }
+  return value
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null
+}