@hiai-gg/docsmint 0.6.8 → 0.7.0

package/dist/storage-quota.d.ts

@@ -67,7 +67,11 @@ export type AttachmentStorageQuotaFinalization = Readonly<{
 }>;
 /**
  * OSS invokes this only after it has verified tenant context and document
- * access.  A host provider is never exposed to HTTP or browser code.
+ * access. A host provider is never exposed to HTTP or browser code. Every
+ * method MUST be idempotent for `context.idempotencyKey`: repeated reserve
+ * returns the same logical reservation, repeated finalize has one charge, and
+ * repeated release is a successful no-op after the first release. The OSS
+ * durable upload/cleanup saga relies on this contract at crash boundaries.
  */
 export type AttachmentStorageQuotaAdmission = Readonly<{
     reserve(context: AttachmentStorageQuotaContext): Promise<Readonly<{

package/dist/types.d.ts

@@ -304,6 +304,8 @@ export interface DocsAttachmentPresignInput {
 export interface DocsAttachmentPresignResponse {
     url: string;
     key: string;
+    /** Signed, exact admission identity required by confirmAttachment. */
+    uploadToken: string;
     /**
      * Opaque server-issued reservation. Present only when workspace storage
      * enforcement is enabled and required verbatim by confirmAttachment.
@@ -314,6 +316,7 @@ export interface DocsAttachmentPresignResponse {
 }
 export interface DocsAttachmentConfirmInput extends DocsAttachmentPresignInput {
     key: string;
+    uploadToken: string;
     /** The opaque reservation returned by presignAttachment when present. */
     quotaReservationId?: string;
 }
@@ -434,4 +437,8 @@ export interface DocsRequestContext {
     workspaceAssertion?: string;
     headers?: HeadersInit;
     signal?: AbortSignal;
+    /** Per-request timeout in milliseconds, overriding the client default. */
+    timeoutMs?: number;
+    /** Idempotency key forwarded as the standard Idempotency-Key header. */
+    idempotencyKey?: string;
 }

package/dist/workspace.d.ts

@@ -1,13 +1,22 @@
 /** Public, server-only workspace assertion contract. */
 export declare const DOCSMINT_WORKSPACE_CONTEXT_HEADER = "x-docsmint-workspace-context";
-export type DocsmintWorkspaceContext = Readonly<{
+export type WorkspaceRole = "owner" | "admin" | "editor" | "viewer";
+export type WorkspaceResourcePermission = "read" | "edit" | "write";
+export type WorkspaceResourceScope = Readonly<{
+    kind: "category";
+    categoryId: string;
+    permissions: readonly WorkspaceResourcePermission[];
+}>;
+export type WorkspaceAssertionPayload = Readonly<{
     actorUserId: string;
     workspaceId: string;
-    actorRole: "owner" | "admin" | "editor" | "viewer";
+    actorRole: WorkspaceRole;
+    resourceScope?: WorkspaceResourceScope;
     issuedAt: number;
     expiresAt: number;
     issuer: string;
 }>;
+export type DocsmintWorkspaceContext = WorkspaceAssertionPayload;
 export type WorkspaceAssertionOptions = Readonly<{
     secret: string;
     issuer: string;

package/dist/workspace.js

@@ -4,6 +4,22 @@ const encoder = new TextEncoder();
 const decoder = new TextDecoder();
 export const DOCSMINT_WORKSPACE_ASSERTION_TTL_SECONDS = 60;
 export const DOCSMINT_WORKSPACE_ASSERTION_CLOCK_SKEW_SECONDS = 5;
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const CONTEXT_FIELDS = new Set([
+    "actorUserId",
+    "workspaceId",
+    "actorRole",
+    "resourceScope",
+    "issuedAt",
+    "expiresAt",
+    "issuer",
+]);
+const RESOURCE_SCOPE_FIELDS = new Set(["kind", "categoryId", "permissions"]);
+const RESOURCE_PERMISSIONS = new Set([
+    "read",
+    "edit",
+    "write",
+]);
 function toBase64Url(bytes) {
     let binary = "";
     for (const byte of bytes)
@@ -26,11 +42,14 @@ async function sign(payload, secret) {
     return toBase64Url(new Uint8Array(await crypto.subtle.sign("HMAC", key, encoder.encode(payload))));
 }
 function assertContext(value) {
-    if (!value || typeof value !== "object")
+    if (!value || typeof value !== "object" || Array.isArray(value))
         throw new Error("Invalid workspace assertion payload");
     const context = value;
+    if (Object.keys(context).some((field) => !CONTEXT_FIELDS.has(field))) {
+        throw new Error("Invalid workspace assertion payload fields");
+    }
     if (typeof context.actorUserId !== "string" ||
-        !/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(context.actorUserId))
+        !UUID_PATTERN.test(context.actorUserId))
         throw new Error("Invalid actorUserId");
     if (typeof context.workspaceId !== "string" ||
         !context.workspaceId.trim() ||
@@ -39,15 +58,69 @@ function assertContext(value) {
         throw new Error("Invalid workspaceId");
     if (!["owner", "admin", "editor", "viewer"].includes(context.actorRole))
         throw new Error("Invalid actorRole");
+    if (context.resourceScope !== undefined) {
+        assertResourceScope(context.resourceScope);
+    }
     if (!Number.isFinite(context.issuedAt) ||
         !Number.isFinite(context.expiresAt) ||
         typeof context.issuer !== "string" ||
         !context.issuer)
         throw new Error("Invalid workspace assertion timestamps or issuer");
 }
+function assertResourceScope(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("Invalid workspace resource scope");
+    }
+    const scope = value;
+    const fields = Object.keys(scope);
+    if (fields.length !== RESOURCE_SCOPE_FIELDS.size ||
+        fields.some((field) => !RESOURCE_SCOPE_FIELDS.has(field))) {
+        throw new Error("Invalid workspace resource scope fields");
+    }
+    if (scope.kind !== "category") {
+        throw new Error("Invalid workspace resource scope kind");
+    }
+    if (typeof scope.categoryId !== "string" ||
+        !UUID_PATTERN.test(scope.categoryId)) {
+        throw new Error("Invalid workspace resource categoryId");
+    }
+    if (!Array.isArray(scope.permissions) ||
+        Array.from(scope.permissions).some((permission) => typeof permission !== "string" ||
+            !RESOURCE_PERMISSIONS.has(permission))) {
+        throw new Error("Invalid workspace resource permissions");
+    }
+}
+function assertStaticLifetime(context) {
+    if (context.expiresAt <= context.issuedAt) {
+        throw new Error("Invalid workspace assertion lifetime");
+    }
+    if (context.expiresAt - context.issuedAt >
+        DOCSMINT_WORKSPACE_ASSERTION_TTL_SECONDS) {
+        throw new Error("Workspace assertion lifetime exceeds maximum TTL");
+    }
+}
+function immutableContext(context) {
+    const resourceScope = context.resourceScope
+        ? Object.freeze({
+            kind: context.resourceScope.kind,
+            categoryId: context.resourceScope.categoryId,
+            permissions: Object.freeze([...context.resourceScope.permissions]),
+        })
+        : undefined;
+    return Object.freeze({
+        actorUserId: context.actorUserId,
+        workspaceId: context.workspaceId,
+        actorRole: context.actorRole,
+        ...(resourceScope ? { resourceScope } : {}),
+        issuedAt: context.issuedAt,
+        expiresAt: context.expiresAt,
+        issuer: context.issuer,
+    });
+}
 export async function createDocsmintWorkspaceAssertion(context, secret) {
     assertContext(context);
-    const payload = toBase64Url(encoder.encode(JSON.stringify(context)));
+    assertStaticLifetime(context);
+    const payload = toBase64Url(encoder.encode(JSON.stringify(immutableContext(context))));
     return `${payload}.${await sign(payload, secret)}`;
 }
 export async function verifyDocsmintWorkspaceAssertion(assertion, options) {
@@ -66,6 +139,7 @@ export async function verifyDocsmintWorkspaceAssertion(assertion, options) {
         throw new Error("Invalid workspace assertion payload");
     }
     assertContext(context);
+    assertStaticLifetime(context);
     if (context.issuer !== options.issuer)
         throw new Error("Invalid workspace assertion issuer");
     const now = options.nowSeconds ?? Math.floor(Date.now() / 1000);
@@ -75,11 +149,9 @@ export async function verifyDocsmintWorkspaceAssertion(assertion, options) {
         skew > DOCSMINT_WORKSPACE_ASSERTION_CLOCK_SKEW_SECONDS) {
         throw new Error("Invalid workspace assertion clock skew");
     }
-    if (context.issuedAt > now + skew ||
-        context.expiresAt <= now - skew ||
-        context.expiresAt <= context.issuedAt ||
-        context.expiresAt - context.issuedAt >
-            DOCSMINT_WORKSPACE_ASSERTION_TTL_SECONDS)
-        throw new Error("Invalid workspace assertion lifetime");
-    return Object.freeze({ ...context });
+    if (context.issuedAt > now + skew)
+        throw new Error("Workspace assertion is not yet valid");
+    if (context.expiresAt <= now - skew)
+        throw new Error("Workspace assertion is expired");
+    return immutableContext(context);
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@hiai-gg/docsmint",
   "mcpName": "io.github.HiAi-gg/docsmint",
-  "version": "0.6.8",
+  "version": "0.7.0",
   "type": "module",
   "browser": {
     "./dist/backend-launcher.js": false,
@@ -59,8 +59,8 @@
       "types": "./dist/index.d.ts"
     },
     "./mcp": {
-      "import": "./packages/mcp-server/src/server.ts",
-      "types": "./packages/mcp-server/src/server.ts"
+      "import": "./dist/mcp-server.js",
+      "types": "./dist/mcp-server.d.ts"
     },
     "./lifecycle": {
       "browser": "./dist/server-only-browser-entry.js",
@@ -339,9 +339,9 @@
   },
   "bin": {
     "docsmint": "./packages/cli/src/index.ts",
-    "docsmint-mcp": "./packages/mcp-server/src/index.ts",
+    "docsmint-mcp": "./dist/mcp-cli.js",
     "hiai-docs": "./packages/cli/src/index.ts",
-    "hiai-docs-mcp": "./packages/mcp-server/src/index.ts"
+    "hiai-docs-mcp": "./dist/mcp-cli.js"
   },
   "files": [
     "dist",
@@ -353,12 +353,6 @@
     "packages/cli/src/config.ts",
     "packages/cli/src/format.ts",
     "packages/cli/src/commands",
-    "packages/mcp-server/src/client.ts",
-    "packages/mcp-server/src/index.ts",
-    "packages/mcp-server/src/server.ts",
-    "packages/mcp-server/src/capabilities.ts",
-    "packages/mcp-server/src/types.ts",
-    "packages/mcp-server/src/tools",
     "skills",
     "backend/src/lib/redis-factory.ts",
     "backend/src/lib/storage-factory.ts",
@@ -397,7 +391,7 @@
     "postgres": "^3.4.9",
     "@aws-sdk/client-s3": "^3.0.0",
     "pino": "^10.0.0",
-    "@sveltejs/kit": "^2.68.0",
+    "@sveltejs/kit": "^2.70.3",
     "svelte": "^5.56.4"
   },
   "peerDependenciesMeta": {
@@ -414,4 +408,4 @@
       "optional": true
     }
   }
-}
+}

package/packages/cli/src/index.ts

@@ -24,7 +24,7 @@ import { registerSearch } from './commands/search.js';
 import { registerSnapshot } from './commands/snapshot.js';
 import { registerUpdate } from './commands/update.js';
 
-const VERSION = '0.6.8';
+const VERSION = '0.7.0';
 
 const program = new Command();
 program.name('hiai-docs').description('CLI for the hiai-docs knowledge base').version(VERSION);

package/packages/db/src/client.ts

@@ -5,16 +5,67 @@ import postgres from "postgres";
 export type Schema = typeof schema;
 export type Database = PostgresJsDatabase<Schema>;
 
+export type DatabaseQueryObservation = Readonly<{
+  query: string;
+}>;
+
+export type DatabaseQueryObserver = (
+  observation: DatabaseQueryObservation,
+) => void;
+
+function observeDatabaseQuery(
+  observer: DatabaseQueryObserver | undefined,
+  query: string,
+): void {
+  if (!observer) return;
+  try {
+    observer(Object.freeze({ query }));
+  } catch {
+    // Query observation is diagnostic only. Observer bugs must never affect the
+    // database protocol, application result, or error surface.
+  }
+}
+
+export type DatabaseClientOptions = Readonly<{
+  max?: number;
+  idleTimeout?: number;
+  connectTimeout?: number;
+  /** Explicit client-local test hook. Omitted clients install no debug callback. */
+  queryObserver?: DatabaseQueryObserver;
+}>;
+
+export function createDatabaseClient(
+  databaseUrl: string,
+  options: DatabaseClientOptions = {},
+) {
+  const sqlClient = postgres(databaseUrl, {
+    max: options.max ?? 20,
+    idle_timeout: options.idleTimeout ?? 30,
+    connect_timeout: options.connectTimeout ?? 10,
+    ...(options.queryObserver
+      ? {
+          debug: (_connection: number, query: string) => {
+            observeDatabaseQuery(options.queryObserver, query);
+          },
+        }
+      : {}),
+  });
+  return {
+    client: sqlClient,
+    db: drizzle(sqlClient, { schema }) as Database,
+  };
+}
+
 const databaseUrl =
   process.env.DATABASE_URL ||
   "postgresql://hiai_app:changeme@localhost:5437/hiai_docs";
 
-const client = postgres(databaseUrl, {
-  max: 20,
-  idle_timeout: 30,
-  connect_timeout: 10,
+const database = createDatabaseClient(databaseUrl, {
+  // Production deliberately owns no query observer. Contract tests create an
+  // explicit client-local observer and close that client after each capture.
 });
 
-export const db: Database = drizzle(client, { schema });
+const client = database.client;
+export const db: Database = database.db;
 
 export { client };

package/packages/db/src/schema.ts

@@ -1,4 +1,4 @@
-import { pgTable, uuid, text, timestamp, bigint, jsonb, index, uniqueIndex, customType, boolean, check, integer, pgEnum, type AnyPgColumn } from "drizzle-orm/pg-core";
+import { pgTable, uuid, text, timestamp, bigint, jsonb, index, uniqueIndex, customType, boolean, check, integer, pgEnum, primaryKey, type AnyPgColumn } from "drizzle-orm/pg-core";
 
 // pgvector vector type — maps to PostgreSQL vector(n) column
 const vector = customType<{
@@ -226,6 +226,7 @@ export const documents = pgTable(
     activeEmbeddingGeneration: uuid("active_embedding_generation"),
     pendingEmbeddingGeneration: uuid("pending_embedding_generation"),
     embeddingProfile: text("embedding_profile"),
+    embeddingContextHash: text("embedding_context_hash"),
     embeddingErrorCode: text("embedding_error_code"),
     embeddingUpdatedAt: timestamp("embedding_updated_at"),
     /** Soft-delete marker. Trashed documents remain tenant-scoped until purge. */
@@ -281,6 +282,8 @@ export const documentPipelineRuns = pgTable(
     generationId: uuid("generation_id").notNull(),
     revision: text("revision").notNull(),
     source: text("source").notNull(),
+    embeddingContextHash: text("embedding_context_hash"),
+    refreshMode: text("refresh_mode").notNull().default("full"),
     status: pipelineStatusEnum("status").notNull().default("pending"),
     prepareStatus: pipelineStatusEnum("prepare_status").notNull().default("pending"),
     embedStatus: pipelineStatusEnum("embed_status").notNull().default("pending"),
@@ -310,6 +313,10 @@ export const documentPipelineRuns = pgTable(
       table.status,
       table.updatedAt,
     ),
+    check(
+      "document_pipeline_runs_refresh_mode_check",
+      sql`${table.refreshMode} in ('incremental', 'full')`,
+    ),
   ],
 );
 
@@ -354,6 +361,41 @@ export const documentPipelineBatches = pgTable(
   ],
 );
 
+// ============================================
+// metadata_reembed_outbox -- exact metadata-impact snapshots
+// ============================================
+export const metadataReembedOutbox = pgTable(
+  "metadata_reembed_outbox",
+  {
+    // The outbox row id is also the deterministic pipeline generation id.
+    id: uuid("id").primaryKey(),
+    operationId: uuid("operation_id").notNull(),
+    documentId: uuid("document_id")
+      .notNull()
+      .references(() => documents.id, { onDelete: "cascade" }),
+    ownerId: uuid("owner_id")
+      .notNull()
+      .references(() => users.id, { onDelete: "cascade" }),
+    workspaceId: text("workspace_id"),
+    revision: text("revision").notNull(),
+    createdAt: timestamp("created_at").defaultNow().notNull(),
+  },
+  (table) => [
+    uniqueIndex("metadata_reembed_outbox_operation_document_idx").on(
+      table.operationId,
+      table.documentId,
+    ),
+    index("metadata_reembed_outbox_operation_id_idx").on(
+      table.operationId,
+      table.id,
+    ),
+    index("metadata_reembed_outbox_created_id_idx").on(
+      table.createdAt,
+      table.id,
+    ),
+  ],
+);
+
 // ============================================
 // document_knowledge_summaries — generation-scoped retrieval metadata
 // ============================================
@@ -575,6 +617,9 @@ export const attachments = pgTable(
       .notNull()
       .references(() => documents.id, { onDelete: "cascade" }),
     workspaceId: text("workspace_id"),
+    uploadedBy: uuid("uploaded_by")
+      .notNull()
+      .references(() => users.id, { onDelete: "restrict" }),
     filename: text("filename").notNull(),
     mimeType: text("mime_type").notNull(),
     size: bigint("size", { mode: "number" }).notNull(),
@@ -583,10 +628,156 @@ export const attachments = pgTable(
   },
   (table) => [
     index("attachments_document_id_idx").on(table.documentId),
+    index("attachments_uploaded_by_idx").on(table.uploadedBy),
     uniqueIndex("attachments_storage_key_unique").on(table.storageKey),
   ]
 );
 
+// A direct upload URL can outlive the request that created it. Keeping the
+// exact actor/key/expiry admission durable lets confirmation authenticate the
+// key after session/document disappearance and lets account purge wait through
+// the unrevocable URL lifetime before deleting the exact object.
+export const pendingAttachmentUploads = pgTable(
+  "pending_attachment_uploads",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    documentId: uuid("document_id")
+      .notNull()
+      .references(() => documents.id, { onDelete: "restrict" }),
+    actorUserId: uuid("actor_user_id")
+      .notNull()
+      .references(() => users.id, { onDelete: "restrict" }),
+    workspaceId: text("workspace_id"),
+    storageKey: text("storage_key").notNull(),
+    tokenHash: text("token_hash").notNull(),
+    filename: text("filename").notNull(),
+    mimeType: text("mime_type").notNull(),
+    declaredSize: bigint("declared_size", { mode: "number" }).notNull(),
+    quotaReservationId: text("quota_reservation_id"),
+    quotaOperationKey: text("quota_operation_key").notNull(),
+    quotaState: text("quota_state").notNull(),
+    actualSize: bigint("actual_size", { mode: "number" }),
+    urlIssuedAt: timestamp("url_issued_at"),
+    confirmingAt: timestamp("confirming_at"),
+    leaseOwner: text("lease_owner"),
+    leaseExpiresAt: timestamp("lease_expires_at"),
+    attemptCount: integer("attempt_count").default(0).notNull(),
+    lastError: text("last_error"),
+    expiresAt: timestamp("expires_at").notNull(),
+    createdAt: timestamp("created_at").defaultNow().notNull(),
+  },
+  (table) => [
+    uniqueIndex("pending_attachment_uploads_storage_key_unique").on(table.storageKey),
+    uniqueIndex("pending_attachment_uploads_token_hash_unique").on(table.tokenHash),
+    index("pending_attachment_uploads_actor_expiry_idx").on(
+      table.actorUserId,
+      table.expiresAt,
+    ),
+    index("pending_attachment_uploads_document_idx").on(table.documentId),
+    index("pending_attachment_uploads_cleanup_lease_idx").on(
+      table.expiresAt,
+      table.leaseExpiresAt,
+      table.id,
+    ),
+    check(
+      "pending_attachment_uploads_quota_state_check",
+      sql`${table.quotaState} IN ('not_required', 'reserve_pending', 'reserved', 'finalize_pending', 'committed')`,
+    ),
+  ],
+);
+
+// DB-authoritative intents for object removal and quota release. Source rows
+// are deleted in the same transaction that inserts an intent; S3 and quota
+// effects happen only after commit and remain recoverable across crashes.
+export const attachmentStorageCleanupOutbox = pgTable(
+  "attachment_storage_cleanup_outbox",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    sourceKind: text("source_kind").notNull(),
+    sourceId: uuid("source_id").notNull(),
+    storageKey: text("storage_key").notNull(),
+    documentId: uuid("document_id").notNull(),
+    actorUserId: uuid("actor_user_id").notNull(),
+    ownerUserId: uuid("owner_user_id").notNull(),
+    requestedByUserId: uuid("requested_by_user_id").notNull(),
+    workspaceId: text("workspace_id"),
+    size: bigint("size", { mode: "number" }).notNull(),
+    quotaOperationKey: text("quota_operation_key").notNull(),
+    quotaReleaseKind: text("quota_release_kind").default("none").notNull(),
+    quotaReservationId: text("quota_reservation_id"),
+    notBefore: timestamp("not_before").defaultNow().notNull(),
+    retainUntil: timestamp("retain_until"),
+    objectDeletedAt: timestamp("object_deleted_at"),
+    leaseOwner: text("lease_owner"),
+    leaseExpiresAt: timestamp("lease_expires_at"),
+    attemptCount: integer("attempt_count").default(0).notNull(),
+    lastError: text("last_error"),
+    createdAt: timestamp("created_at").defaultNow().notNull(),
+  },
+  (table) => [
+    uniqueIndex("attachment_storage_cleanup_outbox_source_unique").on(
+      table.sourceKind,
+      table.sourceId,
+    ),
+    uniqueIndex("attachment_storage_cleanup_outbox_storage_key_unique").on(
+      table.storageKey,
+    ),
+    index("attachment_storage_cleanup_outbox_ready_idx").on(
+      table.notBefore,
+      table.leaseExpiresAt,
+      table.createdAt,
+      table.id,
+    ),
+    index("attachment_storage_cleanup_outbox_actor_idx").on(
+      table.actorUserId,
+      table.id,
+    ),
+    index("attachment_storage_cleanup_outbox_owner_idx").on(
+      table.ownerUserId,
+      table.id,
+    ),
+    index("attachment_storage_cleanup_outbox_requester_idx").on(
+      table.requestedByUserId,
+      table.id,
+    ),
+    check(
+      "attachment_storage_cleanup_outbox_source_kind_check",
+      sql`${table.sourceKind} IN ('attachment', 'pending_upload', 'uncommitted_upload')`,
+    ),
+    check(
+      "attachment_storage_cleanup_outbox_quota_kind_check",
+      sql`${table.quotaReleaseKind} IN ('none', 'reserve_pending', 'reservation', 'finalize_pending', 'committed')`,
+    ),
+    check("attachment_storage_cleanup_outbox_size_check", sql`${table.size} >= 0`),
+    check(
+      "attachment_storage_cleanup_outbox_reservation_check",
+      sql`${table.quotaReleaseKind} NOT IN ('reservation', 'finalize_pending') OR ${table.quotaReservationId} IS NOT NULL`,
+    ),
+  ],
+);
+
+// Internal transaction-bound proof used only by the narrow signed-admission
+// abandonment SECURITY DEFINER function. The runtime role has no table grants.
+export const pendingAttachmentCleanupAuthorizations = pgTable(
+  "pending_attachment_cleanup_authorizations",
+  {
+    backendPid: integer("backend_pid").notNull(),
+    transactionId: bigint("transaction_id", { mode: "bigint" }).notNull(),
+    admissionId: uuid("admission_id").notNull(),
+    documentId: uuid("document_id").notNull(),
+    actorUserId: uuid("actor_user_id").notNull(),
+    ownerUserId: uuid("owner_user_id").notNull(),
+    workspaceId: text("workspace_id"),
+    storageKey: text("storage_key").notNull(),
+    tokenHash: text("token_hash").notNull(),
+  },
+  (table) => [
+    primaryKey({
+      columns: [table.backendPid, table.transactionId, table.admissionId],
+    }),
+  ],
+);
+
 export const attachmentRelations = relations(attachments, ({ one }) => ({
   document: one(documents, {
     fields: [attachments.documentId],

package/packages/db/src/with-tenant.ts

@@ -1,5 +1,12 @@
 import { sql } from "drizzle-orm";
-import { db, type Database } from "./client";
+import { type Database, db } from "./client";
+
+export type WorkspaceResourcePermission = "read" | "edit" | "write";
+export type WorkspaceResourceScope = Readonly<{
+	kind: "category";
+	categoryId: string;
+	permissions: readonly WorkspaceResourcePermission[];
+}>;
 
 /** A transaction carrying the same query surface as the tenant-scoped DB. */
 export type TenantTransaction = Parameters<
@@ -44,6 +51,8 @@ export interface TenantContext {
 	workspaceId?: string;
 	source?: "personal" | "external";
 	actorRole?: "owner" | "admin" | "editor" | "viewer";
+	/** Resource restriction copied from a verified external assertion. */
+	resourceScope?: WorkspaceResourceScope;
 	/** Unix timestamp from a verified external workspace assertion. */
 	assertionExpiresAt?: number;
 }
@@ -99,7 +108,16 @@ export async function withTenant<T>(
 	ctx: TenantContext,
 	fn: (tx: Parameters<Parameters<typeof db.transaction>[0]>[0]) => Promise<T>,
 ): Promise<T> {
-	return db.transaction(async (tx) => {
+	return withTenantDatabase(db, ctx, fn);
+}
+
+/** Execute the canonical tenant transaction against an explicitly owned client. */
+export async function withTenantDatabase<T>(
+	database: Database,
+	ctx: TenantContext,
+	fn: (tx: TenantTransaction) => Promise<T>,
+): Promise<T> {
+	return database.transaction(async (tx) => {
 		await tx.execute(
 			sql`SELECT set_config('app.current_user_id', ${ctx.userId}, true)`,
 		);

package/server.json

@@ -8,12 +8,12 @@
     "source": "github",
     "id": "1249550690"
   },
-  "version": "0.6.8",
+  "version": "0.7.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@hiai-gg/docsmint",
-      "version": "0.6.8",
+      "version": "0.7.0",
       "transport": {
         "type": "stdio"
       },