@starkeep/protocol-primitives 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,316 @@
+import * as v from 'valibot';
+
+type StarkeepId = string & {
+    readonly __brand: unique symbol;
+};
+declare function createStarkeepId(value: string): StarkeepId;
+declare function isStarkeepId(value: unknown): value is StarkeepId;
+
+declare function generateId(): StarkeepId;
+declare function generateIdAt(timestamp: number): StarkeepId;
+
+interface HLCTimestamp {
+    readonly wallTime: number;
+    readonly counter: number;
+    readonly nodeId: string;
+}
+interface HLCClock {
+    now(): HLCTimestamp;
+    send(): HLCTimestamp;
+    receive(remote: HLCTimestamp): HLCTimestamp;
+}
+
+interface ClockState {
+    wallTime: number;
+    counter: number;
+}
+interface ClockOptions {
+    nodeId: string;
+    wallClockFunction?: () => number;
+    /**
+     * Pre-seed the clock from persisted state so a post-restart HLC never
+     * emits a timestamp earlier than one the node already sent.
+     */
+    initialState?: ClockState;
+    /**
+     * Invoked on every state change. Callers typically debounce and persist
+     * to a SyncStateStore.
+     */
+    onTick?: (state: ClockState) => void;
+}
+declare function createHLCClock(options: ClockOptions): HLCClock;
+
+/** Identity element for HLC ordering. Useful as a default watermark / "never seen". */
+declare const ZERO_HLC: HLCTimestamp;
+declare function compareHLC(a: HLCTimestamp, b: HLCTimestamp): -1 | 0 | 1;
+declare function maxHLC(a: HLCTimestamp, b: HLCTimestamp): HLCTimestamp;
+
+declare function serializeHLC(timestamp: HLCTimestamp): string;
+declare function deserializeHLC(serializedString: string): HLCTimestamp;
+
+interface BaseRecord {
+    readonly id: StarkeepId;
+    /**
+     * The record's lowercase file extension, verbatim (e.g. "jpg", "md", "xyz");
+     * "" for extension-less files. This is the identification key. The derived
+     * category (`categoryOf(type)`) determines the metadata table and storage
+     * prefix; unmapped/empty extensions derive category "other".
+     */
+    readonly type: string;
+    readonly createdAt: HLCTimestamp;
+    updatedAt: HLCTimestamp;
+    readonly ownerId: string;
+    deletedAt: HLCTimestamp | null;
+    version: number;
+}
+/**
+ * A row in the shared records table. Every DataRecord is backed by a file in
+ * object storage (`objectStorageKey` + `contentHash`); metadata derived from
+ * the file lives in the per-category `record_<category>_metadata` table
+ * (category = `categoryOf(type)`; `other` records have no metadata table).
+ *
+ * App-level / user-authored fields that cannot be deterministically derived
+ * from the file (titles, captions, edit provenance, etc.) live in app-private
+ * storage, not on this row.
+ */
+interface DataRecord extends BaseRecord {
+    readonly kind: "data";
+    contentHash: string;
+    objectStorageKey: string;
+    mimeType: string;
+    sizeBytes: number;
+    originalFilename: string | null;
+    /**
+     * App identity that produced this record. Set by the data-server at write
+     * time from the authenticated subject. Required on every write.
+     */
+    originAppId: string;
+    /**
+     * Optional parent record id linking this record to another shared record
+     * (e.g. a thumbnail's parent is its original). The parent may be of any
+     * type; cross-type parent links are permitted.
+     */
+    parentId: StarkeepId | null;
+}
+/**
+ * One row in a per-category metadata table (`shared_record_<category>_metadata`
+ * / `shared.record_<category>_metadata`). Columns are declared by the
+ * category's entry in `CATEGORIES`. Every column other than `recordId` must be
+ * deterministically derivable from the record's file bytes.
+ */
+interface MetadataRow {
+    recordId: StarkeepId;
+    [column: string]: unknown;
+}
+type AnyRecord = DataRecord;
+
+interface CreateDataRecordInput {
+    type: string;
+    ownerId: string;
+    originAppId: string;
+    contentHash: string;
+    objectStorageKey: string;
+    mimeType: string;
+    sizeBytes: number;
+    originalFilename?: string | null;
+    parentId?: StarkeepId | null;
+}
+declare function createDataRecord(input: CreateDataRecordInput, clock: HLCClock): DataRecord;
+
+interface TypeDefinition {
+    name: string;
+    namespace: string;
+    schema: v.BaseSchema<unknown, unknown, v.BaseIssue<unknown>>;
+}
+interface TypeRegistry {
+    register(definition: TypeDefinition): void;
+    get(namespace: string, name: string): TypeDefinition | undefined;
+    getByKey(key: string): TypeDefinition | undefined;
+    has(namespace: string, name: string): boolean;
+    list(): TypeDefinition[];
+}
+declare function createTypeRegistry(): TypeRegistry;
+
+declare const dataRecordSchema: v.ObjectSchema<{
+    readonly kind: v.LiteralSchema<"data", undefined>;
+    readonly contentHash: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+    readonly objectStorageKey: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+    readonly mimeType: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+    readonly sizeBytes: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+    readonly originalFilename: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    readonly originAppId: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+    readonly parentId: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.LengthAction<string, 26, undefined>]>;
+    readonly type: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+    readonly createdAt: v.ObjectSchema<{
+        readonly wallTime: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+        readonly counter: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+        readonly nodeId: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+    }, undefined>;
+    readonly updatedAt: v.ObjectSchema<{
+        readonly wallTime: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+        readonly counter: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+        readonly nodeId: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+    }, undefined>;
+    readonly ownerId: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+    readonly deletedAt: v.NullableSchema<v.ObjectSchema<{
+        readonly wallTime: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+        readonly counter: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+        readonly nodeId: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+    }, undefined>, undefined>;
+    readonly version: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>]>;
+}, undefined>;
+declare function validateDataRecord(data: unknown): v.SafeParseResult<v.ObjectSchema<{
+    readonly kind: v.LiteralSchema<"data", undefined>;
+    readonly contentHash: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+    readonly objectStorageKey: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+    readonly mimeType: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+    readonly sizeBytes: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+    readonly originalFilename: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    readonly originAppId: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+    readonly parentId: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.LengthAction<string, 26, undefined>]>;
+    readonly type: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+    readonly createdAt: v.ObjectSchema<{
+        readonly wallTime: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+        readonly counter: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+        readonly nodeId: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+    }, undefined>;
+    readonly updatedAt: v.ObjectSchema<{
+        readonly wallTime: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+        readonly counter: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+        readonly nodeId: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+    }, undefined>;
+    readonly ownerId: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+    readonly deletedAt: v.NullableSchema<v.ObjectSchema<{
+        readonly wallTime: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+        readonly counter: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+        readonly nodeId: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+    }, undefined>, undefined>;
+    readonly version: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>]>;
+}, undefined>>;
+
+declare class StarkeepError extends Error {
+    readonly code: string;
+    readonly cause?: unknown | undefined;
+    constructor(message: string, code: string, cause?: unknown | undefined);
+}
+declare class ValidationError extends StarkeepError {
+    constructor(message: string, cause?: unknown);
+}
+declare class NotFoundError extends StarkeepError {
+    constructor(entity: string, id: string);
+}
+declare class ConflictError extends StarkeepError {
+    constructor(message: string);
+}
+
+type Result<T, E = Error> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: E;
+};
+declare function ok<T>(value: T): Result<T, never>;
+declare function err<E>(error: E): Result<never, E>;
+interface PaginationOptions {
+    limit: number;
+    cursor?: string;
+}
+interface PaginatedResult<T> {
+    items: T[];
+    nextCursor: string | null;
+    hasMore: boolean;
+}
+
+/**
+ * Single source of truth for Starkeep's shared core type system.
+ *
+ * Two registries derived from one place:
+ *   - EXTENSIONS: lowercase file extension → mapped Category. Identification is
+ *     by extension; MIME is never authoritative.
+ *   - CATEGORIES: the user-facing organizational layer (mobile-style: Images,
+ *     Videos, Documents…). Each mapped category owns one metadata table holding
+ *     cross-format properties derivable from the file bytes.
+ *
+ * A record's `type` is the lowercase extension verbatim (e.g. "jpg", "md",
+ * "xyz"), even when the extension is unmapped. Its category is derived:
+ * `category = EXTENSIONS[ext] ?? "other"`. `other` is the terminal catch-all
+ * for unmapped / extension-less files — Drive-only, no metadata table, and no
+ * installable app can ever be granted it (apps may only declare extensions that
+ * are present in EXTENSIONS, and the unmapped set IS the `other` set).
+ *
+ * Every relevant system — manifest validation, IAM emission, DSQL schema-init,
+ * SQLite bootstrap, object-key construction, and the local data-server's access
+ * path — derives its view from the registries below. Adding an extension or a
+ * metadata column is a one-file edit here. There is no runtime registration
+ * path — apps cannot register new types or extend metadata columns.
+ */
+type LogicalColumnType = "integer" | "bigint" | "real" | "text" | "timestamp" | "boolean";
+interface CoreTypeMetadataColumn {
+    name: string;
+    type: LogicalColumnType;
+    /** Defaults to true. Set explicitly when the column must be NOT NULL. */
+    nullable?: boolean;
+}
+/** The fixed set of categories. `other` is the terminal catch-all (last). */
+type Category = "image" | "video" | "audio" | "document" | "text" | "code" | "font" | "archive" | "data" | "model3d" | "other";
+interface CategoryDef {
+    id: Category;
+    description: string;
+    /** Cross-format metadata columns. Empty for `other` (no metadata table). */
+    metadataColumns: CoreTypeMetadataColumn[];
+}
+declare const CATEGORIES: readonly CategoryDef[];
+/**
+ * Extension (lowercase, no dot) → mapped category. `other` is NEVER a value
+ * here — it is exclusively the `?? "other"` fallback in `categoryOf`, which is
+ * why no app can ever declare an `other` extension.
+ */
+declare const EXTENSIONS: Readonly<Record<string, Exclude<Category, "other">>>;
+declare const CATEGORY_IDS: readonly Category[];
+/**
+ * Categories an installable app may be granted — every category a real
+ * extension can map to, i.e. all categories EXCEPT `other`. Drive's all-access
+ * (`fileAccessAll`) covers `other` as well, via its `shared/*` IAM ceiling.
+ */
+declare const APP_GRANTABLE_CATEGORIES: readonly Category[];
+/** The set of known (mapped) extensions. */
+declare const KNOWN_EXTENSIONS: ReadonlySet<string>;
+/**
+ * Derived category for a record's extension/type. Unmapped or empty → "other".
+ * Accepts the extension with or without a leading dot, any case.
+ */
+declare function categoryOf(ext: string): Category;
+declare function getCategory(id: string): CategoryDef | undefined;
+declare function isCategoryId(id: string): id is Category;
+/**
+ * Emits a `CREATE TABLE IF NOT EXISTS shared.record_<category>_metadata`
+ * statement for DSQL. Single non-PL/pgSQL statement, no FK constraints — see
+ * `dsql-schema-init.ts` for the DSQL surface caveats. Callers must skip the
+ * `other` category (no metadata table).
+ */
+declare function pgMetadataDdl(c: CategoryDef): string;
+/**
+ * Emits a `CREATE TABLE IF NOT EXISTS shared_record_<category>_metadata`
+ * statement for the local SQLite bootstrap. Callers must skip the `other`
+ * category (no metadata table).
+ */
+declare function sqliteMetadataDdl(c: CategoryDef): string;
+/**
+ * Returns the SQLite metadata table name for a record's type/extension or a
+ * category id. The category is derived when an extension is passed, so storage
+ * adapters that hold only `record.type` route to the correct per-category
+ * table. Passing the literal `"other"` (or an unmapped extension) yields the
+ * `other` table name, which is never created — callers must not write metadata
+ * for `other` records.
+ */
+declare function sqliteMetadataTableName(typeOrCategory: string): string;
+/** DSQL/Postgres counterpart of {@link sqliteMetadataTableName}. */
+declare function pgMetadataTableName(typeOrCategory: string): string;
+
+declare function dataRecordObjectKey(typeOrExt: string, contentHash: string): string;
+declare function appSyncableObjectKey(appId: string, subKey: string): string;
+
+export { APP_GRANTABLE_CATEGORIES, type AnyRecord, type BaseRecord, CATEGORIES, CATEGORY_IDS, type Category, type CategoryDef, type ClockOptions, ConflictError, type CoreTypeMetadataColumn, type CreateDataRecordInput, type DataRecord, EXTENSIONS, type HLCClock, type HLCTimestamp, KNOWN_EXTENSIONS, type LogicalColumnType, type MetadataRow, NotFoundError, type PaginatedResult, type PaginationOptions, type Result, StarkeepError, type StarkeepId, type TypeDefinition, type TypeRegistry, ValidationError, ZERO_HLC, appSyncableObjectKey, categoryOf, compareHLC, createDataRecord, createHLCClock, createStarkeepId, createTypeRegistry, dataRecordObjectKey, dataRecordSchema, deserializeHLC, err, generateId, generateIdAt, getCategory, isCategoryId, isStarkeepId, maxHLC, ok, pgMetadataDdl, pgMetadataTableName, serializeHLC, sqliteMetadataDdl, sqliteMetadataTableName, validateDataRecord };