@chipmobilesdk/rn-local-db 0.1.0

package/src/query/validate.ts

@@ -0,0 +1,171 @@
+/**
+ * Query validation, run before any SQL is built.
+ *
+ * Two things fall out of validating first: FR-034 is satisfied, and no
+ * consumer-supplied string ever reaches SQL construction — field names are
+ * resolved through the schema to a known column, and values bind as
+ * parameters. Injection stops being a thing to remember.
+ */
+
+import { Budgets } from '../contract/config';
+import { DiagnosticCodes } from '../contract/errors';
+import type { FilterNode, FilterValue, Query, SortKey } from '../contract/query';
+import type { CollectionSchema, FieldType } from '../contract/schema';
+import { raise } from '../diagnostics/errors';
+import { sanitizeIdentifier } from '../diagnostics/redact';
+import { fieldOf } from '../schema/declare';
+
+function queryInvalid(message: string, collection: string): never {
+	// The field name is named; its *value* never is (FR-079).
+	raise(DiagnosticCodes.QUERY_INVALID, { message, detail: { collection } });
+}
+
+const ORDERED_OPERATORS = new Set(['lt', 'lte', 'gt', 'gte', 'between']);
+
+function typeMatches(type: FieldType, value: FilterValue): boolean {
+	if (value === null) {
+		return true;
+	}
+	switch (type) {
+		case 'string':
+			return typeof value === 'string';
+		case 'number':
+		case 'timestamp':
+			return typeof value === 'number';
+		case 'boolean':
+			return typeof value === 'boolean';
+		default:
+			return false;
+	}
+}
+
+function validateField(
+	collection: CollectionSchema,
+	field: string,
+): ReturnType<typeof fieldOf> {
+	const declared = fieldOf(collection, field);
+	if (!declared) {
+		// Returning everything or nothing here would be worse than failing:
+		// a typo would silently change what the user sees.
+		queryInvalid(`filter references undeclared field ${sanitizeIdentifier(field)}`, collection.name);
+	}
+	return declared;
+}
+
+export function validateFilter(collection: CollectionSchema, node: FilterNode): void {
+	switch (node.op) {
+		case 'and':
+		case 'or': {
+			if (!Array.isArray(node.nodes) || node.nodes.length === 0) {
+				queryInvalid(`${node.op} requires at least one child`, collection.name);
+			}
+			for (const child of node.nodes) {
+				validateFilter(collection, child);
+			}
+			return;
+		}
+		case 'not': {
+			if (!node.node) {
+				queryInvalid('not requires a child', collection.name);
+			}
+			validateFilter(collection, node.node);
+			return;
+		}
+		case 'isNull':
+		case 'isNotNull': {
+			validateField(collection, node.field);
+			return;
+		}
+		case 'exists': {
+			validateField(collection, node.field);
+			if (typeof node.value !== 'boolean') {
+				queryInvalid('exists requires a boolean', collection.name);
+			}
+			return;
+		}
+		case 'in':
+		case 'nin': {
+			const declared = validateField(collection, node.field)!;
+			if (!Array.isArray(node.value) || node.value.length === 0) {
+				queryInvalid(`${node.op} requires a non-empty array`, collection.name);
+			}
+			for (const value of node.value) {
+				if (!typeMatches(declared.type, value)) {
+					queryInvalid(`${node.op} value does not match field type`, collection.name);
+				}
+			}
+			return;
+		}
+		case 'between': {
+			const declared = validateField(collection, node.field)!;
+			if (!Array.isArray(node.value) || node.value.length !== 2) {
+				queryInvalid('between requires exactly two bounds', collection.name);
+			}
+			for (const value of node.value) {
+				if (!typeMatches(declared.type, value)) {
+					queryInvalid('between bound does not match field type', collection.name);
+				}
+			}
+			return;
+		}
+		case 'eq':
+		case 'ne':
+		case 'lt':
+		case 'lte':
+		case 'gt':
+		case 'gte': {
+			const declared = validateField(collection, node.field)!;
+			if (declared.type === 'boolean' && ORDERED_OPERATORS.has(node.op)) {
+				queryInvalid('ordered comparison is not defined for a boolean', collection.name);
+			}
+			if (!typeMatches(declared.type, node.value)) {
+				queryInvalid('filter value does not match field type', collection.name);
+			}
+			return;
+		}
+		default: {
+			queryInvalid(
+				`unsupported operator ${sanitizeIdentifier(String((node as { op: string }).op))}`,
+				collection.name,
+			);
+		}
+	}
+}
+
+export function validateSort(collection: CollectionSchema, sort: SortKey[]): void {
+	const seen = new Set<string>();
+	for (const key of sort) {
+		validateField(collection, key.field);
+		if (seen.has(key.field)) {
+			queryInvalid(`duplicate sort field ${sanitizeIdentifier(key.field)}`, collection.name);
+		}
+		seen.add(key.field);
+		if (key.direction && key.direction !== 'asc' && key.direction !== 'desc') {
+			queryInvalid('sort direction must be asc or desc', collection.name);
+		}
+	}
+}
+
+export function validatePageSize(size: number): void {
+	if (!Number.isInteger(size) || size < 1 || size > Budgets.MAX_PAGE_SIZE) {
+		raise(DiagnosticCodes.PAGE_SIZE_INVALID, {
+			message: 'page size out of range',
+			detail: { limit: Budgets.MAX_PAGE_SIZE },
+		});
+	}
+}
+
+export function validateQuery(collection: CollectionSchema, query: Query | undefined): void {
+	if (!query) {
+		return;
+	}
+	if (query.filter) {
+		validateFilter(collection, query.filter);
+	}
+	if (query.sort) {
+		validateSort(collection, query.sort);
+	}
+	if (query.page) {
+		validatePageSize(query.page.size);
+	}
+}

package/src/schema/declare.ts

@@ -0,0 +1,45 @@
+/**
+ * Schema lookup helpers shared by both adapters.
+ *
+ * Declaring a field makes it queryable — it does not restrict what a record
+ * may contain. `isQueryable` is the single answer to "may a filter or sort
+ * reference this?", so both adapters reject the same field names (FR-034).
+ */
+
+import type { CollectionSchema, FieldDeclaration } from '../contract/schema';
+
+export type SchemaIndex = ReadonlyMap<string, CollectionSchema>;
+
+export function indexSchemas(collections: CollectionSchema[]): SchemaIndex {
+	return new Map(collections.map(collection => [collection.name, collection]));
+}
+
+export function fieldOf(
+	collection: CollectionSchema,
+	name: string,
+): FieldDeclaration | undefined {
+	return collection.fields?.find(field => field.name === name);
+}
+
+export function isQueryable(collection: CollectionSchema, name: string): boolean {
+	return fieldOf(collection, name) !== undefined;
+}
+
+export function hasSoftDelete(collection: CollectionSchema): boolean {
+	return collection.softDelete === true;
+}
+
+export function hasTimestamps(collection: CollectionSchema): boolean {
+	return collection.timestamps === true;
+}
+
+/** Column name for a projected queryable field. Prefixed to avoid colliding
+ * with the reserved columns (`id`, `payload`, `created_at`, ...). */
+export function projectedColumn(field: string): string {
+	return `f_${field}`;
+}
+
+/** Table name for a collection, prefixed for the same reason. */
+export function collectionTable(name: string): string {
+	return `c_${name}`;
+}

package/src/schema/validate-config.ts

@@ -0,0 +1,158 @@
+/**
+ * Configuration validation.
+ *
+ * Runs to completion before any write and before any migration executes
+ * (FR-006, FR-053). Order matters: scope first, then collections, then the
+ * migration chain — so a consumer fixes the outermost problem first rather
+ * than chasing a downstream symptom.
+ */
+
+import { Budgets, type DatabaseConfig } from '../contract/config';
+import { DiagnosticCodes } from '../contract/errors';
+import type { CollectionSchema } from '../contract/schema';
+import { raise } from '../diagnostics/errors';
+import { validateDescriptor } from '../scope/validate';
+
+const IDENTIFIER = /^[A-Za-z][A-Za-z0-9_]{0,62}$/;
+
+function configInvalid(message: string, detail?: Record<string, unknown>): never {
+	raise(DiagnosticCodes.CONFIG_INVALID, { message, detail });
+}
+
+function validateCollection(collection: CollectionSchema, seen: Set<string>): void {
+	if (!IDENTIFIER.test(collection.name)) {
+		configInvalid('collection name is not a valid identifier', {
+			collection: collection.name,
+		});
+	}
+	if (seen.has(collection.name)) {
+		configInvalid('duplicate collection name', { collection: collection.name });
+	}
+	seen.add(collection.name);
+
+	const fieldNames = new Set<string>();
+	for (const field of collection.fields ?? []) {
+		if (!IDENTIFIER.test(field.name)) {
+			configInvalid('field name is not a valid identifier', {
+				collection: collection.name,
+			});
+		}
+		if (fieldNames.has(field.name)) {
+			configInvalid('duplicate field name', { collection: collection.name });
+		}
+		fieldNames.add(field.name);
+	}
+
+	const indexNames = new Set<string>();
+	for (const index of collection.indexes ?? []) {
+		if (!IDENTIFIER.test(index.name)) {
+			configInvalid('index name is not a valid identifier', {
+				collection: collection.name,
+			});
+		}
+		if (indexNames.has(index.name)) {
+			configInvalid('duplicate index name', { collection: collection.name });
+		}
+		indexNames.add(index.name);
+		if (!Array.isArray(index.fields) || index.fields.length === 0) {
+			configInvalid('index declares no fields', { collection: collection.name });
+		}
+		for (const field of index.fields) {
+			if (!fieldNames.has(field)) {
+				// The whole point of declaring fields is that the package can
+				// tell a typo from a deliberate choice. Silently creating an
+				// index over a column that will never exist would turn a config
+				// bug into a mysterious full scan at runtime.
+				configInvalid('index references an undeclared field', {
+					collection: collection.name,
+				});
+			}
+		}
+	}
+}
+
+function validateMigrations(config: DatabaseConfig): void {
+	const migrations = config.migrations ?? [];
+	if (!Number.isInteger(config.schemaVersion) || config.schemaVersion < 1) {
+		raise(DiagnosticCodes.MIGRATION_CONFIG_INVALID, {
+			message: 'schemaVersion must be a positive integer',
+		});
+	}
+
+	const versions = new Set<number>();
+	for (const migration of migrations) {
+		if (!Number.isInteger(migration.version) || migration.version < 1) {
+			raise(DiagnosticCodes.MIGRATION_CONFIG_INVALID, {
+				message: 'migration version must be a positive integer',
+			});
+		}
+		if (versions.has(migration.version)) {
+			raise(DiagnosticCodes.MIGRATION_CONFIG_INVALID, {
+				message: 'duplicate migration version',
+				detail: { version: migration.version },
+			});
+		}
+		versions.add(migration.version);
+		if (typeof migration.migrate !== 'function') {
+			raise(DiagnosticCodes.MIGRATION_CONFIG_INVALID, {
+				message: 'migration has no migrate function',
+				detail: { version: migration.version },
+			});
+		}
+	}
+
+	// A chain must be able to carry a database from 1 to schemaVersion. A gap
+	// means some upgrading user has no path across it, which is worse than
+	// refusing to open.
+	for (let version = 1; version <= config.schemaVersion; version += 1) {
+		if (!versions.has(version)) {
+			raise(DiagnosticCodes.MIGRATION_CONFIG_INVALID, {
+				message: 'migration chain has a gap',
+				detail: { version },
+			});
+		}
+	}
+
+	for (const version of versions) {
+		if (version > config.schemaVersion) {
+			raise(DiagnosticCodes.MIGRATION_CONFIG_INVALID, {
+				message: 'migration version exceeds the declared schemaVersion',
+				detail: { version },
+			});
+		}
+	}
+}
+
+export function validateConfig(config: DatabaseConfig): void {
+	if (!config || typeof config !== 'object') {
+		configInvalid('database config is required');
+	}
+	if (typeof config.name !== 'string' || !IDENTIFIER.test(config.name)) {
+		configInvalid('database name is not a valid identifier');
+	}
+
+	validateDescriptor(config.scope);
+
+	if (!Array.isArray(config.collections) || config.collections.length === 0) {
+		configInvalid('at least one collection must be declared');
+	}
+	if (config.collections.length > Budgets.MAX_COLLECTIONS_PER_DATABASE) {
+		configInvalid('collection count exceeds the budget', {
+			count: config.collections.length,
+			limit: Budgets.MAX_COLLECTIONS_PER_DATABASE,
+		});
+	}
+
+	const seen = new Set<string>();
+	for (const collection of config.collections) {
+		validateCollection(collection, seen);
+	}
+
+	validateMigrations(config);
+
+	if (config.encryption && config.encryption.enabled) {
+		if (typeof config.encryption.keyProvider?.getKey !== 'function') {
+			configInvalid('encryption is enabled but no key provider was supplied');
+		}
+	}
+}

package/src/scope/hash.ts

@@ -0,0 +1,134 @@
+/**
+ * Scope key derivation.
+ *
+ * The directory a scope lives in is named by the SHA-256 digest of its
+ * canonical descriptor, never by the components themselves. FR-014 requires
+ * scope components be treated as sensitive, and a directory named after an
+ * email address puts that address in plaintext on disk — visible even when
+ * the database itself is encrypted, and carried into any crash report that
+ * includes a file path.
+ *
+ * Hashing also removes filesystem charset and length limits from the problem,
+ * which is what lets validation reject rather than sanitize (research.md R2).
+ *
+ * Implemented in pure TypeScript rather than over a native crypto peer so the
+ * scope layer stays importable from anywhere in the package, including the
+ * in-memory adapter running under Jest.
+ *
+ * Verified against Node's own SHA-256 in scope-resolution.test.ts — a wrong
+ * digest would silently merge or split scopes, so it is checked against a
+ * reference implementation rather than against a snapshot of this one.
+ */
+
+/* eslint-disable no-bitwise -- SHA-256 is defined in terms of bitwise operations. */
+
+const K = new Uint32Array([
+	0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4,
+	0xab1c5ed5, 0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe,
+	0x9bdc06a7, 0xc19bf174, 0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f,
+	0x4a7484aa, 0x5cb0a9dc, 0x76f988da, 0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7,
+	0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967, 0x27b70a85, 0x2e1b2138, 0x4d2c6dfc,
+	0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85, 0xa2bfe8a1, 0xa81a664b,
+	0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070, 0x19a4c116,
+	0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
+	0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7,
+	0xc67178f2,
+]);
+
+function rotr(value: number, bits: number): number {
+	return (value >>> bits) | (value << (32 - bits));
+}
+
+function utf8Bytes(input: string): Uint8Array {
+	const out: number[] = [];
+	for (let i = 0; i < input.length; i += 1) {
+		let codePoint = input.codePointAt(i)!;
+		if (codePoint > 0xffff) {
+			i += 1;
+		}
+		if (codePoint < 0x80) {
+			out.push(codePoint);
+		} else if (codePoint < 0x800) {
+			out.push(0xc0 | (codePoint >> 6), 0x80 | (codePoint & 0x3f));
+		} else if (codePoint < 0x10000) {
+			out.push(
+				0xe0 | (codePoint >> 12),
+				0x80 | ((codePoint >> 6) & 0x3f),
+				0x80 | (codePoint & 0x3f),
+			);
+		} else {
+			out.push(
+				0xf0 | (codePoint >> 18),
+				0x80 | ((codePoint >> 12) & 0x3f),
+				0x80 | ((codePoint >> 6) & 0x3f),
+				0x80 | (codePoint & 0x3f),
+			);
+		}
+	}
+	return Uint8Array.from(out);
+}
+
+export function utf8ByteLength(input: string): number {
+	return utf8Bytes(input).length;
+}
+
+export function sha256Hex(input: string): string {
+	const bytes = utf8Bytes(input);
+	const bitLength = bytes.length * 8;
+	const paddedLength = (((bytes.length + 9) >> 6) + 1) << 6;
+	const padded = new Uint8Array(paddedLength);
+	padded.set(bytes);
+	padded[bytes.length] = 0x80;
+
+	const view = new DataView(padded.buffer);
+	view.setUint32(paddedLength - 8, Math.floor(bitLength / 0x100000000), false);
+	view.setUint32(paddedLength - 4, bitLength >>> 0, false);
+
+	const h = new Uint32Array([
+		0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab,
+		0x5be0cd19,
+	]);
+	const w = new Uint32Array(64);
+
+	for (let offset = 0; offset < paddedLength; offset += 64) {
+		for (let i = 0; i < 16; i += 1) {
+			w[i] = view.getUint32(offset + i * 4, false);
+		}
+		for (let i = 16; i < 64; i += 1) {
+			const s0 = rotr(w[i - 15]!, 7) ^ rotr(w[i - 15]!, 18) ^ (w[i - 15]! >>> 3);
+			const s1 = rotr(w[i - 2]!, 17) ^ rotr(w[i - 2]!, 19) ^ (w[i - 2]! >>> 10);
+			w[i] = (w[i - 16]! + s0 + w[i - 7]! + s1) >>> 0;
+		}
+
+		let [a, b, c, d, e, f, g, hh] = [h[0]!, h[1]!, h[2]!, h[3]!, h[4]!, h[5]!, h[6]!, h[7]!];
+
+		for (let i = 0; i < 64; i += 1) {
+			const S1 = rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25);
+			const ch = (e & f) ^ (~e & g);
+			const temp1 = (hh + S1 + ch + K[i]! + w[i]!) >>> 0;
+			const S0 = rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22);
+			const maj = (a & b) ^ (a & c) ^ (b & c);
+			const temp2 = (S0 + maj) >>> 0;
+
+			hh = g;
+			g = f;
+			f = e;
+			e = (d + temp1) >>> 0;
+			d = c;
+			c = b;
+			b = a;
+			a = (temp1 + temp2) >>> 0;
+		}
+
+		h[0] = (h[0]! + a) >>> 0;
+		h[1] = (h[1]! + b) >>> 0;
+		h[2] = (h[2]! + c) >>> 0;
+		h[3] = (h[3]! + d) >>> 0;
+		h[4] = (h[4]! + e) >>> 0;
+		h[5] = (h[5]! + f) >>> 0;
+		h[6] = (h[6]! + g) >>> 0;
+		h[7] = (h[7]! + hh) >>> 0;
+	}
+
+	return Array.from(h, value => value.toString(16).padStart(8, '0')).join('');
+}

package/src/scope/normalize.ts

@@ -0,0 +1,90 @@
+/**
+ * Scope descriptor normalization.
+ *
+ * The package normalizes and validates; it never repairs. A component it
+ * cannot represent safely is an error (FR-013), because silently sanitizing
+ * one is how two different descriptors end up sharing a directory — which
+ * would be a cross-scope leak dressed up as a convenience.
+ */
+
+import type { ScopeDescriptor, ScopeKind } from '../contract/scope';
+
+/**
+ * Separates components in the canonical form.
+ *
+ * NUL rather than a printable character: a component containing the separator
+ * could forge another descriptor's canonical string, and every printable
+ * candidate occurs in legitimate identity data. Tenant names contain spaces,
+ * identifiers contain colons and slashes, emails contain "@" and ".". NUL
+ * occurs in none of them, so reserving it costs consumers nothing.
+ */
+export const COMPONENT_SEPARATOR = '\u0000';
+
+/**
+ * Control characters are rejected wholesale rather than only the separator.
+ * They have no place in an identity component, and they would be trouble in a
+ * log line or a diagnostic even where they could not forge a canonical
+ * string.
+ */
+// eslint-disable-next-line no-control-regex
+export const CONTROL_CHARACTER = /[\u0000-\u001f\u007f]/;
+
+export const MAX_COMPONENT_BYTES = 512;
+
+/** Fixed order, so the canonical form is stable across callers. */
+export const COMPONENT_ORDER = [
+	'kind',
+	'id',
+	'tenant',
+	'app',
+	'environment',
+	'namespace',
+] as const;
+
+export const SCOPE_KINDS: readonly ScopeKind[] = [
+	'guest',
+	'identity',
+	'tenant',
+	'workspace',
+	'custom',
+];
+
+/**
+ * NFC, trimmed, case preserved.
+ *
+ * Case is preserved deliberately: the package does not know whether a
+ * consumer's identity system is case-sensitive, and folding case would merge
+ * two scopes the app considers distinct.
+ */
+export function normalizeComponent(value: string): string {
+	return value.normalize('NFC').trim();
+}
+
+export type NormalizedScope = {
+	kind: ScopeKind;
+	components: Record<string, string>;
+	canonical: string;
+};
+
+/** Normalize without validating. Callers must validate first. */
+export function normalizeDescriptor(descriptor: ScopeDescriptor): NormalizedScope {
+	const components: Record<string, string> = {};
+	const parts: string[] = [];
+
+	for (const key of COMPONENT_ORDER) {
+		const raw = descriptor[key as keyof ScopeDescriptor];
+		if (typeof raw !== 'string' || raw.length === 0) {
+			parts.push('');
+			continue;
+		}
+		const normalized = normalizeComponent(raw);
+		components[key] = normalized;
+		parts.push(normalized);
+	}
+
+	return {
+		kind: descriptor.kind,
+		components,
+		canonical: parts.join(COMPONENT_SEPARATOR),
+	};
+}

package/src/scope/validate.ts

@@ -0,0 +1,83 @@
+/**
+ * Scope validation and resolution.
+ *
+ * Validate, never repair (FR-013). The package never invents, derives, or
+ * defaults an identity of its own (FR-008).
+ */
+
+import { DiagnosticCodes } from '../contract/errors';
+import type { ResolvedScope, ScopeDescriptor } from '../contract/scope';
+import { raise } from '../diagnostics/errors';
+import { sha256Hex, utf8ByteLength } from './hash';
+import {
+	COMPONENT_ORDER,
+	CONTROL_CHARACTER,
+	MAX_COMPONENT_BYTES,
+	SCOPE_KINDS,
+	normalizeComponent,
+	normalizeDescriptor,
+} from './normalize';
+
+function invalid(reason: string): never {
+	// The reason names the *component*, never its value — naming the value
+	// would put a scope component into an error, which FR-014 forbids.
+	raise(DiagnosticCodes.INVALID_SCOPE, { message: reason });
+}
+
+function validateComponent(key: string, raw: unknown): void {
+	if (raw === undefined || raw === null) {
+		return;
+	}
+	if (typeof raw !== 'string') {
+		invalid(`scope component ${key} must be a string`);
+	}
+	const normalized = normalizeComponent(raw);
+	if (normalized.length === 0) {
+		invalid(`scope component ${key} is empty after normalization`);
+	}
+	if (CONTROL_CHARACTER.test(normalized)) {
+		invalid(`scope component ${key} contains a control character`);
+	}
+	if (utf8ByteLength(normalized) > MAX_COMPONENT_BYTES) {
+		invalid(`scope component ${key} exceeds the maximum length`);
+	}
+}
+
+export function validateDescriptor(descriptor: ScopeDescriptor | undefined | null): void {
+	if (!descriptor || typeof descriptor !== 'object') {
+		invalid('scope descriptor is required');
+	}
+	if (!SCOPE_KINDS.includes(descriptor.kind)) {
+		invalid('scope kind is not recognised');
+	}
+
+	// Guest is the one kind with no identity, by design: an anonymous session
+	// still gets its own isolated scope rather than sharing a default.
+	if (descriptor.kind !== 'guest') {
+		const id = descriptor.id;
+		if (typeof id !== 'string' || normalizeComponent(id).length === 0) {
+			invalid('scope id is required for this kind');
+		}
+	}
+
+	for (const key of COMPONENT_ORDER) {
+		if (key === 'kind') {
+			continue;
+		}
+		validateComponent(key, descriptor[key as keyof ScopeDescriptor]);
+	}
+}
+
+/**
+ * Deterministic: identical descriptors always resolve to the same scope, and
+ * descriptors differing in any component always resolve to different ones
+ * (FR-010).
+ */
+export function resolveScope(descriptor: ScopeDescriptor): ResolvedScope {
+	validateDescriptor(descriptor);
+	const normalized = normalizeDescriptor(descriptor);
+	return {
+		key: sha256Hex(normalized.canonical),
+		kind: descriptor.kind,
+	};
+}