@dxos/keys 0.8.4-staging.ac66bdf99f → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/keys",
-  "version": "0.8.4-staging.ac66bdf99f",
+  "version": "0.9.0",
   "description": "Key utils and definitions.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -8,7 +8,7 @@
     "type": "git",
     "url": "https://github.com/dxos/dxos"
   },
-  "license": "MIT",
+  "license": "FSL-1.1-Apache-2.0",
   "author": "DXOS.org",
   "sideEffects": false,
   "type": "module",
@@ -21,26 +21,23 @@
     }
   },
   "types": "dist/types/src/index.d.ts",
-  "typesVersions": {
-    "*": {}
-  },
   "files": [
     "dist",
     "src"
   ],
   "dependencies": {
     "ulidx": "^2.3.0",
-    "@dxos/invariant": "0.8.4-staging.ac66bdf99f",
-    "@dxos/debug": "0.8.4-staging.ac66bdf99f",
-    "@dxos/node-std": "0.8.4-staging.ac66bdf99f"
+    "@dxos/debug": "0.9.0",
+    "@dxos/node-std": "0.9.0",
+    "@dxos/invariant": "0.9.0"
   },
   "devDependencies": {
     "base32-decode": "^1.0.0",
     "base32-encode": "^2.0.0",
-    "effect": "3.20.0"
+    "effect": "3.21.3"
   },
   "peerDependencies": {
-    "effect": "3.20.0"
+    "effect": "3.21.3"
   },
   "publishConfig": {
     "access": "public"

package/src/DXN.test.ts

@@ -0,0 +1,85 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import * as DXN from './DXN';
+
+describe('DXN.isDXN', () => {
+  test('accepts new-format DXNs', ({ expect }) => {
+    expect(DXN.isDXN('dxn:org.dxos.type.calendar')).toBe(true);
+    expect(DXN.isDXN('dxn:org.dxos.type.calendar:1.0.0')).toBe(true);
+    expect(DXN.isDXN('dxn:com.alice.type.contact:2.1.0')).toBe(true);
+    expect(DXN.isDXN('dxn:org.dxos.plugin.markdown')).toBe(true);
+    expect(DXN.isDXN('dxn:org.dxos.type.calendarEvent')).toBe(true);
+  });
+
+  test('rejects non-DXN strings', ({ expect }) => {
+    expect(DXN.isDXN('echo://space/object')).toBe(false);
+    expect(DXN.isDXN('https://example.com')).toBe(false);
+    expect(DXN.isDXN('')).toBe(false);
+    expect(DXN.isDXN(42)).toBe(false);
+  });
+});
+
+describe('DXN.make', () => {
+  test('produces unversioned DXN', ({ expect }) => {
+    expect(DXN.make('org.dxos.type.calendar')).toBe('dxn:org.dxos.type.calendar');
+  });
+
+  test('produces versioned DXN', ({ expect }) => {
+    expect(DXN.make('org.dxos.type.calendar', '1.0.0')).toBe('dxn:org.dxos.type.calendar:1.0.0');
+  });
+
+  test('throws on invalid NSID', ({ expect }) => {
+    expect(() => DXN.make('not-a-valid-nsid')).toThrow();
+    expect(() => DXN.make('com.example.type.registry-entry')).toThrow();
+    expect(() => DXN.make('com.example.type.registry-entry', '0.1.0')).toThrow();
+  });
+});
+
+describe('DXN.tryMake', () => {
+  test('parses new-format DXN strings', ({ expect }) => {
+    expect(DXN.tryMake('dxn:org.dxos.type.calendar')).toBe('dxn:org.dxos.type.calendar');
+    expect(DXN.tryMake('dxn:org.dxos.type.calendar:1.0.0')).toBe('dxn:org.dxos.type.calendar:1.0.0');
+  });
+
+  test('returns undefined on invalid input', ({ expect }) => {
+    expect(DXN.tryMake('not-a-dxn')).toBeUndefined();
+    expect(DXN.tryMake('dxn:invalid')).toBeUndefined();
+  });
+
+  test('rejects hyphens in the last NSID segment (must be camelCase)', ({ expect }) => {
+    expect(DXN.tryMake('dxn:com.example.type.registry-entry')).toBeUndefined();
+    expect(DXN.tryMake('dxn:com.example.type.registry-entry:0.1.0')).toBeUndefined();
+  });
+
+  test('accepts hyphens in middle segments but not the last', ({ expect }) => {
+    expect(DXN.tryMake('dxn:org.dxos.relation.plugin-crm.profileOf')).toBe(
+      'dxn:org.dxos.relation.plugin-crm.profileOf',
+    );
+  });
+});
+
+describe('DXN.getName', () => {
+  test('extracts NSID from new-format DXN', ({ expect }) => {
+    expect(DXN.getName(DXN.make('org.dxos.type.calendar'))).toBe('org.dxos.type.calendar');
+    expect(DXN.getName(DXN.make('org.dxos.plugin.markdown'))).toBe('org.dxos.plugin.markdown');
+  });
+
+  test('extracts NSID from versioned DXN (without version)', ({ expect }) => {
+    expect(DXN.getName(DXN.make('org.dxos.type.calendar', '1.0.0'))).toBe('org.dxos.type.calendar');
+  });
+});
+
+describe('DXN.getVersion', () => {
+  test('returns version from versioned DXN', ({ expect }) => {
+    expect(DXN.getVersion(DXN.make('org.dxos.type.calendar', '1.0.0'))).toBe('1.0.0');
+    expect(DXN.getVersion(DXN.make('com.alice.type.contact', '2.1.0'))).toBe('2.1.0');
+  });
+
+  test('returns undefined for unversioned DXN', ({ expect }) => {
+    expect(DXN.getVersion(DXN.make('org.dxos.type.calendar'))).toBeUndefined();
+  });
+});

package/src/DXN.ts

@@ -0,0 +1,104 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+// @import-as-namespace
+
+import * as Schema from 'effect/Schema';
+
+import type * as URI from './URI';
+
+/**
+ * Full DXN regex per spec: `dxn:<nsid>[:<version>]`.
+ * Middle segments may contain hyphens; the final segment must be camelCase
+ * (alphanumeric, leading letter — no hyphens or underscores).
+ */
+const DXN_SPEC_REGEXP =
+  /^dxn:[a-zA-Z]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(\.[a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)+(\.[a-zA-Z][a-zA-Z0-9]{0,62})(:\d+\.\d+\.\d+)?$/;
+
+/**
+ * DXN names a resource (type, plugin, capability, etc.).
+ *
+ * Format: `dxn:<nsid>[:<version>]` where NSID is an atproto-style dotted name.
+ *
+ * @example
+ * ```
+ * dxn:org.dxos.type.calendar
+ * dxn:org.dxos.type.calendar:1.0.0
+ * dxn:org.dxos.plugin.markdown
+ * ```
+ */
+export type DXN = URI.URI & { readonly __DXN: unique symbol };
+
+/**
+ * Cheap prefix check — does not validate the full DXN grammar.
+ * Sufficient for narrowing a URI to a DXN.
+ */
+export const isDXN = (value: unknown): value is DXN => typeof value === 'string' && value.startsWith('dxn:');
+
+/**
+ * Constructs a DXN from an NSID (and optional version). Throws if the result
+ * is not a valid DXN. Use `tryMake` for non-throwing string parsing.
+ *
+ * @example make('org.dxos.type.calendar') → 'dxn:org.dxos.type.calendar'
+ * @example make('org.dxos.type.calendar', '1.0.0') → 'dxn:org.dxos.type.calendar:1.0.0'
+ */
+export const make = (nsid: string, version?: string): DXN =>
+  parse(version != null ? `dxn:${nsid}:${version}` : `dxn:${nsid}`);
+
+/**
+ * Parses a full DXN string. Returns undefined on failure.
+ */
+export const tryMake = (dxn: string): DXN | undefined => {
+  try {
+    return parse(dxn);
+  } catch {
+    return undefined;
+  }
+};
+
+// Internal — full-grammar validator. Callers outside this module should use
+// `make(nsid, version?)` or `tryMake(dxn)`.
+const parse = (dxn: string): DXN => {
+  if (typeof dxn === 'string' && DXN_SPEC_REGEXP.test(dxn)) {
+    return dxn as DXN;
+  }
+  throw new Error(`Invalid DXN: ${dxn}`);
+};
+
+/**
+ * Returns the NSID portion of a DXN (the part after `dxn:` and before optional `:<version>`).
+ * @example getName('dxn:org.dxos.type.calendar:1.0.0') → 'org.dxos.type.calendar'
+ */
+export const getName = (dxn: DXN): string => {
+  const match = /^dxn:([^:]+)/.exec(dxn);
+  if (!match) {
+    throw new Error(`Invalid DXN: ${dxn}`);
+  }
+  return match[1];
+};
+
+/**
+ * Returns the semver version from a versioned DXN, or undefined if unversioned.
+ * @example getVersion('dxn:org.dxos.type.calendar:1.0.0') → '1.0.0'
+ */
+export const getVersion = (dxn: DXN): string | undefined => {
+  const match = /^dxn:[^:]+:(\d+\.\d+\.\d+)$/.exec(dxn);
+  return match?.[1];
+};
+
+/**
+ * Effect Schema for DXN validation.
+ */
+// Identity-encoded schema (`Schema<DXN, DXN>`) so consumers can refine generic schemas
+// without the encode/decode types diverging. `Schema.filter` produces a refinement with
+// `Encoded = string`; we narrow the encoded form too with `as unknown as` since the runtime
+// representation is identical (a branded string).
+const Schema_: Schema.Schema<DXN, DXN> = Schema.String.pipe(
+  Schema.filter((value): value is DXN => isDXN(value), { message: () => 'Invalid DXN' }),
+  Schema.annotations({
+    title: 'DXN',
+    description: 'DXN URI: dxn:<nsid>[:<version>]',
+  }),
+) as unknown as Schema.Schema<DXN, DXN>;
+export { Schema_ as Schema };

package/src/EID.test.ts

@@ -0,0 +1,147 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import * as EID from './EID';
+import { EntityId } from './entity-id';
+import { SpaceId } from './space-id';
+
+const SPACE = SpaceId.random();
+const OBJECT = EntityId.random();
+const OBJECT2 = EntityId.random();
+
+describe('EID.make', () => {
+  test('produces qualified echo URI from spaceId + objectId', ({ expect }) => {
+    expect(EID.make({ spaceId: SPACE, entityId: OBJECT })).toBe(`echo://${SPACE}/${OBJECT}`);
+  });
+
+  test('produces local echo URI from objectId only', ({ expect }) => {
+    expect(EID.make({ entityId: OBJECT })).toBe(`echo:/${OBJECT}`);
+  });
+
+  test('produces space-only echo URI from spaceId only', ({ expect }) => {
+    expect(EID.make({ spaceId: SPACE })).toBe(`echo://${SPACE}`);
+  });
+
+  test('throws when neither id is provided', ({ expect }) => {
+    expect(() => EID.make({})).toThrow();
+  });
+});
+
+describe('EID.isEID', () => {
+  test('accepts new format', ({ expect }) => {
+    expect(EID.isEID(`echo://${SPACE}/${OBJECT}`)).toBe(true);
+    expect(EID.isEID(`echo:/${OBJECT}`)).toBe(true);
+    expect(EID.isEID(`echo:///${OBJECT}`)).toBe(true);
+    expect(EID.isEID(`echo://${SPACE}`)).toBe(true);
+  });
+
+  test('rejects non-echo strings', ({ expect }) => {
+    expect(EID.isEID('dxn:org.dxos.type.calendar')).toBe(false);
+    expect(EID.isEID(`dxn:echo:@:${OBJECT}`)).toBe(false);
+    expect(EID.isEID(`dxn:queue:data:${SPACE}:${OBJECT}`)).toBe(false);
+    expect(EID.isEID('https://example.com')).toBe(false);
+    expect(EID.isEID('')).toBe(false);
+    expect(EID.isEID(42)).toBe(false);
+  });
+});
+
+describe('EID.parse', () => {
+  test('passes through canonical format unchanged', ({ expect }) => {
+    const id = `echo://${SPACE}/${OBJECT}`;
+    expect(EID.parse(id)).toBe(id);
+  });
+
+  test('throws on invalid input', ({ expect }) => {
+    expect(() => EID.parse('dxn:org.dxos.type.calendar')).toThrow();
+    expect(() => EID.parse(`dxn:echo:@:${OBJECT}`)).toThrow();
+    expect(() => EID.parse(`dxn:queue:data:${SPACE}:${OBJECT}`)).toThrow();
+    expect(() => EID.parse('not-a-uri')).toThrow();
+    expect(() => EID.parse('echo:')).toThrow();
+    expect(() => EID.parse('echo://')).toThrow();
+  });
+});
+
+describe('EID.tryParse', () => {
+  test('returns undefined on failure instead of throwing', ({ expect }) => {
+    expect(EID.tryParse('not-a-uri')).toBeUndefined();
+    expect(EID.tryParse(`echo:/${OBJECT}`)).toBe(`echo:/${OBJECT}`);
+  });
+});
+
+describe('EID.getSpaceId', () => {
+  test('returns spaceId from qualified ref', ({ expect }) => {
+    expect(EID.getSpaceId(EID.make({ spaceId: SPACE, entityId: OBJECT }))).toBe(SPACE);
+  });
+
+  test('returns spaceId from space-only ref', ({ expect }) => {
+    expect(EID.getSpaceId(EID.make({ spaceId: SPACE }))).toBe(SPACE);
+  });
+
+  test('returns undefined for local ref', ({ expect }) => {
+    expect(EID.getSpaceId(EID.make({ entityId: OBJECT }))).toBeUndefined();
+    expect(EID.getSpaceId(EID.parse(`echo:///${OBJECT}`))).toBeUndefined();
+  });
+});
+
+describe('EID.getEntityId', () => {
+  test('returns objectId from qualified ref', ({ expect }) => {
+    expect(EID.getEntityId(EID.make({ spaceId: SPACE, entityId: OBJECT }))).toBe(OBJECT);
+  });
+
+  test('returns objectId from local ref', ({ expect }) => {
+    expect(EID.getEntityId(EID.make({ entityId: OBJECT }))).toBe(OBJECT);
+    expect(EID.getEntityId(EID.parse(`echo:///${OBJECT}`))).toBe(OBJECT);
+  });
+
+  test('returns undefined for space-only ref', ({ expect }) => {
+    expect(EID.getEntityId(EID.make({ spaceId: SPACE }))).toBeUndefined();
+  });
+});
+
+describe('EID.isLocal', () => {
+  test('returns true for local refs', ({ expect }) => {
+    expect(EID.isLocal(EID.make({ entityId: OBJECT }))).toBe(true);
+    expect(EID.isLocal(EID.parse(`echo:///${OBJECT}`))).toBe(true);
+  });
+
+  test('returns false for qualified refs', ({ expect }) => {
+    expect(EID.isLocal(EID.make({ spaceId: SPACE, entityId: OBJECT }))).toBe(false);
+    expect(EID.isLocal(EID.make({ spaceId: SPACE }))).toBe(false);
+  });
+});
+
+describe('EID.equals', () => {
+  test('returns true for identical refs', ({ expect }) => {
+    const id = EID.make({ spaceId: SPACE, entityId: OBJECT });
+    expect(EID.equals(id, id)).toBe(true);
+  });
+
+  test('returns false for different refs', ({ expect }) => {
+    const a = EID.make({ spaceId: SPACE, entityId: OBJECT });
+    const b = EID.make({ spaceId: SPACE, entityId: OBJECT2 });
+    expect(EID.equals(a, b)).toBe(false);
+  });
+});
+
+describe('EID.toLocal', () => {
+  test('drops the space from a qualified ref', ({ expect }) => {
+    expect(EID.toLocal(EID.make({ spaceId: SPACE, entityId: OBJECT }))).toBe(EID.make({ entityId: OBJECT }));
+  });
+
+  test('leaves a local ref unchanged', ({ expect }) => {
+    expect(EID.toLocal(EID.make({ entityId: OBJECT }))).toBe(EID.make({ entityId: OBJECT }));
+  });
+
+  test('collapses qualified and bare refs to the same value', ({ expect }) => {
+    expect(EID.toLocal(EID.make({ spaceId: SPACE, entityId: OBJECT }))).toBe(
+      EID.toLocal(EID.make({ entityId: OBJECT })),
+    );
+  });
+
+  test('returns space-only refs unchanged', ({ expect }) => {
+    expect(EID.toLocal(EID.make({ spaceId: SPACE }))).toBe(EID.make({ spaceId: SPACE }));
+  });
+});

package/src/EID.ts

@@ -0,0 +1,151 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+// @import-as-namespace
+
+import * as Schema from 'effect/Schema';
+
+import type { EntityId } from './entity-id';
+import type { SpaceId } from './space-id';
+import type * as URI from './URI';
+
+// Canonical-form regex covering all three EID shapes.
+//   echo://<spaceId>/<objectId>
+//   echo://<spaceId>
+//   echo:/<objectId>      (local)
+//   echo:///<objectId>    (local, alt form)
+const ECHO_URI_REGEXP = /^echo:(?:\/\/[^/]+(?:\/[^/]+)?|(?:\/\/\/|\/)[^/]+)$/;
+
+// Sub-patterns used for extraction.
+const QUALIFIED_RE = /^echo:\/\/([^/]+)\/([^/]+)$/;
+const SPACE_ONLY_RE = /^echo:\/\/([^/]+)$/;
+const LOCAL_RE = /^echo:(?:\/\/\/|\/)([^/]+)$/;
+
+/**
+ * Addresses an ECHO object or space. Uses the `echo:` URI scheme.
+ *
+ * @example
+ * ```
+ * echo://BA25QRC2FEWCSAMRP4RZL65LWJ7352CKE/01J00J9B45YHYSGZQTQMSKMGJ6
+ * echo:/01J00J9B45YHYSGZQTQMSKMGJ6
+ * echo://BA25QRC2FEWCSAMRP4RZL65LWJ7352CKE
+ * ```
+ */
+export type EID = URI.URI & { readonly __EID: unique symbol };
+
+/**
+ * Returns true if the value is a valid EID.
+ */
+export const isEID = (value: unknown): value is EID => typeof value === 'string' && value.startsWith('echo:');
+
+/**
+ * Parses a string to EID. Throws if the string is not a valid canonical `echo:` EID.
+ */
+export const parse = (uri: string): EID => {
+  if (!ECHO_URI_REGEXP.test(uri)) {
+    throw new Error(`Invalid EID: ${uri}`);
+  }
+  return uri as EID;
+};
+
+/**
+ * Like `parse` but returns undefined on failure instead of throwing.
+ */
+export const tryParse = (uri: string): EID | undefined => {
+  try {
+    return parse(uri);
+  } catch {
+    return undefined;
+  }
+};
+
+/**
+ * Constructs an EID. Validates the result via `parse`.
+ *
+ * - `{ spaceId, entityId }` → `echo://<spaceId>/<entityId>` (fully qualified)
+ * - `{ entityId }`          → `echo:/<entityId>` (local — current space)
+ * - `{ spaceId }`           → `echo://<spaceId>` (space-only)
+ *
+ * Throws if neither id is provided, or if the result is not a valid EID.
+ */
+export const make = ({ spaceId, entityId }: { spaceId?: SpaceId; entityId?: EntityId }): EID => {
+  let raw: string;
+  if (spaceId != null && entityId != null) {
+    raw = `echo://${spaceId}/${entityId}`;
+  } else if (entityId != null) {
+    raw = `echo:/${entityId}`;
+  } else if (spaceId != null) {
+    raw = `echo://${spaceId}`;
+  } else {
+    throw new Error('EID.make requires at least one of spaceId or entityId');
+  }
+  return parse(raw);
+};
+
+/**
+ * Returns the SpaceId from a fully-qualified EID, or undefined for local refs.
+ */
+export const getSpaceId = (uri: EID): SpaceId | undefined => {
+  const normalized = parse(uri);
+  const match = QUALIFIED_RE.exec(normalized) ?? SPACE_ONLY_RE.exec(normalized);
+  return match?.[1] as SpaceId | undefined;
+};
+
+/**
+ * Returns the EntityId from an EID, or undefined for space-only refs.
+ */
+export const getEntityId = (uri: EID): EntityId | undefined => {
+  const normalized = parse(uri);
+  const qualMatch = QUALIFIED_RE.exec(normalized);
+  if (qualMatch) {
+    return qualMatch[2] as EntityId;
+  }
+  const localMatch = LOCAL_RE.exec(normalized);
+  return localMatch?.[1] as EntityId | undefined;
+};
+
+/**
+ * Returns true if the EID is a local reference (no authority/space).
+ */
+export const isLocal = (uri: EID): boolean => {
+  const normalized = parse(uri);
+  return LOCAL_RE.test(normalized);
+};
+
+/**
+ * Returns the local (space-less) form of an EID, dropping any space authority. A space-qualified EID and a
+ * bare one for the same entity collapse to the same value; space-only EIDs (no entity id) are returned
+ * unchanged.
+ *
+ * Entity ids are unique within a space, so the local form is a safe key/comparison basis only among EIDs
+ * already known to belong to one space (e.g. a single space's reverse-ref index). Do NOT use it to decide
+ * whether two arbitrary EIDs name the same entity across spaces.
+ */
+export const toLocal = (uri: EID): EID => {
+  const entityId = getEntityId(uri);
+  return entityId != null ? make({ entityId }) : parse(uri);
+};
+
+/**
+ * Returns true if the two EIDs refer to the same object, normalizing both first.
+ */
+export const equals = (a: EID, b: EID): boolean => parse(a) === parse(b);
+
+/**
+ * Effect Schema for EID validation.
+ */
+// Identity-encoded schema (`Schema<EID, EID>`) so consumers can refine generic
+// schemas without the encode/decode types diverging. `Schema.filter` produces a refinement
+// with `Encoded = string`; we narrow the encoded form too with `as unknown as` since the
+// runtime representation is identical (a branded string).
+const Schema_: Schema.Schema<EID, EID> = Schema.String.pipe(
+  Schema.filter((value): value is EID => isEID(value), {
+    message: () => 'Invalid EID: must start with echo:',
+  }),
+  Schema.annotations({
+    title: 'EID',
+    description: 'ECHO object/space URI: echo://<spaceId>[/<objectId>] or echo:/<objectId>',
+  }),
+) as unknown as Schema.Schema<EID, EID>;
+export { Schema_ as Schema };

package/src/URI.ts

@@ -0,0 +1,35 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+// @import-as-namespace
+
+import * as Schema from 'effect/Schema';
+
+/**
+ * Branded string type for any URI.
+ * Base type for more specific URI schemes like DXN and EID.
+ */
+export type URI = string & { readonly __URI: unique symbol };
+
+/**
+ * Brand a string as an opaque URI without validating the scheme.
+ * For typed construction prefer `DXN.make`, `EID.make`, etc.
+ */
+export const make = (uri: string): URI => uri as URI;
+
+/**
+ * Returns true if the value looks like a URI (string with a scheme prefix).
+ */
+export const isURI = (value: unknown): value is URI =>
+  typeof value === 'string' && /^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(value);
+
+/**
+ * Effect Schema for any URI string.
+ */
+// Identity-encoded `Schema<URI, URI>` so consumers can refine without the encode/decode
+// types diverging. Runtime representation is identical (a branded string).
+const Schema_: Schema.Schema<URI, URI> = Schema.String.pipe(
+  Schema.filter((value): value is URI => isURI(value), { message: () => 'Invalid URI' }),
+) as unknown as Schema.Schema<URI, URI>;
+export { Schema_ as Schema };

package/src/entity-id.test.ts

@@ -0,0 +1,73 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test, vi } from 'vitest';
+
+import { EntityId } from './entity-id';
+
+describe('EntityId', () => {
+  describe('isValid', () => {
+    test('accepts a randomly-generated id', ({ expect }) => {
+      const id = EntityId.random();
+      expect(EntityId.isValid(id)).toBe(true);
+    });
+
+    test('rejects malformed strings', ({ expect }) => {
+      expect(EntityId.isValid('')).toBe(false);
+      expect(EntityId.isValid('not-a-ulid')).toBe(false);
+      // Wrong leading char (must be 0-7).
+      expect(EntityId.isValid('8AAAAAAAAAAAAAAAAAAAAAAAAA')).toBe(false);
+    });
+  });
+
+  describe('deterministic', () => {
+    test('returns the same id for the same seeds', ({ expect }) => {
+      const first = EntityId.deterministic('org.dxos.type.person', '0.1.0');
+      const second = EntityId.deterministic('org.dxos.type.person', '0.1.0');
+      expect(first).toBe(second);
+    });
+
+    test('returns different ids for different seeds', ({ expect }) => {
+      const person = EntityId.deterministic('org.dxos.type.person', '0.1.0');
+      const organization = EntityId.deterministic('org.dxos.type.organization', '0.1.0');
+      expect(person).not.toBe(organization);
+    });
+
+    test('returns different ids when version differs', ({ expect }) => {
+      const v1 = EntityId.deterministic('org.dxos.type.person', '0.1.0');
+      const v2 = EntityId.deterministic('org.dxos.type.person', '0.2.0');
+      expect(v1).not.toBe(v2);
+    });
+
+    test('output passes EntityId.isValid', ({ expect }) => {
+      const id = EntityId.deterministic('org.dxos.type.person', '0.1.0');
+      expect(EntityId.isValid(id)).toBe(true);
+    });
+
+    test('accepts numeric seeds', ({ expect }) => {
+      const id = EntityId.deterministic('prefix', 42, 'suffix');
+      expect(EntityId.isValid(id)).toBe(true);
+    });
+
+    test('does not call crypto.getRandomValues', ({ expect }) => {
+      // Workerd forbids `crypto.getRandomValues()` in global scope; deterministic() must therefore
+      // never reach for the platform RNG. Verify by spying on the global.
+      const spy = vi.spyOn(globalThis.crypto, 'getRandomValues');
+      try {
+        EntityId.deterministic('org.dxos.type.person', '0.1.0');
+        expect(spy).not.toHaveBeenCalled();
+      } finally {
+        spy.mockRestore();
+      }
+    });
+
+    test('seed-component separator avoids collisions across adjacent inputs', ({ expect }) => {
+      // ('ab', 'c') vs ('a', 'bc') must hash differently — guards against naive
+      // concatenation that would conflate adjacent string seeds.
+      const left = EntityId.deterministic('ab', 'c');
+      const right = EntityId.deterministic('a', 'bc');
+      expect(left).not.toBe(right);
+    });
+  });
+});