@kubun/store-graph 0.17.0 → 0.18.0

package/lib/catalog-scope.d.ts

@@ -0,0 +1,120 @@
+import { type DocumentNode, parseCatalogDuration } from '@kubun/protocol';
+import type { GraphStoreAPI } from './api.js';
+export type CatalogRef = {
+    owner: string;
+    id: string;
+};
+export type CatalogRuleInput = Omit<CatalogRule, 'id'> & {
+    id?: string;
+};
+export type CatalogRule = {
+    id: string;
+    models?: Array<string>;
+    owners?: Array<string>;
+    maxAge?: string;
+    maxAhead?: string;
+    dateField?: string;
+};
+export type CatalogLevel = 'KNOWN' | 'OFFLINE' | 'SERVE_ONLY';
+export type CatalogUse = {
+    level: CatalogLevel | null;
+    followed: boolean;
+};
+export type RouteRulesInput = ReadonlyArray<{
+    catalog: CatalogRef;
+    rules: ReadonlyArray<CatalogRule>;
+}>;
+export type DocumentHold = {
+    id: string;
+    documentID: string;
+    createdBy: string;
+    reason: string | null;
+    expiresAt: number | null;
+};
+export type PlaceDocumentHoldParams = {
+    holdID: string;
+    documentID: string;
+    createdBy: string;
+    reason?: string;
+    expiresAt?: number;
+};
+export type DocumentScope = {
+    scope: 'visible' | 'retained' | 'outOfScope';
+    retained: boolean;
+    refs: Array<string>;
+};
+/**
+ * `LOCAL`: the document is here. `UNAVAILABLE`: this device swept it and a retaining rule matches
+ * it again. Null: neither, the same as a document never received.
+ */
+export type DocumentAvailability = 'LOCAL' | 'UNAVAILABLE';
+/** A document's scope with its availability, as an app reads it. */
+export type DocumentScopeView = DocumentScope & {
+    availability: DocumentAvailability | null;
+};
+/** A swept document a retaining rule matches again, with the catalogs whose rules match it. */
+export type UnavailableDocument = {
+    documentID: string;
+    owner: string;
+    catalogs: Array<CatalogRef>;
+};
+/** What this device kept of a document it swept. */
+export type SweptDocument = {
+    documentID: string;
+    modelID: string;
+    owner: string;
+    createdAt: number;
+    scopeDate: number | null;
+    /** Each declared date field's scope date. */
+    fieldDates: Record<string, number>;
+    /** The document's own read rule, when it had one. */
+    readAccess: SweptReadAccess | null;
+    mutationDigest: string;
+    sweptAt: number;
+};
+export type SweptReadAccess = {
+    level: AccessLevelName;
+    allowedDIDs?: Array<string>;
+    allowedGroups?: Array<string>;
+    allowedCircles?: Array<string>;
+};
+type AccessLevelName = 'only_owner' | 'anyone' | 'restricted';
+export type ScopeCatalog = {
+    name: string;
+    rules: Array<CatalogRule>;
+};
+export declare class InvalidCatalogScopeError extends Error {
+    get code(): 'INVALID_CATALOG_RULE';
+    constructor(message: string, options?: ErrorOptions);
+}
+export declare class CatalogScopeRuleLimitError extends Error {
+    get code(): 'CATALOG_RULE_LIMIT_EXCEEDED';
+    constructor();
+}
+export declare class CatalogScopeRulesEmptyError extends Error {
+    get code(): 'CATALOG_RULES_EMPTY';
+    constructor();
+}
+export declare const parseScopeDuration: typeof parseCatalogDuration;
+export declare function isCatalogRuleID(value: unknown): value is string;
+export declare function validateScopeCatalog(catalog: ScopeCatalog): void;
+export declare function parseScopeDate(value: unknown): number | null;
+export declare function scopeRuleMatches(rule: CatalogRule, doc: DocumentNode, nowMS: number, interfaces?: ReadonlyArray<string>): boolean;
+/** What a catalog rule reads of a document, for one that may no longer be stored. */
+export type ScopeRuleFacts = {
+    model: string;
+    owner: string;
+    /** The scope date a rule windows on: the model's own with no field, else the field's. */
+    dateOf: (field: string | null) => number;
+};
+export declare function scopeRuleMatchesFacts(rule: CatalogRule, facts: ScopeRuleFacts, nowMS: number, interfaces?: ReadonlyArray<string>): boolean;
+export declare function recomputeDocumentRefs(documentID: string, tx: GraphStoreAPI, routeRules: RouteRulesInput): Promise<DocumentScope>;
+export declare function canonicalCatalogRuleContent(rule: CatalogRuleInput): string;
+export type AssignCatalogRuleIDsParams = {
+    input: ReadonlyArray<CatalogRuleInput>;
+    current: ReadonlyArray<CatalogRule>;
+    ancestryRuleIDs: ReadonlySet<string>;
+    newRuleID: () => string;
+};
+export declare function assignCatalogRuleIDs(params: AssignCatalogRuleIDsParams): Array<CatalogRule>;
+export {};

package/lib/catalog-scope.js

@@ -0,0 +1,165 @@
+import { InvalidCatalogDurationError, parseCatalogDuration } from '@kubun/protocol';
+export class InvalidCatalogScopeError extends Error {
+    get code() {
+        return 'INVALID_CATALOG_RULE';
+    }
+    constructor(message, options){
+        super(message, options);
+        this.name = 'InvalidCatalogScopeError';
+    }
+}
+export class CatalogScopeRuleLimitError extends Error {
+    get code() {
+        return 'CATALOG_RULE_LIMIT_EXCEEDED';
+    }
+    constructor(){
+        super('Catalogs must have between 1 and 32 rules');
+        this.name = 'CatalogScopeRuleLimitError';
+    }
+}
+export class CatalogScopeRulesEmptyError extends Error {
+    get code() {
+        return 'CATALOG_RULES_EMPTY';
+    }
+    constructor(){
+        super('Catalogs must have at least one rule');
+        this.name = 'CatalogScopeRulesEmptyError';
+    }
+}
+export const parseScopeDuration = parseCatalogDuration;
+export function isCatalogRuleID(value) {
+    return typeof value === 'string' && /^[A-Za-z0-9_-]{1,64}$/.test(value);
+}
+export function validateScopeCatalog(catalog) {
+    if (catalog.rules.length === 0) throw new CatalogScopeRulesEmptyError();
+    if (catalog.rules.length > 32) {
+        throw new CatalogScopeRuleLimitError();
+    }
+    for (const rule of catalog.rules){
+        if (!isCatalogRuleID(rule.id)) {
+            throw new InvalidCatalogScopeError('Invalid catalog rule ID');
+        }
+        if (rule.models?.length === 0 || rule.owners?.length === 0) {
+            throw new InvalidCatalogScopeError('Catalog selectors must be nonempty');
+        }
+        if (rule.models == null && rule.owners == null && rule.maxAge == null && rule.maxAhead == null) {
+            throw new InvalidCatalogScopeError('A rule needs a model, owner or window selector');
+        }
+        try {
+            if (rule.maxAge != null) parseScopeDuration(rule.maxAge);
+            if (rule.maxAhead != null) parseScopeDuration(rule.maxAhead);
+        } catch (error) {
+            if (error instanceof InvalidCatalogDurationError) {
+                throw new InvalidCatalogScopeError(error.message, {
+                    cause: error
+                });
+            }
+            throw error;
+        }
+        if (rule.dateField != null && (rule.models == null || rule.models.length === 0)) {
+            throw new InvalidCatalogScopeError('A date-field override requires selected models');
+        }
+    }
+}
+const fullDatePattern = /^(\d{4})-(\d{2})-(\d{2})$/;
+const dateTimePattern = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.\d+)?(Z|[+-]\d{2}:\d{2})$/;
+export function parseScopeDate(value) {
+    if (typeof value !== 'string') return null;
+    const full = fullDatePattern.exec(value);
+    const timed = dateTimePattern.exec(value);
+    const match = full ?? timed;
+    if (match == null) return null;
+    const year = Number(match[1]);
+    const month = Number(match[2]);
+    const day = Number(match[3]);
+    const validDay = new Date(Date.UTC(year, month - 1, day));
+    if (validDay.getUTCFullYear() !== year || validDay.getUTCMonth() + 1 !== month || validDay.getUTCDate() !== day) return null;
+    if (timed != null) {
+        if (Number(timed[4]) > 23 || Number(timed[5]) > 59 || Number(timed[6]) > 59) return null;
+        const offset = timed[7] ?? 'Z';
+        if (offset !== 'Z' && (Number(offset.slice(1, 3)) > 23 || Number(offset.slice(4)) > 59)) {
+            return null;
+        }
+    }
+    const timestamp = Date.parse(value);
+    return Number.isFinite(timestamp) ? timestamp : null;
+}
+function fieldValue(data, field) {
+    let value = data;
+    for (const segment of field.split('.')){
+        if (value == null || typeof value !== 'object') return null;
+        value = value[segment];
+    }
+    return value;
+}
+export function scopeRuleMatches(rule, doc, nowMS, interfaces = []) {
+    const createdAt = doc.createdAt.getTime();
+    return scopeRuleMatchesFacts(rule, {
+        model: doc.model,
+        owner: doc.owner,
+        dateOf: (field)=>field == null ? doc.scopeDate ?? createdAt : parseScopeDate(fieldValue(doc.data, field)) ?? createdAt
+    }, nowMS, interfaces);
+}
+export function scopeRuleMatchesFacts(rule, facts, nowMS, interfaces = []) {
+    if (rule.models != null && !rule.models.some((model)=>model === facts.model || interfaces.includes(model))) {
+        return false;
+    }
+    if (rule.owners != null && !rule.owners.includes(facts.owner)) return false;
+    if (rule.maxAge == null && rule.maxAhead == null) return true;
+    const date = facts.dateOf(rule.dateField ?? null);
+    if (rule.maxAge != null && date < nowMS - parseScopeDuration(rule.maxAge)) return false;
+    if (rule.maxAhead != null && date >= nowMS + parseScopeDuration(rule.maxAhead)) return false;
+    return true;
+}
+export function recomputeDocumentRefs(documentID, tx, routeRules) {
+    return tx.recomputeDocumentRefs({
+        documentID,
+        routeRules
+    });
+}
+export function canonicalCatalogRuleContent(rule) {
+    return JSON.stringify({
+        models: rule.models == null ? null : [
+            ...new Set(rule.models)
+        ].sort(),
+        owners: rule.owners == null ? null : [
+            ...new Set(rule.owners)
+        ].sort(),
+        maxAge: rule.maxAge ?? null,
+        maxAhead: rule.maxAhead ?? null,
+        dateField: rule.dateField ?? null
+    });
+}
+export function assignCatalogRuleIDs(params) {
+    const claimed = new Set();
+    const admissible = new Set([
+        ...params.ancestryRuleIDs,
+        ...params.current.map((rule)=>rule.id)
+    ]);
+    for (const rule of params.input){
+        if (rule.id === undefined) continue;
+        if (!isCatalogRuleID(rule.id)) {
+            throw new InvalidCatalogScopeError('Invalid catalog rule ID');
+        }
+        if (claimed.has(rule.id)) throw new InvalidCatalogScopeError('Duplicate catalog rule ID');
+        if (!admissible.has(rule.id)) throw new InvalidCatalogScopeError('Catalog rule ID does not belong to this lineage');
+        claimed.add(rule.id);
+    }
+    return params.input.map((rule)=>{
+        if (rule.id !== undefined) return {
+            ...rule,
+            id: rule.id
+        };
+        const content = canonicalCatalogRuleContent(rule);
+        const match = params.current.find((candidate)=>!claimed.has(candidate.id) && canonicalCatalogRuleContent(candidate) === content);
+        const id = match?.id ?? params.newRuleID();
+        if (claimed.has(id) || match == null && admissible.has(id)) {
+            throw new InvalidCatalogScopeError('Could not allocate a unique catalog rule ID');
+        }
+        claimed.add(id);
+        return {
+            ...rule,
+            id
+        };
+    });
+}

package/lib/catalog-state.d.ts

@@ -0,0 +1,21 @@
+import type { SignedRecord } from '@kubun/records';
+import type { Kysely } from 'kysely';
+import type { CatalogDraftState, CatalogVersionRef, LocalCatalogPublication, PendingCatalogHead } from './catalog-types.js';
+import type { GraphTables } from './tables.js';
+export type CatalogStateMethods = {
+    getAdmittedCatalogHead(catalogID: string): Promise<SignedRecord | null>;
+    putAdmittedCatalogHead(catalogID: string, record: SignedRecord): Promise<void>;
+    deleteAdmittedCatalogHead(catalogID: string): Promise<void>;
+    getCatalogDraft(catalogID: string): Promise<CatalogDraftState | null>;
+    putCatalogDraft(draft: CatalogDraftState): Promise<void>;
+    deleteCatalogDraft(catalogID: string): Promise<boolean>;
+    putLocalCatalogPublication(value: LocalCatalogPublication): Promise<void>;
+    listLocalCatalogPublications(catalogID: string): Promise<Array<LocalCatalogPublication>>;
+    getRecipientCatalogVersion(ref: CatalogVersionRef): Promise<SignedRecord | null>;
+    putRecipientCatalogVersion(ref: CatalogVersionRef, record: SignedRecord): Promise<void>;
+    getPendingCatalogHead(catalogID: string): Promise<PendingCatalogHead | null>;
+    putPendingCatalogHead(head: PendingCatalogHead): Promise<void>;
+    deletePendingCatalogHead(catalogID: string): Promise<void>;
+    listPendingCatalogHeads(): Promise<Array<PendingCatalogHead>>;
+};
+export declare function createCatalogStateMethods(db: Kysely<GraphTables>): CatalogStateMethods;

package/lib/catalog-state.js

@@ -0,0 +1,122 @@
+import { fromB64U, toB64U } from '@sozai/codec';
+function normalizeBytes(value) {
+    if (value instanceof Uint8Array) return {
+        bytes: toB64U(value)
+    };
+    if (Array.isArray(value)) return value.map(normalizeBytes);
+    if (value !== null && typeof value === 'object') return Object.fromEntries(Object.entries(value).map(([key, item])=>[
+            key,
+            normalizeBytes(item)
+        ]));
+    return value;
+}
+function encode(value) {
+    // Buffer.toJSON runs before a replacer; normalize bytes before JSON visits them.
+    return JSON.stringify(normalizeBytes(value));
+}
+function decode(value) {
+    return JSON.parse(typeof value === 'string' ? value : JSON.stringify(value), (_key, item)=>{
+        if (item !== null && typeof item === 'object' && 'bytes' in item && Object.keys(item).length === 1 && typeof item.bytes === 'string') return fromB64U(item.bytes);
+        return item;
+    });
+}
+function pending(row) {
+    return {
+        catalogID: row.catalog_id,
+        headVersionID: row.head_version_id,
+        groupID: row.group_id,
+        retryAt: Number(row.retry_at),
+        attempts: Number(row.attempts)
+    };
+}
+export function createCatalogStateMethods(db) {
+    return {
+        async getAdmittedCatalogHead (catalogID) {
+            const row = await db.selectFrom('kubun_graph_catalog_admitted_heads').select('signed_record').where('catalog_id', '=', catalogID).executeTakeFirst();
+            return row === undefined ? null : decode(row.signed_record);
+        },
+        async putAdmittedCatalogHead (catalogID, record) {
+            const values = {
+                catalog_id: catalogID,
+                signed_record: encode(record)
+            };
+            await db.insertInto('kubun_graph_catalog_admitted_heads').values(values).onConflict((oc)=>oc.column('catalog_id').doUpdateSet({
+                    signed_record: values.signed_record
+                })).execute();
+        },
+        async deleteAdmittedCatalogHead (catalogID) {
+            await db.deleteFrom('kubun_graph_catalog_admitted_heads').where('catalog_id', '=', catalogID).execute();
+        },
+        async getCatalogDraft (catalogID) {
+            const row = await db.selectFrom('kubun_graph_catalog_drafts').select('state').where('catalog_id', '=', catalogID).executeTakeFirst();
+            return row === undefined ? null : decode(row.state);
+        },
+        async putCatalogDraft (draft) {
+            const values = {
+                catalog_id: draft.catalogID,
+                state: encode(draft)
+            };
+            await db.insertInto('kubun_graph_catalog_drafts').values(values).onConflict((oc)=>oc.column('catalog_id').doUpdateSet({
+                    state: values.state
+                })).execute();
+        },
+        async deleteCatalogDraft (catalogID) {
+            const result = await db.deleteFrom('kubun_graph_catalog_drafts').where('catalog_id', '=', catalogID).executeTakeFirst();
+            return Number(result.numDeletedRows) > 0;
+        },
+        async putLocalCatalogPublication (value) {
+            await db.insertInto('kubun_graph_catalog_publications').values({
+                catalog_id: value.catalogID,
+                version_id: value.versionID
+            }).onConflict((oc)=>oc.columns([
+                    'catalog_id',
+                    'version_id'
+                ]).doNothing()).execute();
+        },
+        async listLocalCatalogPublications (catalogID) {
+            const rows = await db.selectFrom('kubun_graph_catalog_publications').selectAll().where('catalog_id', '=', catalogID).orderBy('version_id').execute();
+            return rows.map((row)=>({
+                    catalogID: row.catalog_id,
+                    versionID: row.version_id
+                }));
+        },
+        async getRecipientCatalogVersion (ref) {
+            const row = await db.selectFrom('kubun_graph_catalog_recipient_versions').select('signed_record').where('catalog_id', '=', ref.catalogID).where('version_id', '=', ref.versionID).executeTakeFirst();
+            return row === undefined ? null : decode(row.signed_record);
+        },
+        async putRecipientCatalogVersion (ref, record) {
+            const values = {
+                catalog_id: ref.catalogID,
+                version_id: ref.versionID,
+                signed_record: encode(record)
+            };
+            await db.insertInto('kubun_graph_catalog_recipient_versions').values(values).onConflict((oc)=>oc.columns([
+                    'catalog_id',
+                    'version_id'
+                ]).doUpdateSet({
+                    signed_record: values.signed_record
+                })).execute();
+        },
+        async getPendingCatalogHead (catalogID) {
+            const row = await db.selectFrom('kubun_graph_catalog_pending_heads').selectAll().where('catalog_id', '=', catalogID).executeTakeFirst();
+            return row === undefined ? null : pending(row);
+        },
+        async putPendingCatalogHead (head) {
+            const values = {
+                catalog_id: head.catalogID,
+                head_version_id: head.headVersionID,
+                group_id: head.groupID,
+                retry_at: head.retryAt,
+                attempts: head.attempts
+            };
+            await db.insertInto('kubun_graph_catalog_pending_heads').values(values).onConflict((oc)=>oc.column('catalog_id').doUpdateSet(values)).execute();
+        },
+        async deletePendingCatalogHead (catalogID) {
+            await db.deleteFrom('kubun_graph_catalog_pending_heads').where('catalog_id', '=', catalogID).execute();
+        },
+        async listPendingCatalogHeads () {
+            const rows = await db.selectFrom('kubun_graph_catalog_pending_heads').selectAll().orderBy('catalog_id').execute();
+            return rows.map(pending);
+        }
+    };
+}

package/lib/catalog-types.d.ts

@@ -0,0 +1,71 @@
+import type { SignedRecord } from '@kubun/records';
+import type { CatalogRule } from './catalog-scope.js';
+export type CatalogDefinition = {
+    name: string;
+    description?: string;
+    app?: string;
+    rules: Array<CatalogRule>;
+};
+export type CatalogVersionRef = {
+    catalogID: string;
+    versionID: string;
+};
+export type CatalogVersionPayload = {
+    definition: CatalogDefinition;
+    parents: Array<CatalogVersionRef>;
+    upstream?: CatalogVersionRef;
+    embeddedBase?: SignedRecord;
+    publishedAt: string;
+};
+export type CatalogHeadPayload = CatalogDefinition & {
+    headVersionID: string;
+    upstream?: CatalogVersionRef;
+};
+export type CatalogRuleResolutionInput = {
+    ruleID: string;
+    side: 'LOCAL' | 'UPSTREAM';
+};
+export type OwnerCatalogMergeState = {
+    baseVersionID: string;
+    localRevisionID: string;
+    upstreamVersionID: string;
+    winningHeadVersionID: string;
+};
+export type CatalogDraftState = {
+    catalogID: string;
+    baseVersionID: string;
+    definition: CatalogDefinition;
+    dirtyRuleIDs: Array<string>;
+    resolutions: Array<CatalogRuleResolutionInput>;
+    integratedBase: SignedRecord | null;
+    mergedBranchVersionIDs: Array<string>;
+    activeBranchVersionID: string | null;
+    activeOwnerMerge: OwnerCatalogMergeState | null;
+};
+export type LocalCatalogPublication = {
+    catalogID: string;
+    versionID: string;
+};
+export type PendingCatalogHead = {
+    catalogID: string;
+    headVersionID: string;
+    groupID: string | null;
+    retryAt: number;
+    attempts: number;
+};
+export type CatalogRuleConflict = {
+    ruleID: string;
+    base: CatalogRule | null;
+    local: CatalogRule | null;
+    upstream: CatalogRule | null;
+};
+export type MergeCatalogDefinitionsParams = {
+    base: CatalogDefinition;
+    local: CatalogDefinition;
+    upstream: CatalogDefinition;
+    resolutions?: ReadonlyArray<CatalogRuleResolutionInput>;
+};
+export type CatalogMergeResult = {
+    merged: CatalogDefinition;
+    conflicts: Array<CatalogRuleConflict>;
+};

package/lib/catalog-types.js

@@ -0,0 +1 @@
+export { };

package/lib/errors.d.ts

@@ -32,3 +32,18 @@ export declare class ModelNotDeployedError extends Error {
         modelID: string;
     };
 }
+export declare class InvalidModelDateFieldError extends Error {
+    get code(): 'INVALID_MODEL_DATE_FIELD';
+    constructor(message: string);
+}
+export declare class MissingGraphCommitContextError extends Error {
+    constructor();
+}
+export declare class DocumentNotHoldableError extends Error {
+    get code(): string;
+    constructor(options?: ErrorOptions);
+}
+export declare class DocumentLockRequiresTransactionError extends Error {
+    get code(): 'GRAPH_DOCUMENT_LOCK_REQUIRES_TRANSACTION';
+    constructor();
+}

package/lib/errors.js

@@ -43,3 +43,36 @@
         };
     }
 }
+export class InvalidModelDateFieldError extends Error {
+    get code() {
+        return 'INVALID_MODEL_DATE_FIELD';
+    }
+    constructor(message){
+        super(message);
+        this.name = 'InvalidModelDateFieldError';
+    }
+}
+export class MissingGraphCommitContextError extends Error {
+    constructor(){
+        super('Graph store requires a commit context');
+        this.name = 'MissingGraphCommitContextError';
+    }
+}
+export class DocumentNotHoldableError extends Error {
+    get code() {
+        return 'DOCUMENT_NOT_HOLDABLE';
+    }
+    constructor(options){
+        super('Only a local document the viewer can read can be held', options);
+        this.name = 'DocumentNotHoldableError';
+    }
+}
+export class DocumentLockRequiresTransactionError extends Error {
+    get code() {
+        return 'GRAPH_DOCUMENT_LOCK_REQUIRES_TRANSACTION';
+    }
+    constructor(){
+        super('A document row lock is held only by a transaction');
+        this.name = 'DocumentLockRequiresTransactionError';
+    }
+}

package/lib/identifiers.d.ts

@@ -0,0 +1,7 @@
+export declare const MAX_IDENTIFIER_BYTES = 63;
+/**
+ * Returns an identifier of at most `MAX_IDENTIFIER_BYTES` bytes. Names within the
+ * limit are returned unchanged; longer ones keep their leading part and end with
+ * a hash of the full name, so names that differ only past the limit stay distinct.
+ */
+export declare function boundedIdentifier(name: string): string;

package/lib/identifiers.js

@@ -0,0 +1,27 @@
+// Postgres truncates identifiers longer than NAMEDATALEN - 1 bytes, so two long
+// names sharing a prefix can silently resolve to the same object.
+export const MAX_IDENTIFIER_BYTES = 63;
+const HASH_LENGTH = 13 // a 64-bit value in base36
+;
+const FNV_OFFSET = 0xcbf29ce484222325n;
+const FNV_PRIME = 0x100000001b3n;
+const UINT64_MASK = 0xffffffffffffffffn;
+function hashName(bytes) {
+    let hash = FNV_OFFSET;
+    for (const byte of bytes){
+        hash = (hash ^ BigInt(byte)) * FNV_PRIME & UINT64_MASK;
+    }
+    return hash.toString(36).padStart(HASH_LENGTH, '0');
+}
+/**
+ * Returns an identifier of at most `MAX_IDENTIFIER_BYTES` bytes. Names within the
+ * limit are returned unchanged; longer ones keep their leading part and end with
+ * a hash of the full name, so names that differ only past the limit stay distinct.
+ */ export function boundedIdentifier(name) {
+    const bytes = new TextEncoder().encode(name);
+    if (bytes.length <= MAX_IDENTIFIER_BYTES) {
+        return name;
+    }
+    const prefix = name.slice(0, MAX_IDENTIFIER_BYTES - HASH_LENGTH - 1);
+    return `${prefix}_${hashName(bytes)}`;
+}

package/lib/index.d.ts

@@ -1,10 +1,17 @@
+export { accessDefaultRecordProvider, GraphAccessDefaultRecordError, GraphAccessDefaultRecordTypeError, graphAccessDefaultRecordAdapter, } from './access-default-records.js';
 import type { StoreProvider } from '@kubun/db';
 import type { GraphStoreAPI } from './api.js';
-export type { GraphStoreAPI, StoredAccessDefaultRow, StoredAccessRule } from './api.js';
-export { createGraphStore } from './api.js';
+export type { CustodyNonce, CustodyPinRelease, CustodyReceiptRecord, DocumentSweepRefusal, DocumentSweepResult, GetDocumentIDsForScopeParams, GraphStoreAPI, ReadWinnerStateDigestsParams, RecomputeDocumentRefsParams, ReconcileCatalogModelRefsParams, RecordPendingMutationAttemptParams, RemoveUserModelAccessDefaultsParams, StoredAccessDefaultRow, StoredAccessRule, SweepDocumentParams, UpdateSearchEntryParams, } from './api.js';
+export { catalogRuleRef, createGraphStore, custodyPinRef, isCatalogRuleRef, isCustodyPinRef, mutationIDsDigest, readWinnerStateDigest, readWinnerStateDigests, } from './api.js';
+export { catalogLocalRevisionID, mergeCatalogDefinitions, orderMergedCatalogRules, } from './catalog-merge.js';
+export { catalogRecordPolicy, GraphCatalogRecordError, GraphCatalogRecordTypeError, graphCatalogRecordAdapter, graphStoreOfCatalogRecords, verifyGraphCatalogRecord, } from './catalog-records.js';
+export type { AssignCatalogRuleIDsParams, CatalogLevel, CatalogRef as ScopeCatalogRef, CatalogRule as ScopeCatalogRule, CatalogRuleInput, CatalogRuleInput as ScopeCatalogRuleInput, CatalogUse, DocumentAvailability, DocumentHold, DocumentScope, DocumentScopeView, PlaceDocumentHoldParams, RouteRulesInput, ScopeCatalog, SweptDocument, SweptReadAccess, UnavailableDocument, } from './catalog-scope.js';
+export { assignCatalogRuleIDs, canonicalCatalogRuleContent, isCatalogRuleID, parseScopeDate, recomputeDocumentRefs, } from './catalog-scope.js';
 export { graphStoreDefinition } from './definition.js';
-export { ModelNotDeployedError } from './errors.js';
+export { DocumentLockRequiresTransactionError, DocumentNotHoldableError, InvalidModelDateFieldError, MissingGraphCommitContextError, ModelNotDeployedError, } from './errors.js';
 export { resolveSearchableFields, SearchNotEnabledError } from './search.js';
 export declare const GRAPH_STORE: "graph";
 export declare function getGraphStore(provider: StoreProvider): Promise<GraphStoreAPI>;
-export type { AccessLevel, AccessPermissions, AddDocumentModelParams, Catalog, ClusterDefinitionRow, ClusterModel, ConnectionArguments, CreateDocumentParams, CreateGraphParams, CursorDocument, Document, DocumentData, DocumentModelRow, DocumentParams, GraphModel, GraphModelWithRecord, GraphTables, InsertCatalog, InsertClusterModel, InsertDocument, InsertDocumentModel, InsertDocumentModelInterface, InsertMutationLogEntry, ListDocumentsParams, MutationLogEntry, PaginatedResult, PaginationParams, QueryDocumentsParams, QueryDocumentsResult, SaveDocumentParams, SearchConfig, SearchDocumentResult, SearchDocumentsParams, UpdateDocument, UpdateDocumentModel, ViewerReadAccess, } from './tables.js';
+export { type GCMark, gcMarkPastGrace } from './api.js';
+export type { CatalogDefinition, CatalogDraftState, CatalogHeadPayload, CatalogMergeResult, CatalogRuleConflict, CatalogRuleResolutionInput, CatalogVersionPayload, CatalogVersionRef, LocalCatalogPublication, MergeCatalogDefinitionsParams, OwnerCatalogMergeState, PendingCatalogHead, } from './catalog-types.js';
+export type { AccessLevel, AccessPermissions, AddDocumentModelParams, ClusterDefinitionRow, ClusterModel, ConnectionArguments, CreateDocumentParams, CreateGraphParams, CursorDocument, Document, DocumentData, DocumentLeafPageParams, DocumentLeafRow, DocumentLeafRule, DocumentModelRow, DocumentParams, GraphModel, GraphModelWithRecord, GraphTables, InsertClusterModel, InsertDocument, InsertDocumentModel, InsertDocumentModelInterface, InsertMutationLogEntry, ListDocumentsParams, MutationLogEntry, PaginatedResult, PaginationParams, QueryDocumentsParams, QueryDocumentsResult, SaveDocumentParams, SearchConfig, SearchDocumentResult, SearchDocumentsParams, UpdateDocument, UpdateDocumentModel, ViewerReadAccess, } from './tables.js';

package/lib/index.js

@@ -1,8 +1,13 @@
-export { createGraphStore } from './api.js';
+export { accessDefaultRecordProvider, GraphAccessDefaultRecordError, GraphAccessDefaultRecordTypeError, graphAccessDefaultRecordAdapter } from './access-default-records.js';
+export { catalogRuleRef, createGraphStore, custodyPinRef, isCatalogRuleRef, isCustodyPinRef, mutationIDsDigest, readWinnerStateDigest, readWinnerStateDigests } from './api.js';
+export { catalogLocalRevisionID, mergeCatalogDefinitions, orderMergedCatalogRules } from './catalog-merge.js';
+export { catalogRecordPolicy, GraphCatalogRecordError, GraphCatalogRecordTypeError, graphCatalogRecordAdapter, graphStoreOfCatalogRecords, verifyGraphCatalogRecord } from './catalog-records.js';
+export { assignCatalogRuleIDs, canonicalCatalogRuleContent, isCatalogRuleID, parseScopeDate, recomputeDocumentRefs } from './catalog-scope.js';
 export { graphStoreDefinition } from './definition.js';
-export { ModelNotDeployedError } from './errors.js';
+export { DocumentLockRequiresTransactionError, DocumentNotHoldableError, InvalidModelDateFieldError, MissingGraphCommitContextError, ModelNotDeployedError } from './errors.js';
 export { resolveSearchableFields, SearchNotEnabledError } from './search.js';
 export const GRAPH_STORE = 'graph';
 export function getGraphStore(provider) {
     return provider.getStore(GRAPH_STORE);
 }
+export { gcMarkPastGrace } from './api.js';

package/lib/migrations.d.ts

@@ -1,16 +1,14 @@
 import type { MigrationContext } from '@kubun/db';
 import type { Migration } from 'kysely/migration';
 /**
- * A shipped migration is immutable: once a database has run it, editing it
- * changes nothing on that database and silently diverges the schema from the
- * code. Every schema change after a release therefore goes in a NEW migration,
- * which is why the later ones here say so.
+ * A shipped migration should be immutable: once a database has run it, editing
+ * it changes nothing on that database and silently diverges its schema from the
+ * code. Schema changes after a release that preserves databases need a NEW
+ * migration.
  *
- * `0-init` is a deliberate exception on this change: it was edited in place
- * rather than extended. That is a BREAKING change — a database created before it
- * will not pick the new columns up and must be recreated. It was taken because
- * this release already requires recreating local databases for unrelated reasons,
- * so folding the change into the initial schema costs nothing and keeps `0-init`
- * readable as the whole schema. Do NOT repeat it after this release ships.
+ * `0-init` was edited in place again for the pending arrival group, sender, retry columns and
+ * due index. Existing databases will not acquire them and must be recreated.
+ * This is a breaking reset. Do NOT repeat an in-place edit once a release that
+ * must preserve existing databases ships; add a new migration then.
  */
 export declare function getGraphMigrations(ctx: MigrationContext): Record<string, Migration>;