@flowdular/sdk 0.2.4 → 0.3.1

package/modules/sandbox/module.json

@@ -3,7 +3,7 @@
 	"schemaVersion": 1,
 	"id": "sandbox.core",
 	"package": "@flowdular/module-sandbox",
-	"version": "0.4.0",
+	"version": "0.4.1",
 	"profile": "full",
 	"capabilities": ["api", "database", "client", "translations", "cli"],
 	"platform": {
@@ -13,11 +13,11 @@
 	"dependencies": [
 		{
 			"id": "system.core",
-			"range": "0.5.0"
+			"range": "^0.7.0"
 		},
 		{
 			"id": "auth.core",
-			"range": "0.10.0"
+			"range": "^0.13.0"
 		}
 	],
 	"tenancy": "required",
@@ -27,5 +27,5 @@
 		"catalog": "src/cli/commands.json",
 		"entry": "src/cli/index.ts"
 	},
-	"platformApi": "0.1.0"
+	"platformApi": "^0.1.0"
 }

package/modules/sandbox/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@flowdular/module-sandbox",
-	"version": "0.4.0",
+	"version": "0.4.1",
 	"type": "module",
 	"exports": {
 		".": "./src/index.ts",

package/modules/sandbox/spec/module.yaml

@@ -1,6 +1,6 @@
 schemaVersion: 1
 id: sandbox.core
-specVersion: 0.4.0
+specVersion: 0.4.1
 status: approved
 name: Sandbox Access
 description: Owns sandbox access grants, sandbox session records, and the audit evidence that lets an authorized account open the Flowdular sandbox, preview a draft module against live platform data, and eject an accepted module into the workspace.
@@ -13,9 +13,9 @@ capabilities:
   - cli
 dependencies:
   - id: system.core
-    range: 0.5.0
+    range: ^0.7.0
   - id: auth.core
-    range: 0.10.0
+    range: ^0.13.0
 tenancy: required
 locales:
   - en

package/modules/sandbox/src/services/database-repository.ts

@@ -1,6 +1,6 @@
 import { createHash, randomUUID } from 'node:crypto';
 import type { DatabaseHandle, DatabaseTransaction } from '@flowdular/sdk/database';
-import { runDatabaseMigrations } from '@flowdular/sdk/database';
+import { integer, runDatabaseMigrations } from '@flowdular/sdk/database';
 import type {
 	SandboxAccessGrant,
 	SandboxAuditChainVerification,
@@ -57,21 +57,11 @@ interface AuditRow {
 	event_hash: string;
 }
 
-/* PostgreSQL returns BIGINT as a string. The audit hash covers sequence and
-   occurredAt, so a string here would silently break every chain verification
-   rather than merely look wrong. */
-function integer(value: number | bigint | string): number {
-	const normalized = Number(value);
-	if (!Number.isSafeInteger(normalized)) {
-		throw new Error('The sandbox database returned an invalid integer.');
-	}
-	return normalized;
-}
-
 function optionalInteger(
 	value: number | bigint | string | null,
+	field: string,
 ): number | null {
-	return value === null ? null : integer(value);
+	return value === null ? null : integer(value, field);
 }
 
 function fromGrantRow(row: GrantRow): SandboxAccessGrant {
@@ -86,9 +76,9 @@ function fromGrantRow(row: GrantRow): SandboxAccessGrant {
 		) as readonly SandboxGrantCapability[],
 		note: row.note,
 		grantedBy: row.granted_by,
-		grantedAt: integer(row.granted_at),
-		expiresAt: optionalInteger(row.expires_at),
-		revokedAt: optionalInteger(row.revoked_at),
+		grantedAt: integer(row.granted_at, 'granted_at'),
+		expiresAt: optionalInteger(row.expires_at, 'expires_at'),
+		revokedAt: optionalInteger(row.revoked_at, 'revoked_at'),
 		revokedBy: row.revoked_by,
 	};
 }
@@ -104,10 +94,10 @@ function fromSessionRow(row: SessionRow): SandboxSessionRecord {
 		driver: row.driver,
 		mode: row.mode,
 		state: row.state,
-		createdAt: integer(row.created_at),
-		updatedAt: integer(row.updated_at),
-		ejectedAt: optionalInteger(row.ejected_at),
-		archivedAt: optionalInteger(row.archived_at),
+		createdAt: integer(row.created_at, 'created_at'),
+		updatedAt: integer(row.updated_at, 'updated_at'),
+		ejectedAt: optionalInteger(row.ejected_at, 'ejected_at'),
+		archivedAt: optionalInteger(row.archived_at, 'archived_at'),
 	};
 }
 
@@ -115,13 +105,13 @@ function fromAuditRow(row: AuditRow): SandboxAuditEvent {
 	return {
 		id: row.id,
 		tenantId: row.tenant_id,
-		sequence: integer(row.sequence),
+		sequence: integer(row.sequence, 'sequence'),
 		actorId: row.actor_id,
 		action: row.action,
 		subjectType: row.subject_type,
 		subjectId: row.subject_id,
 		metadata: JSON.parse(row.metadata_json) as SandboxAuditEvent['metadata'],
-		occurredAt: integer(row.occurred_at),
+		occurredAt: integer(row.occurred_at, 'occurred_at'),
 		previousHash: row.previous_hash,
 		eventHash: row.event_hash,
 	};
@@ -397,7 +387,8 @@ export class DatabaseSandboxRepository implements SandboxRepository {
 					parameters: [event.tenantId],
 				});
 				const previous = latest.rows[0];
-				const sequence = (previous ? integer(previous.sequence) : 0) + 1;
+				const sequence =
+					(previous ? integer(previous.sequence, 'sequence') : 0) + 1;
 				const previousHash = previous?.event_hash ?? null;
 				const metadataJson = stableMetadata(event.metadata);
 				const created: SandboxAuditEvent = {

package/modules/sandbox/src/services/directory.ts

@@ -13,6 +13,11 @@ export interface SandboxDirectoryMember {
 export interface SandboxDirectory {
 	listMembers(tenantId: string): Promise<readonly SandboxDirectoryMember[]>;
 	listScopes(accountId: string, tenantId: string): Promise<readonly string[]>;
+	/** The scopes of many members in one auth read, keyed by account id. */
+	listScopesForMembers(
+		accountIds: readonly string[],
+		tenantId: string,
+	): Promise<ReadonlyMap<string, readonly string[]>>;
 }
 
 export function directoryFromAuthRuntime(auth: AuthRuntime): SandboxDirectory {
@@ -29,5 +34,16 @@ export function directoryFromAuthRuntime(auth: AuthRuntime): SandboxDirectory {
 			),
 		listScopes: async (accountId, tenantId) =>
 			(await auth.service()).listMembershipScopes(accountId, tenantId),
+		listScopesForMembers: async (accountIds, tenantId) => {
+			const wanted = new Set(accountIds);
+			const scopes = new Map<string, readonly string[]>();
+			for (const member of await (
+				await auth.service()
+			).listTenantMembers(tenantId)) {
+				if (wanted.has(member.accountId))
+					scopes.set(member.accountId, member.scopes);
+			}
+			return scopes;
+		},
 	};
 }

package/modules/sandbox/src/services/sandbox-service.ts

@@ -151,18 +151,20 @@ export class SandboxService {
 	): Promise<readonly SandboxAccessCandidate[]> {
 		const tenant = identifier(tenantId, 'tenantId');
 		const members = await this.directory.listMembers(tenant);
-		return await Promise.all(
-			members.map(async (member) => ({
-				accountId: member.accountId,
-				email: member.email,
-				displayName: member.displayName,
-				role: member.role,
-				status: member.status,
-				availableCapabilities: sandboxCapabilitiesOf(
-					await this.directory.listScopes(member.accountId, tenant),
-				),
-			})),
+		const scopes = await this.directory.listScopesForMembers(
+			members.map((member) => member.accountId),
+			tenant,
 		);
+		return members.map((member) => ({
+			accountId: member.accountId,
+			email: member.email,
+			displayName: member.displayName,
+			role: member.role,
+			status: member.status,
+			availableCapabilities: sandboxCapabilitiesOf(
+				scopes.get(member.accountId) ?? [],
+			),
+		}));
 	}
 
 	async listGrants(tenantId: string): Promise<readonly SandboxAccessGrant[]> {

package/modules/search/migrations/0001_search_core.down.sql

@@ -0,0 +1 @@
+DROP TABLE IF EXISTS search_recent_queries;

package/modules/search/migrations/0001_search_core.up.sql

@@ -0,0 +1,22 @@
+CREATE TABLE IF NOT EXISTS search_recent_queries (
+  id TEXT PRIMARY KEY,
+  tenant_id TEXT NOT NULL,
+  account_id TEXT NOT NULL,
+  query TEXT NOT NULL,
+  ran_at BIGINT NOT NULL
+);
+-- One row per member and query text. Re-running a query moves it to the top
+-- instead of filling the member's recall list with the same words, so the
+-- bound of 50 counts distinct queries rather than keystrokes.
+CREATE UNIQUE INDEX IF NOT EXISTS search_recent_queries_member_query_idx
+  ON search_recent_queries (tenant_id, account_id, lower(query));
+CREATE INDEX IF NOT EXISTS search_recent_queries_member_idx
+  ON search_recent_queries (tenant_id, account_id, ran_at DESC, id DESC);
+-- Retention sweeps the workspace, not one member, so it needs its own order.
+CREATE INDEX IF NOT EXISTS search_recent_queries_retention_idx
+  ON search_recent_queries (tenant_id, ran_at, id);
+ALTER TABLE search_recent_queries ENABLE ROW LEVEL SECURITY;
+ALTER TABLE search_recent_queries FORCE ROW LEVEL SECURITY;
+CREATE POLICY search_recent_queries_tenant_policy ON search_recent_queries
+  USING (tenant_id = current_setting('coreloom.tenant_id', true))
+  WITH CHECK (tenant_id = current_setting('coreloom.tenant_id', true));

package/modules/search/migrations/0002_search_recent_export.down.sql

@@ -0,0 +1,3 @@
+-- Reverses 0002: the export walk falls back to a sequential scan of the
+-- workspace's rows, which is correct but unindexed.
+DROP INDEX IF EXISTS search_recent_queries_export_idx;

package/modules/search/migrations/0002_search_recent_export.up.sql

@@ -0,0 +1,5 @@
+-- The export walk pages on the immutable key. Re-running a query rewrites its
+-- ran_at, so a keyset on the timestamp hands the walk the same row again; the
+-- retention index orders by ran_at and cannot serve the id order.
+CREATE INDEX IF NOT EXISTS search_recent_queries_export_idx
+  ON search_recent_queries (tenant_id, id);

package/modules/search/migrations/README.md

@@ -0,0 +1,3 @@
+# Migrations
+
+Migrations in this directory are append-only after release.

package/modules/search/module.json

@@ -0,0 +1,28 @@
+{
+	"$schema": "../../packages/contracts/schemas/module.schema.json",
+	"schemaVersion": 1,
+	"id": "search.core",
+	"package": "@flowdular/module-search",
+	"version": "0.1.5",
+	"platformApi": "^0.1.0",
+	"profile": "full",
+	"capabilities": ["api", "database", "client", "translations"],
+	"platform": {
+		"server": true,
+		"client": true
+	},
+	"dependencies": [
+		{
+			"id": "system.core",
+			"range": "^0.7.0"
+		},
+		{
+			"id": "auth.core",
+			"range": "^0.13.0"
+		}
+	],
+	"provides": ["search.providers.v1"],
+	"tenancy": "required",
+	"locales": ["en", "pl"],
+	"stability": "experimental"
+}

package/modules/search/package.json

@@ -0,0 +1,43 @@
+{
+	"name": "@flowdular/module-search",
+	"version": "0.1.5",
+	"private": true,
+	"type": "module",
+	"exports": {
+		".": "./src/index.ts",
+		"./client": "./src/client/index.ts",
+		"./server": "./src/server/index.ts",
+		"./platform": "./src/platform.ts",
+		"./module.json": "./module.json"
+	},
+	"files": [
+		"src",
+		"module.json",
+		"migrations",
+		"translations",
+		"spec",
+		"README.md"
+	],
+	"scripts": {
+		"typecheck": "tsrx-tsc --noEmit -p tsconfig.json",
+		"test": "vitest run"
+	},
+	"dependencies": {
+		"@flowdular/client": "workspace:*",
+		"@flowdular/contracts": "workspace:*",
+		"@flowdular/database": "workspace:*",
+		"@flowdular/kernel": "workspace:*",
+		"@flowdular/module-auth": "workspace:*",
+		"@flowdular/server": "workspace:*",
+		"@flowdular/ui": "workspace:*",
+		"octane": "0.1.51",
+		"segment-state": "0.2.1"
+	},
+	"devDependencies": {
+		"@flowdular/database-testing": "workspace:*",
+		"@tsrx/typescript-plugin": "0.3.120",
+		"@types/node": "24.13.3",
+		"typescript": "5.9.3",
+		"vitest": "4.1.11"
+	}
+}

package/modules/search/spec/module.yaml

@@ -0,0 +1,177 @@
+schemaVersion: 2
+id: search.core
+specVersion: 0.1.5
+status: approved
+name: Search Core
+description: Lets a member find records across modules from one search box, by asking every module that registered a search provider to search its own tables under the member's permissions and merging the paginated hits, with PostgreSQL full-text indexes owned by each module and no central index.
+profile: full
+capabilities:
+  - api
+  - database
+  - client
+  - translations
+dependencies:
+  - id: system.core
+    range: ^0.7.0
+  - id: auth.core
+    range: ^0.13.0
+tenancy: required
+locales:
+  - en
+  - pl
+invariants:
+  - Persistence runs on the shared asynchronous database contract with explicit PostgreSQL SQL; every tenant table enables and forces row-level security with USING and WITH CHECK policies bound to the transaction-local tenant id, and the runtime role holds neither SUPERUSER nor BYPASSRLS.
+  - A search provider is registered by its owning module through the public capability search.providers.v1 at composition with a stable key, a label, the permission a member needs to see its hits, and a search(tenantId, principal, query, page) operation that runs inside the owner's own tenant-scoped transaction over the owner's own tables; search.core never reads another module's tables and holds no index of its own.
+  - A query is bounded to 200 characters, normalised, and sent to every provider whose permission the principal holds, in parallel, with a per-provider time budget; a provider that fails or times out contributes no hits and is reported as unavailable in the response, never as an error for the whole search.
+  - Hits are merged by provider order and score, paginated with the platform pagination helpers, and carry only what the provider returned (record reference, title, snippet, view id and route); search.core never fetches the record.
+  - A provider searches its own tables with an index it owns, PostgreSQL full-text search where the owner holds the columns; the capability carries no index declaration, so composition validates the provider shape and bounds only, and the owner's tests prove the index or the bounded scan (users.core scans at most 500 memberships through the auth administration port because auth.core owns the table).
+  - Recent queries of a member are kept per workspace for their own recall (bounded to 50, deletable by the member) and are the data class search.core.recent-queries with a default retention of 90 days, swept through the platform registry; a query is kept only when the member submits it deliberately or opens one of its hits, never for a debounced prefix.
+  - The command palette shows record hits below navigation entries when a query is at least two characters long, debounced, and never blocks navigation; the full search screen lists hits with provider filters and pages further hits through the cursor the previous page answered with.
+permissions:
+  - id: search.records.read
+    description: Search records across modules in the active workspace within the member's own permissions.
+dataOwnership:
+  - search.core owns the registry of providers as recorded and the member's recent queries.
+  - Each provider module owns its index, its ranking and the permission that gates its hits.
+entities:
+  - id: provider
+    name: Search provider
+    description: One registered provider as the workspace sees it.
+    fields:
+      - id: key
+        type: string
+        required: true
+        unique: tenant
+        maxLength: 96
+      - id: moduleId
+        type: string
+        required: true
+        maxLength: 64
+      - id: label
+        type: string
+        required: true
+        maxLength: 120
+      - id: permission
+        type: string
+        required: true
+        maxLength: 96
+  - id: recent-query
+    name: Recent query
+    description: A query a member ran, for recall.
+    fields:
+      - id: accountId
+        type: string
+        required: true
+        maxLength: 128
+      - id: query
+        type: string
+        required: true
+        maxLength: 200
+      - id: ranAt
+        type: datetime
+        required: true
+screens:
+  - id: search
+    kind: list
+    entity: provider
+    title: Search
+    columns:
+      - label
+      - moduleId
+    filters:
+      - key
+    navigationGroup: Workspace
+actions:
+  - id: clear-recent
+    entity: recent-query
+    permission: search.records.read
+    kind: delete
+    risk: workspace-write
+    idempotent: true
+    description: Delete the member's own recent queries in this workspace.
+  - id: remember
+    entity: recent-query
+    permission: search.records.read
+    kind: create
+    risk: workspace-write
+    idempotent: true
+    description: Keep the query a member opened a hit from in their own recall list, as one write that outlives the screen it navigates away from; a repeat of the same query moves the existing row instead of adding one.
+widgets: []
+settings:
+  - key: providerTimeoutMs
+    type: integer
+    scope: platform
+    default: 1500
+    description: Time budget per provider per query; 200 to 10000.
+  - key: hitsPerProvider
+    type: integer
+    scope: platform
+    default: 20
+    description: Hits a provider may return per page; 5 to 100.
+agentTools: []
+outOfScope:
+  - A central index, a search service and cross-module ranking beyond provider order and score are rejected by RFC 0002 G7.
+  - Fuzzy matching and synonyms depend on each provider's index configuration; v1 uses the simple PostgreSQL configuration per locale.
+  - Searching document contents is not offered; documents.core indexes filenames and descriptions only.
+decisions:
+  - id: D-SEARCH-SHAPE
+    question: What is the first version?
+    answer: A provider contract per module, parallel querying with a time budget, merged paginated hits in the command palette and a search screen, PostgreSQL full-text indexes per module; the first providers are users members, notifications inbox, documents filenames and audit data classes.
+    decidedBy: user
+  - id: D-SEARCH-PERMISSIONS
+    question: Who may search?
+    answer: Every member holds search.records.read; each hit is additionally gated by the provider's permission.
+    decidedBy: default
+  - id: D-SEARCH-SCREEN
+    question: What does the Search screen show?
+    answer: The results of the query box, with a provider filter whose options read label and module id, and the unavailable providers named; the provider rows themselves are the filter, not a list of their own.
+    decidedBy: default
+  - id: D-SEARCH-RECENT
+    question: Are queries stored?
+    answer: Only the member's own last 50 per workspace, for recall, deletable, retained by policy, and only for a deliberate submit or an opened hit so a debounced prefix is never kept.
+    decidedBy: default
+  - id: D-SEARCH-TOPBAR
+    question: Does search.core contribute its own topbar widget?
+    answer: No. The shell already owns a topbar search button that opens the command palette, and a second widget in the same slot duplicated it; search.core contributes the palette hits and the screen only.
+    decidedBy: default
+acceptanceScenarios:
+  - id: SEARCH-PROVIDERS
+    given: Four modules registered providers at composition and one of them requires a permission the member lacks.
+    when: The member searches a term that matches records in all four.
+    then: Hits from the three permitted providers are merged and paginated, the fourth contributes nothing and is not listed as unavailable, and each hit carries a record reference, title, snippet and route only.
+  - id: SEARCH-TIMEOUT
+    given: A provider that exceeds the time budget.
+    when: A member searches.
+    then: The other providers' hits are returned within the budget, the slow provider is reported as unavailable, and no error is raised for the search.
+  - id: SEARCH-BOUNDS
+    given: A query over 200 characters or shorter than two.
+    when: A member searches.
+    then: The over-long query is refused with a stable error and the short query returns navigation entries only.
+  - id: SEARCH-RECENT
+    given: A member ran 51 queries.
+    when: The member lists recent queries and then clears them.
+    then: The newest 50 are listed for that member only and the clear removes them for that member in this workspace only.
+  - id: SEARCH-DENY
+    given: A principal is unauthenticated or lacks search.records.read.
+    when: The principal searches.
+    then: The server denies the operation before any provider is called.
+  - id: SEARCH-TENANT-BOUNDARY
+    given: Two workspaces with records and recent queries.
+    when: A member of one workspace searches.
+    then: Only that workspace's hits and recent queries appear, and a row carrying another tenant identifier is rejected by the forced policy.
+  - id: SEARCH-PAGING
+    given: More hits than one page holds.
+    when: The member asks for the next page from the search screen.
+    then: The cursor the previous page answered with is sent back, the further hits extend the list, and no cursor is answered past a provider that was unavailable on that page.
+  - id: SEARCH-RECENT-DELIBERATE
+    given: A member typing a query on the search screen.
+    when: The debounced searches run and the member then submits the query.
+    then: Only the submitted query is kept in recall, and the typed prefixes are not.
+  - id: SEARCH-STALE-ANSWER
+    given: A search of the search screen that has not answered yet, and an overlapping later request.
+    when: The member deletes the term back under the minimum, or types a different term, before the answer arrives.
+    then: The answer is discarded and no hits or page position are shown under a term that did not produce them; only the newest request answering the term the box still holds may write, and the screen's one load of the provider filter options, which asks with no term before the member has typed, still lands.
+  - id: SEARCH-OPEN-RECALL
+    given: A member opening one of the hits of the query, on the search screen or in the command palette.
+    when: The shell navigates to the record.
+    then: The query that hit answered, and not whatever the box holds by then, is kept in the member's recall by one write that outlives the navigation and calls no provider; the write is refused without the permission and without the CSRF token, and a term under the minimum is not kept; the record opens whether or not the write lands.

package/modules/search/src/acl/permissions.ts

@@ -0,0 +1,5 @@
+export const SEARCH_PERMISSIONS = {
+	read: 'search.records.read',
+} as const;
+
+export const permissions = Object.freeze(Object.values(SEARCH_PERMISSIONS));