@sixb/core 0.1.7 → 0.1.8

package/src/storage/objects/types.ts

@@ -6,6 +6,7 @@ import type {
   ObjectQuerySortField,
   QueryScalarKind,
 } from "../../objects/query"
+import type { ObjectReadExecutionLimits } from "./execution-limits"
 import type { LinkBatchKey, ObjectBatchKey } from "./keys"
 
 /**
@@ -85,6 +86,78 @@ export interface QueryObjectLinksResult {
   hasMore: boolean
 }
 
+/**
+ * A finite, provider-neutral selection rooted at exact object identities.
+ *
+ * Object and link instances are resolved live by the provider for every operation. The selection
+ * describes only which paths and properties may become visible.
+ */
+export interface SelectedObjectReadScope {
+  readonly kind: "selected"
+  readonly roots: readonly ObjectReadRoot[]
+}
+
+export interface ObjectReadRoot {
+  readonly anchor: {
+    readonly objectTypeId: string
+    readonly primaryId: string
+  }
+  readonly node: ObjectReadNode
+}
+
+export interface ObjectReadNode {
+  /** Visible properties for every concrete object type selected at this path occurrence. */
+  readonly objects: readonly ObjectReadObjectSelection[]
+  readonly links: readonly ObjectReadLinkSelection[]
+}
+
+export interface ObjectReadObjectSelection {
+  readonly objectTypeId: string
+  readonly propertyIds: readonly string[]
+}
+
+export interface ObjectReadLinkSelection {
+  /** Physical ontology link definitions allowed from this exact path occurrence. */
+  readonly definitions: readonly ObjectReadLinkDefinitionSelection[]
+  readonly target: ObjectReadNode
+}
+
+export interface ObjectReadLinkDefinitionSelection {
+  readonly sourceObjectTypeId: string
+  readonly linkId: string
+  readonly targetObjectTypeIds: readonly string[]
+  readonly propertyIds: readonly string[]
+}
+
+/** Detached and deeply immutable selection consumed by storage providers. */
+export interface CompiledSelectedObjectReadScope {
+  readonly kind: "selected"
+  readonly roots: readonly CompiledObjectReadRoot[]
+  readonly objects: readonly CompiledObjectReadObjectSelection[]
+  readonly steps: readonly CompiledObjectReadStep[]
+}
+
+export interface CompiledObjectReadRoot {
+  /** Id of this root's path occurrence. */
+  readonly nodeId: number
+  readonly objectTypeId: string
+  readonly primaryId: string
+}
+
+export interface CompiledObjectReadObjectSelection extends ObjectReadObjectSelection {
+  readonly nodeId: number
+}
+
+export interface CompiledObjectReadStep {
+  /** Id of the target path occurrence reached by this step. */
+  readonly nodeId: number
+  readonly parentNodeId: number
+  readonly sourceObjectTypeId: string
+  readonly linkId: string
+  readonly targetObjectTypeId: string
+  readonly propertyIds: readonly string[]
+}
+
 export type ObjectQueryCapabilityMap<T extends string> = Readonly<Partial<Record<T, boolean>>>
 
 export type ObjectQueryScalarOperation = "equality" | "ordering"
@@ -189,7 +262,8 @@ export interface FacetObjectsResult {
   facets: readonly ObjectFacetResult[]
 }
 
-export interface ObjectStorage {
+/** Provider-facing read-only surface for effective objects and links. */
+export interface ObjectReadStorage {
   queryCapabilities(): ObjectQueryCapabilities
 
   queryObjects?(params: QueryObjectsInput): Promise<QueryObjectsResult>
@@ -203,6 +277,22 @@ export interface ObjectStorage {
     primaryId: string
   }): Promise<ObjectRow | null>
 
+  /**
+   * Check whether each requested property belongs to the reader's selection.
+   *
+   * Results align exactly with `items`, including duplicates. Selection is independent from the
+   * property's current materialized value: an unrestricted reader selects every property of an
+   * existing object even when that property has no stored value.
+   */
+  selectsObjectProperties(params: {
+    projectId: string
+    items: readonly {
+      objectTypeId: string
+      primaryId: string
+      propertyId: string
+    }[]
+  }): Promise<readonly boolean[]>
+
   listLinks(params: {
     projectId: string
     objectTypeId: string
@@ -221,11 +311,13 @@ export interface ObjectStorage {
   }): Promise<ReadonlyMap<ObjectBatchKey, ObjectRow>>
 
   /**
-   * Batch fetch outgoing links by (objectTypeId, objectId, linkId) tuples.
+   * Batch fetch links by (objectTypeId, objectId, linkId) tuples in the requested direction.
+   * Direction defaults to outgoing.
    * Returns a Map keyed by {@link linkBatchKey}. Missing entries are absent.
    */
   listLinksBatch(params: {
     projectId: string
+    direction?: LinkDirection
     items: readonly { objectTypeId: string; objectId: string; linkId: string }[]
   }): Promise<ReadonlyMap<LinkBatchKey, ObjectLinkRow[]>>
 
@@ -236,11 +328,38 @@ export interface ObjectStorage {
    */
   queryLinks(params: QueryObjectLinksInput): Promise<QueryObjectLinksResult>
 
+  list(params: {
+    projectId: string
+    objectTypeId?: string | readonly string[]
+    primaryIdPrefix?: string
+    primaryIdSuffix?: string
+    updatedAfter?: Date
+    updatedBefore?: Date
+    createdAfter?: Date
+    createdBefore?: Date
+    limit?: number
+    offset?: number
+    orderBy?: "createdAt" | "updatedAt" | "primaryId"
+    order?: "asc" | "desc"
+  }): Promise<{ objects: readonly ObjectRow[]; hasMore: boolean; total: number }>
+}
+
+/** Provider capability for enforcing a finite, precompiled object-read selection. */
+export interface ObjectReadScopeFactory {
+  createSelectedReadScope(params: {
+    projectId: string
+    scope: CompiledSelectedObjectReadScope
+    limits: ObjectReadExecutionLimits
+  }): ObjectReadStorage
+}
+
+/** Latest-state projection storage, including selected reads and trusted internal primitives. */
+export interface ObjectStorage extends ObjectReadStorage, ObjectReadScopeFactory {
   /**
    * Batch fetch every link incident to any of the given objects, in BOTH directions (the object as
    * link source or target). Returns a flat, de-duplicated list: a physical link incident to two
-   * listed objects appears once. This unpaged primitive exists for internal materialization and
-   * per-parent expansion work; interactive reads use {@link queryLinks}.
+   * listed objects appears once. This unpaged primitive is reserved for trusted internal work and
+   * deliberately absent from {@link ObjectReadStorage}; interactive reads use {@link queryLinks}.
    */
   listIncidentLinksBatch(params: {
     projectId: string
@@ -254,19 +373,4 @@ export interface ObjectStorage {
     afterPrimaryId?: string
     limit: number
   }): Promise<{ objects: readonly ObjectRow[]; nextPrimaryId?: string }>
-
-  list(params: {
-    projectId: string
-    objectTypeId?: string | readonly string[]
-    primaryIdPrefix?: string
-    primaryIdSuffix?: string
-    updatedAfter?: Date
-    updatedBefore?: Date
-    createdAfter?: Date
-    createdBefore?: Date
-    limit?: number
-    offset?: number
-    orderBy?: "createdAt" | "updatedAt" | "primaryId"
-    order?: "asc" | "desc"
-  }): Promise<{ objects: readonly ObjectRow[]; hasMore: boolean; total: number }>
 }

package/src/storage/operation-scope.ts

@@ -1,6 +1,8 @@
 import { AsyncLocalStorage } from "node:async_hooks"
 import type { AgentStorage } from "./agents"
 import type { AuthStorage } from "./auth"
+import type { ObjectStorage } from "./objects"
+import { createGuardedObjectReadStorage, requireObjectReadScopeFactory } from "./objects/guard"
 import type { OntologyStorage } from "./ontology"
 import type { WorkflowRunStorage } from "./workflow-runs"
 
@@ -231,6 +233,20 @@ export function createOntologyOperationScope<T extends OntologyStorage>(
   }) as T
 }
 
+/** Keep synchronously created selected readers inside the provider's root operation scope. */
+export function createObjectOperationScope<T extends ObjectStorage>(
+  target: T,
+  scope: StorageOperationScope
+): T {
+  const factory = requireObjectReadScopeFactory(target)
+  return createOperationScopedFacade<ObjectStorage>(target, scope, {
+    createSelectedReadScope: (params) => {
+      scope.assertAvailable()
+      return createGuardedObjectReadStorage(factory.createSelectedReadScope(params), scope)
+    },
+  }) as T
+}
+
 export function createWorkflowRunOperationScope<T extends WorkflowRunStorage>(
   target: T,
   scope: StorageOperationScope

package/src/storage/share-grants/errors.ts

@@ -0,0 +1,14 @@
+export type ShareGrantStorageErrorCode = "duplicate" | "invalid_input" | "invalid_record"
+
+/** Provider-level control signal; Core maps it to the public Share lifecycle error vocabulary. */
+export class ShareGrantStorageError extends Error {
+  readonly name = "ShareGrantStorageError"
+
+  constructor(
+    readonly code: ShareGrantStorageErrorCode,
+    message: string,
+    options?: ErrorOptions
+  ) {
+    super(message, options)
+  }
+}

package/src/storage/share-grants/in-memory.ts

@@ -0,0 +1,107 @@
+import { ShareGrantStorageError } from "./errors"
+import {
+  cloneShareGrantRecord,
+  normalizeGetShareGrantByIdInput,
+  normalizeListShareGrantsInput,
+  normalizeRevokeShareGrantInput,
+  normalizeShareGrantCreate,
+  parseShareGrantRecord,
+} from "./record"
+import type {
+  CreateShareGrantInput,
+  GetShareGrantByIdInput,
+  ListShareGrantsInput,
+  ListShareGrantsResult,
+  RevokeShareGrantInput,
+  ShareGrantRecord,
+  ShareGrantStorage,
+} from "./types"
+
+export class InMemoryShareGrantStorage implements ShareGrantStorage {
+  private rows = new Map<string, ShareGrantRecord>()
+
+  async create(input: CreateShareGrantInput): Promise<ShareGrantRecord> {
+    const record = normalizeShareGrantCreate(input)
+    const key = rowKey(record.projectId, record.id)
+    const duplicateTokenHash = [...this.rows.values()].some(
+      (current) => current.projectId === record.projectId && current.tokenHash === record.tokenHash
+    )
+    if (this.rows.has(key) || duplicateTokenHash) {
+      throw new ShareGrantStorageError(
+        "duplicate",
+        `[Sixb] Share grant '${record.id}' conflicts with an existing record.`
+      )
+    }
+
+    this.rows.set(key, record)
+    return cloneShareGrantRecord(record)
+  }
+
+  async getById(input: GetShareGrantByIdInput): Promise<ShareGrantRecord | null> {
+    const normalized = normalizeGetShareGrantByIdInput(input)
+    const record = this.rows.get(rowKey(normalized.projectId, normalized.id))
+    return record ? cloneShareGrantRecord(record) : null
+  }
+
+  async list(input: ListShareGrantsInput): Promise<ListShareGrantsResult> {
+    const normalized = normalizeListShareGrantsInput(input)
+    const matching = [...this.rows.values()]
+      .filter(
+        (record) =>
+          record.projectId === normalized.projectId &&
+          (normalized.definitionId === undefined ||
+            record.definitionId === normalized.definitionId) &&
+          (normalized.target === undefined ||
+            (record.target.objectTypeId === normalized.target.objectTypeId &&
+              record.target.primaryId === normalized.target.primaryId)) &&
+          (normalized.includeRevoked || record.revokedAt === undefined) &&
+          (normalized.includeExpired || record.expiresAt.getTime() > normalized.now.getTime())
+      )
+      .sort(compareShareGrants)
+
+    const total = matching.length
+    const grants = matching
+      .slice(normalized.offset, normalized.offset + normalized.limit)
+      .map(cloneShareGrantRecord)
+    return {
+      grants,
+      total,
+      hasMore: normalized.offset + grants.length < total,
+    }
+  }
+
+  async revoke(input: RevokeShareGrantInput): Promise<ShareGrantRecord | null> {
+    const normalized = normalizeRevokeShareGrantInput(input)
+    const key = rowKey(normalized.projectId, normalized.id)
+    const current = this.rows.get(key)
+    if (!current) return null
+    if (current.revokedAt) return cloneShareGrantRecord(current)
+
+    const revocation = normalizeRevokeShareGrantInput(normalized, current.createdAt)
+    const updated: ShareGrantRecord = {
+      ...current,
+      revokedAt: new Date(revocation.revokedAt),
+      revokedBy: { ...revocation.revokedBy },
+    }
+    this.rows.set(key, updated)
+    return cloneShareGrantRecord(updated)
+  }
+
+  snapshot(): ReadonlyMap<string, ShareGrantRecord> {
+    return new Map([...this.rows].map(([key, record]) => [key, cloneShareGrantRecord(record)]))
+  }
+
+  restore(snapshot: ReadonlyMap<string, ShareGrantRecord>): void {
+    this.rows = new Map([...snapshot].map(([key, record]) => [key, parseShareGrantRecord(record)]))
+  }
+}
+
+function compareShareGrants(left: ShareGrantRecord, right: ShareGrantRecord): number {
+  const created = right.createdAt.getTime() - left.createdAt.getTime()
+  if (created !== 0) return created
+  return left.id === right.id ? 0 : left.id < right.id ? 1 : -1
+}
+
+function rowKey(projectId: string, id: string): string {
+  return `${projectId}\0${id}`
+}

package/src/storage/share-grants/index.ts

@@ -0,0 +1,14 @@
+export type { ShareGrantStorageErrorCode } from "./errors"
+export { ShareGrantStorageError } from "./errors"
+export { InMemoryShareGrantStorage } from "./in-memory"
+export type {
+  CreateShareGrantInput,
+  GetShareGrantByIdInput,
+  ListShareGrantsInput,
+  ListShareGrantsResult,
+  RevokeShareGrantInput,
+  ShareAuthoritySnapshot,
+  ShareAuthoritySnapshotV1,
+  ShareGrantRecord,
+  ShareGrantStorage,
+} from "./types"

package/src/storage/share-grants/provider.ts

@@ -0,0 +1,11 @@
+/** @internal Repository storage-provider helpers; not part of the app-author API. */
+export {
+  cloneShareGrantRecord,
+  normalizeGetShareGrantByIdInput,
+  normalizeListShareGrantsInput,
+  normalizeRevokeShareGrantInput,
+  normalizeShareGrantCreate,
+  parseShareGrantRecord,
+  shareAuthorityDigest,
+} from "./record"
+export type { NormalizedListShareGrantsInput } from "./types"