@flowdular/sdk 0.2.4 → 0.3.1

package/packages/contracts/src/index.ts

@@ -1,3 +1,20 @@
+/* Version of the public platform contract, independent of application
+   versions. While it stays below 1.0.0 a patch bump means an additive change
+   that `^0.1.0` consumers still accept, and a minor bump means a member was
+   removed or changed. The surface is pinned by
+   packages/kernel/platform-api.snapshot.d.ts; `pnpm platform-api:check` fails
+   when the surface changes without a bump here. */
+export const PLATFORM_API_VERSION = '0.1.8';
+
+/* The workspace time zone: one tenant setting, declared by the module named
+   here and read by any module that shows or schedules a local time. The id, the
+   key and the fallback live here so a reader never restates them. */
+export const TENANT_TIME_ZONE_SETTING = {
+	moduleId: 'system.core',
+	key: 'timeZone',
+	defaultValue: 'UTC',
+} as const;
+
 export type ModuleCapability =
 	| 'api'
 	| 'database'
@@ -15,6 +32,16 @@ export interface ModuleDependency {
 	readonly range: string;
 }
 
+/* A public capability id another module registers through
+   `context.capabilities`, such as `notifications.publish.v1`. The version is
+   part of the id, so compatibility is asserted by name, not by module version. */
+export interface ModuleCapabilityRequirement {
+	readonly id: string;
+	/* An optional requirement is resolved with `get` returning null when no
+	   enabled module provides it; a required one fails composition. */
+	readonly optional?: boolean;
+}
+
 export interface ModuleManifest {
 	readonly platformApi?: string;
 	readonly $schema?: string;
@@ -25,6 +52,10 @@ export interface ModuleManifest {
 	readonly profile: ModuleProfile;
 	readonly capabilities: readonly ModuleCapability[];
 	readonly dependencies: readonly ModuleDependency[];
+	/** Capability ids this module registers at composition. */
+	readonly provides?: readonly string[];
+	/** Capability ids this module resolves from other modules. */
+	readonly requires?: readonly ModuleCapabilityRequirement[];
 	readonly tenancy: 'required' | 'optional' | 'none';
 	readonly locales: readonly string[];
 	readonly stability: ModuleStability;
@@ -54,8 +85,105 @@ export interface BlueprintManifest {
 	readonly status: 'draft' | 'approved' | 'deprecated';
 }
 
+export type ModuleSpecFieldType =
+	| 'string'
+	| 'text'
+	| 'integer'
+	| 'decimal'
+	| 'boolean'
+	| 'date'
+	| 'datetime'
+	| 'enum'
+	| 'reference'
+	| 'json';
+
+export interface ModuleSpecField {
+	readonly id: string;
+	readonly type: ModuleSpecFieldType;
+	readonly required?: boolean;
+	readonly unique?: 'tenant' | 'none';
+	readonly maxLength?: number;
+	/* Enum members; required when type is enum. */
+	readonly values?: readonly string[];
+	/* "<entityId>" in this spec, or "<moduleId>.<entityId>" in a dependency. */
+	readonly reference?: string;
+	readonly description?: string;
+}
+
+export interface ModuleSpecStates {
+	readonly field: string;
+	readonly values: readonly string[];
+	readonly transitions?: readonly {
+		readonly from: string;
+		readonly to: string;
+		readonly permission?: string;
+	}[];
+}
+
+export interface ModuleSpecEntity {
+	readonly id: string;
+	readonly name: string;
+	readonly description?: string;
+	readonly fields: readonly ModuleSpecField[];
+	readonly states?: ModuleSpecStates;
+}
+
+export interface ModuleSpecScreen {
+	readonly id: string;
+	readonly kind: 'list' | 'record' | 'form' | 'dashboard';
+	readonly entity?: string;
+	readonly title?: string;
+	readonly columns?: readonly string[];
+	readonly filters?: readonly string[];
+	readonly navigationGroup?: string;
+}
+
+export interface ModuleSpecAction {
+	readonly id: string;
+	readonly entity?: string;
+	readonly permission: string;
+	readonly kind: 'create' | 'update' | 'delete' | 'custom';
+	readonly risk: 'read' | 'workspace-write' | 'external' | 'destructive';
+	readonly idempotent: boolean;
+	readonly description: string;
+}
+
+export interface ModuleSpecWidget {
+	readonly id: string;
+	readonly slot:
+		| 'dashboard.metrics'
+		| 'dashboard.main'
+		| 'dashboard.aside'
+		| 'topbar.actions';
+	readonly entity?: string;
+	readonly description: string;
+}
+
+export interface ModuleSpecSetting {
+	readonly key: string;
+	readonly type: 'string' | 'integer' | 'boolean' | 'enum';
+	readonly scope: 'tenant' | 'platform';
+	readonly default?: string | number | boolean;
+	readonly values?: readonly string[];
+	readonly description: string;
+}
+
+export interface ModuleSpecAgentTool {
+	readonly id: string;
+	readonly permission: string;
+	readonly description: string;
+	readonly risk: 'read' | 'workspace-write';
+}
+
+export interface ModuleSpecDecision {
+	readonly id: string;
+	readonly question: string;
+	readonly answer: string;
+	readonly decidedBy: 'user' | 'default';
+}
+
 export interface ModuleSpec {
-	readonly schemaVersion: 1;
+	readonly schemaVersion: 1 | 2;
 	readonly id: string;
 	readonly specVersion: string;
 	readonly status:
@@ -69,6 +197,8 @@ export interface ModuleSpec {
 	readonly profile: ModuleProfile;
 	readonly capabilities: readonly ModuleCapability[];
 	readonly dependencies: readonly ModuleDependency[];
+	readonly provides?: readonly string[];
+	readonly requires?: readonly ModuleCapabilityRequirement[];
 	readonly tenancy: 'required' | 'optional' | 'none';
 	readonly locales: readonly string[];
 	readonly invariants?: readonly string[];
@@ -83,8 +213,21 @@ export interface ModuleSpec {
 		readonly when: string;
 		readonly then: string;
 	}[];
+	/* Domain model, accepted only with schemaVersion 2. Every member stays
+	   optional so a specification can adopt version 2 section by section. */
+	readonly entities?: readonly ModuleSpecEntity[];
+	readonly screens?: readonly ModuleSpecScreen[];
+	readonly actions?: readonly ModuleSpecAction[];
+	readonly widgets?: readonly ModuleSpecWidget[];
+	readonly settings?: readonly ModuleSpecSetting[];
+	readonly agentTools?: readonly ModuleSpecAgentTool[];
+	readonly outOfScope?: readonly string[];
+	readonly decisions?: readonly ModuleSpecDecision[];
 }
 
+/** A specification that carries the version 2 domain model. */
+export type ModuleSpecV2 = ModuleSpec & { readonly schemaVersion: 2 };
+
 export interface ValidationIssue {
 	readonly code: string;
 	readonly message: string;

package/packages/database/src/backup.ts

@@ -0,0 +1,180 @@
+import { createHash } from 'node:crypto';
+import { DatabaseError } from './contracts.ts';
+import type { ConfiguredDatabaseAdapter } from './provider.ts';
+
+export const BACKUP_MANIFEST_FILE = 'backup.json';
+export const BACKUP_MANIFEST_VERSION = 1;
+
+/**
+ * The encryption keys that protect data stored inside the database. A dump
+ * alone restores unreadable credentials and workflow payloads, so every backup
+ * records which keys it was taken under. Only a SHA-256 fingerprint of the key
+ * material is recorded; the material itself never enters a backup.
+ */
+export const BACKUP_KEY_VARIABLES = Object.freeze([
+	'FD_AGENT_CREDENTIAL_KEY',
+	'FD_AGENT_RUN_GRANT_KEY',
+	'FD_APPROVAL_GRANT_KEY',
+	'FD_WORKFLOWS_PAYLOAD_KEY',
+	'FD_WORKFLOWS_CURSOR_KEY',
+	'FD_AUTH_MFA_KEY',
+	'FD_AUTOMATIONS_CREDENTIAL_KEY',
+	'FD_NOTIFICATIONS_SECRET_KEY',
+	'FD_STORAGE_ENCRYPTION_KEY',
+	'FD_CONNECTORS_SECRET_KEY',
+	'FD_AUDIT_ANCHOR_KEY',
+] as const);
+
+export interface BackupKeyFingerprint {
+	readonly variable: string;
+	/** `sha256:<hex>` of the key material, or null when the key was not set. */
+	readonly fingerprint: string | null;
+}
+
+export interface BackupManifest {
+	readonly schemaVersion: number;
+	readonly createdAt: string;
+	readonly adapter: ConfiguredDatabaseAdapter;
+	readonly platformVersion: string;
+	readonly modules: readonly string[];
+	readonly keys: readonly BackupKeyFingerprint[];
+}
+
+export type BackupKeyStatus =
+	| 'match'
+	| 'different'
+	| 'missing-in-environment'
+	| 'missing-in-backup';
+
+export interface BackupKeyComparison {
+	readonly variable: string;
+	readonly status: BackupKeyStatus;
+}
+
+/* One 32 byte key is written as hex, base64 or base64url depending on the
+   module that reads it, so the fingerprint covers the decoded bytes and not the
+   spelling. A value that decodes to anything else is fingerprinted verbatim. */
+function keyMaterial(value: string): Buffer {
+	if (/^[0-9a-f]{64}$/i.test(value)) return Buffer.from(value, 'hex');
+	const decoded = Buffer.from(value, 'base64');
+	return decoded.byteLength === 32 ? decoded : Buffer.from(value, 'utf8');
+}
+
+export function backupKeyFingerprint(value: string | undefined): string | null {
+	const trimmed = value?.trim();
+	if (!trimmed) return null;
+	const material = keyMaterial(trimmed);
+	const digest = createHash('sha256').update(material).digest('hex');
+	material.fill(0);
+	return `sha256:${digest}`;
+}
+
+export function backupKeyFingerprints(
+	environment: NodeJS.ProcessEnv,
+): readonly BackupKeyFingerprint[] {
+	return BACKUP_KEY_VARIABLES.map((variable) => ({
+		variable,
+		fingerprint: backupKeyFingerprint(environment[variable]),
+	}));
+}
+
+/**
+ * Every key the backup or this platform knows about, so a restore can warn
+ * before the data it is about to write becomes unreadable.
+ */
+export function compareBackupKeys(
+	manifest: BackupManifest,
+	environment: NodeJS.ProcessEnv,
+): readonly BackupKeyComparison[] {
+	const recorded = new Map(
+		manifest.keys.map((key) => [key.variable, key.fingerprint]),
+	);
+	const variables = [
+		...new Set([...recorded.keys(), ...BACKUP_KEY_VARIABLES]),
+	].sort((left, right) => left.localeCompare(right));
+	return variables.map((variable) => {
+		const backup = recorded.get(variable) ?? null;
+		const current = backupKeyFingerprint(environment[variable]);
+		if (backup === current) return { variable, status: 'match' as const };
+		if (!current)
+			return { variable, status: 'missing-in-environment' as const };
+		if (!backup) return { variable, status: 'missing-in-backup' as const };
+		return { variable, status: 'different' as const };
+	});
+}
+
+export function createBackupManifest(input: {
+	readonly adapter: ConfiguredDatabaseAdapter;
+	readonly platformVersion: string;
+	readonly modules: readonly string[];
+	readonly environment: NodeJS.ProcessEnv;
+	readonly createdAt?: Date;
+}): BackupManifest {
+	return {
+		schemaVersion: BACKUP_MANIFEST_VERSION,
+		createdAt: (input.createdAt ?? new Date()).toISOString(),
+		adapter: input.adapter,
+		platformVersion: input.platformVersion,
+		modules: [...input.modules],
+		keys: backupKeyFingerprints(input.environment),
+	};
+}
+
+function invalid(reason: string): never {
+	throw new DatabaseError(
+		'INVALID_ARGUMENT',
+		`The backup manifest is invalid: ${reason}`,
+	);
+}
+
+function boundedString(value: unknown, field: string): string {
+	if (typeof value !== 'string' || value.length < 1 || value.length > 256) {
+		invalid(`${field} must be a string of 1 to 256 characters.`);
+	}
+	return value;
+}
+
+/** Parses a manifest read from disk. Bounded so a hostile file cannot grow the process. */
+export function parseBackupManifest(value: unknown): BackupManifest {
+	if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+		invalid('it is not an object.');
+	}
+	const record = value as Record<string, unknown>;
+	if (record.schemaVersion !== BACKUP_MANIFEST_VERSION) {
+		invalid(`schemaVersion must be ${BACKUP_MANIFEST_VERSION}.`);
+	}
+	const adapter = record.adapter;
+	if (adapter !== 'pglite' && adapter !== 'postgresql') {
+		invalid('adapter must be "pglite" or "postgresql".');
+	}
+	if (!Array.isArray(record.modules) || record.modules.length > 512) {
+		invalid('modules must be a list of at most 512 module ids.');
+	}
+	if (!Array.isArray(record.keys) || record.keys.length > 64) {
+		invalid('keys must be a list of at most 64 fingerprints.');
+	}
+	return {
+		schemaVersion: BACKUP_MANIFEST_VERSION,
+		createdAt: boundedString(record.createdAt, 'createdAt'),
+		adapter,
+		platformVersion: boundedString(record.platformVersion, 'platformVersion'),
+		modules: record.modules.map((entry) => boundedString(entry, 'modules[]')),
+		keys: record.keys.map((entry) => {
+			if (typeof entry !== 'object' || entry === null) {
+				invalid('keys[] must be an object.');
+			}
+			const key = entry as Record<string, unknown>;
+			const fingerprint = key.fingerprint;
+			if (fingerprint !== null && typeof fingerprint !== 'string') {
+				invalid('keys[].fingerprint must be a string or null.');
+			}
+			return {
+				variable: boundedString(key.variable, 'keys[].variable'),
+				fingerprint:
+					fingerprint === null
+						? null
+						: boundedString(fingerprint, 'keys[].fingerprint'),
+			};
+		}),
+	};
+}

package/packages/database/src/decoders.ts

@@ -0,0 +1,25 @@
+/**
+ * Reads an integer column as the adapters hand it back: the embedded build
+ * returns a number, the server driver returns int8 as text and a driver
+ * configured for it returns a bigint. A fraction, an unsafe integer or a value
+ * below `min` is a defect in the read, so it throws naming the field.
+ */
+export function integer(
+	value: unknown,
+	field: string,
+	options?: { readonly min?: number },
+): number {
+	const normalized =
+		typeof value === 'number' ||
+		typeof value === 'bigint' ||
+		typeof value === 'string'
+			? Number(value)
+			: Number.NaN;
+	if (
+		!Number.isSafeInteger(normalized) ||
+		(options?.min !== undefined && normalized < options.min)
+	) {
+		throw new Error(`The database returned an invalid ${field}.`);
+	}
+	return normalized;
+}

package/packages/database/src/index.ts

@@ -67,7 +67,24 @@ export type {
 	DatabaseProviderFactories,
 	DatabaseReadiness,
 } from './provider.ts';
+export {
+	backupKeyFingerprint,
+	backupKeyFingerprints,
+	compareBackupKeys,
+	createBackupManifest,
+	parseBackupManifest,
+	BACKUP_KEY_VARIABLES,
+	BACKUP_MANIFEST_FILE,
+	BACKUP_MANIFEST_VERSION,
+} from './backup.ts';
+export type {
+	BackupKeyComparison,
+	BackupKeyFingerprint,
+	BackupKeyStatus,
+	BackupManifest,
+} from './backup.ts';
 export { appendRecordHistory, queryRecordHistory } from './record-history.ts';
+export { integer } from './decoders.ts';
 export { databaseResetPlan, resetDatabase } from './reset.ts';
 export type {
 	DatabaseResetAuthorization,

package/packages/database/src/migrations.ts

@@ -10,6 +10,8 @@ import {
 } from './contracts.ts';
 
 export const DATABASE_MIGRATION_LEDGER = '_coreloom_migrations_v2';
+/** The advisory lock every module migration takes before its own. */
+export const DATABASE_MIGRATION_LEDGER_LOCK = 'coreloom.migrations';
 
 /* Line endings and surrounding blank space are editor noise; everything else,
    including whitespace inside the SQL, is part of the checksum. Changing this
@@ -377,6 +379,11 @@ export async function runDatabaseMigrations(
 
 	return database.transaction(
 		async (transaction) => {
+			/* Every module shares the ledger table, and this transaction is
+			   serializable, so two modules migrating at the same boot collide on
+			   it with a serialization failure. The ledger lock serialises boots
+			   across modules; the namespace lock keeps the per-module contract. */
+			await transaction.acquireMigrationLock(DATABASE_MIGRATION_LEDGER_LOCK);
 			await transaction.acquireMigrationLock(namespace);
 			await transaction.executeScript(
 				database.capabilities.sql.migrationLedgerDdl(DATABASE_MIGRATION_LEDGER),

package/packages/database/src/record-history.ts

@@ -14,6 +14,7 @@ import {
 	type DatabaseParameter,
 	type DatabaseSession,
 } from './contracts.ts';
+import { integer } from './decoders.ts';
 
 interface HistoryRow {
 	readonly id: string;
@@ -29,17 +30,6 @@ interface HistoryRow {
 	readonly occurred_at: number | bigint | string;
 }
 
-/* The server driver returns BIGINT as a string while the embedded build returns
-   a number, so every integer read crosses the same normalizer instead of
-   trusting whichever one a deployment happens to open. */
-function integer(value: number | bigint | string, field: string): number {
-	const normalized = Number(value);
-	if (!Number.isSafeInteger(normalized) || normalized < 0) {
-		throw new Error(`The history table returned an invalid ${field}.`);
-	}
-	return normalized;
-}
-
 function actorFromRow(row: HistoryRow): Actor {
 	if (row.actor_kind === 'user') {
 		return { kind: 'user', id: row.actor_id, label: row.actor_label };
@@ -115,7 +105,8 @@ export async function appendRecordHistory(
 		parameters: [write.tenantId, write.recordId],
 	});
 	const current = previous.rows[0]?.version ?? null;
-	const version = (current === null ? 0 : integer(current, 'version')) + 1;
+	const version =
+		(current === null ? 0 : integer(current, 'version', { min: 0 })) + 1;
 	const values: DatabaseParameter[] = [
 		randomUUID(),
 		write.tenantId,
@@ -185,11 +176,11 @@ export async function queryRecordHistory(
 		(row): HistoryEntry => ({
 			id: row.id,
 			recordId: row.record_id,
-			version: integer(row.version, 'version'),
+			version: integer(row.version, 'version', { min: 0 }),
 			action: row.action,
 			actor: actorFromRow(row),
 			changes: JSON.parse(row.changes_json) as RecordChanges,
-			occurredAt: integer(row.occurred_at, 'timestamp'),
+			occurredAt: integer(row.occurred_at, 'timestamp', { min: 0 }),
 		}),
 	);
 	const last = page[page.length - 1];

package/packages/harness/src/index.ts

@@ -32,6 +32,8 @@ export type {
 	AgentTool,
 	AgentToolAccessAuthorizer,
 	AgentToolAuthorizationRequest,
+	AgentToolConsent,
+	AgentToolConsentDecision,
 	AgentToolContext,
 	AgentUsage,
 	JsonValue,