@ai-matrx/associations 0.2.0

package/dist/core/index.d.cts

@@ -0,0 +1,648 @@
+import { EntityOverlayMap, EntityTypeToken, EntityOverlayEntry, ErrorSink, AssociationsRpcError, AssociationsDataSource, AssociationsIdentity, AssociationTargetType, AssociationsRpcResult, AssociationEdge, AssociationTargetEdge, AssociationSourceEdge, CategoryDimension, PlatformCategory, UserStateKind, UserEntityState, AssociationsEntry, CategoriesEntry, AssociationsConfig } from '../index.cjs';
+import 'react';
+
+/** The universal ownership column post-2026-reorg. */
+declare const DEFAULT_OWNER_COLUMN = "created_by";
+/** The universal org-scoping column. */
+declare const DEFAULT_ORG_COLUMN = "organization_id";
+type ContentRole = "utility" | "source" | "destination" | "hybrid" | "container";
+/** Runtime guard for the DB's free-text `content_role` column. */
+declare function isContentRole(value: string | null): value is ContentRole;
+/**
+ * Normalise a raw `kind`/`type` string onto its canonical entity token.
+ * Returns the input unchanged when it is already canonical or unknown — the
+ * caller's existing "no registry entry → plain text" path still applies.
+ */
+declare function resolveEntityToken(raw: string): string;
+/**
+ * Fully-resolved entity descriptor — generated metadata + host overlay, with
+ * safe fallbacks so an un-overlaid token still renders (derived plural, no
+ * door, `Icon: null` → the consumer's default) even if it can't be queried
+ * for candidates yet.
+ */
+interface EntityInfo {
+    token: EntityTypeToken;
+    label: string;
+    labelPlural: string;
+    /** Postgres schema of the backing table (from the generated registry). */
+    schema: string;
+    /** Backing table name (from the generated registry). */
+    table: string;
+    /** Title column for the picker, or null when none is registered. */
+    titleColumn: string | null;
+    /** Ownership column to scope candidate reads to the current user. */
+    ownerColumn: string;
+    /** Org-scoping column. */
+    orgColumn: string;
+    /** Host-supplied icon component, or null (consumer renders its default). */
+    Icon: EntityOverlayEntry["Icon"] | null;
+    hrefFor: ((id: string) => string) | null;
+    scopeable: boolean;
+    category: string | null;
+    /** Knowledge-model grouping bucket (resource surfaces group by this). */
+    contentRole: ContentRole;
+    /** Candidate-source override (rag-backed tokens etc.); null = generic read. */
+    listCandidates: EntityOverlayEntry["listCandidates"] | null;
+    /** True when a picker can list real candidates (title column OR override). */
+    canListCandidates: boolean;
+}
+interface EntityRegistry {
+    /** Merge more overlay entries in (host binding, W4 pickers, tests). */
+    registerEntityOverlay(overlay: EntityOverlayMap): void;
+    /** Resolve a KNOWN token to its full descriptor. */
+    getEntityInfo(token: EntityTypeToken): EntityInfo;
+    /** Safe variant for raw strings (e.g. an edge's `otherType`). */
+    tryGetEntityInfo(token: string): EntityInfo | null;
+    /** Resolve from a live `(schema, table)` pair, or null. */
+    tryGetEntityInfoByTable(schema: string, table: string): EntityInfo | null;
+    /** Resolve a raw table name only when it maps to exactly one entity. */
+    tryGetEntityInfoByUniqueTableName(table: string): EntityInfo | null;
+    /**
+     * Tokens the DB classifies as knowledge resources via a valid
+     * `content_role` AND that can list candidates. The default set for card
+     * grids, resource sections, and attach pickers.
+     */
+    curatedTokens(): EntityTypeToken[];
+    /**
+     * Tokens offered as reference "Allowed types" — DB-driven via
+     * `platform.entity_types.reference_pickable`. A pickable token with no
+     * title column and no candidate override is a config defect: excluded and
+     * screamed to the errorSink, never silently shown broken.
+     */
+    listableTokens(): EntityTypeToken[];
+}
+/** Build the merge engine over the host overlay (empty overlay is legal). */
+declare function createEntityRegistry(errorSink: ErrorSink, initialOverlay?: EntityOverlayMap): EntityRegistry;
+
+/** True when `value` is a syntactically valid UUID string. */
+declare function isUuid(value: unknown): value is string;
+/** Return the first failing check, or null if all pass. Pure. */
+declare function firstError(...checks: (AssociationsRpcError | null)[]): AssociationsRpcError | null;
+interface AssociationGuards {
+    /** A single id must be a real UUID. Kills the "cute text id" bug class. */
+    checkUuid(field: string, value: unknown): AssociationsRpcError | null;
+    /** Every id in an array must be a real UUID. */
+    checkUuidArray(field: string, values: readonly unknown[]): AssociationsRpcError | null;
+    /** A type token must be registered in `platform.entity_types`. */
+    checkToken(field: string, value: unknown): AssociationsRpcError | null;
+    /**
+     * Map a legacy/phantom token to its registered canonical token.
+     * Pass-through for anything not in the alias table. Loud by doctrine — the
+     * alias firing is a bug at the callsite, recovered here, never silent.
+     */
+    normalizeEntityToken(value: string): string;
+}
+/** Bind the guard set to the host's errorSink (the loud seam). */
+declare function createAssociationGuards(errorSink: ErrorSink): AssociationGuards;
+
+declare function err(code: AssociationsRpcError["code"], message: string, detail?: unknown, hint?: string): {
+    ok: false;
+    error: AssociationsRpcError;
+};
+declare function ok<T>(data: T): {
+    ok: true;
+    data: T;
+};
+/**
+ * True when a failure is the TRANSPORT dying, not the server answering: the
+ * browser is offline, asleep, mid-wifi-handoff, or DNS/TLS failed; also the
+ * bounded Envoy/Supabase gateway shape emitted when the upstream connection
+ * dies before response headers. Use it to decide how LOUD a failure is,
+ * never whether to handle it.
+ */
+declare function isTransportFailure(e: unknown): boolean;
+type PgErrorMapper = (e: unknown) => AssociationsRpcError;
+type PgErrorPairMapper = (e: unknown) => [AssociationsRpcError["code"], string, unknown, string | undefined];
+interface RpcResultHelpers {
+    ok: typeof ok;
+    err: typeof err;
+    mapPgError: PgErrorMapper;
+    mapPgErrorPair: PgErrorPairMapper;
+}
+/**
+ * Bind the loud funnel to the host's errorSink. Every failure in this
+ * package's services passes through the returned `mapPgError` exactly once.
+ */
+declare function createRpcResultHelpers(errorSink: ErrorSink): RpcResultHelpers;
+
+interface CoreDeps {
+    dataSource: AssociationsDataSource;
+    identity: AssociationsIdentity;
+    errorSink: ErrorSink;
+    guards: AssociationGuards;
+    rpc: RpcResultHelpers;
+    registry: EntityRegistry;
+}
+
+interface ConversationFileLink {
+    fileId: string;
+    label: string | null;
+    metadata: unknown;
+    createdAt: string;
+}
+interface AddAssociationArgs {
+    sourceType: string;
+    sourceId: string;
+    targetType: AssociationTargetType;
+    targetId: string;
+    orgId?: string;
+    label?: string;
+    metadata?: unknown;
+    /**
+     * Exact file → conversation updates preserve existing metadata unless the
+     * caller explicitly opts into replacement. Invalid for every other pair.
+     */
+    replaceMetadata?: boolean;
+    role?: string;
+    position?: number;
+    /**
+     * Typed edge payload (Edge Payload System). `payloadKind` must be a
+     * registered `platform.edge_payload_kind`; the DB trigger validates
+     * `payload` against its JSON Schema and hard-fails on any mismatch. Real
+     * logic an edge carries goes HERE — `metadata` is for loose annotations.
+     */
+    payloadKind?: string;
+    payload?: unknown;
+}
+interface AssociationsServiceApi {
+    listForEntity(rawType: string, id: string): Promise<AssociationsRpcResult<{
+        edges: AssociationEdge[];
+    }>>;
+    listConversationFiles(conversationId: string): Promise<AssociationsRpcResult<{
+        files: ConversationFileLink[];
+    }>>;
+    listForTargets(rawTargetType: string, targetIds: string[]): Promise<AssociationsRpcResult<{
+        edges: AssociationTargetEdge[];
+    }>>;
+    listForTargetsVisible(rawTargetType: string, targetIds: string[]): Promise<AssociationsRpcResult<{
+        edges: AssociationTargetEdge[];
+    }>>;
+    listForSources(rawSourceType: string, sourceIds: string[], rawTargetType?: string): Promise<AssociationsRpcResult<{
+        edges: AssociationSourceEdge[];
+    }>>;
+    add(args: AddAssociationArgs): Promise<AssociationsRpcResult<{
+        id: string;
+    }>>;
+    remove(args: {
+        sourceType: string;
+        sourceId: string;
+        targetType: string;
+        targetId: string;
+        role?: string;
+    }): Promise<AssociationsRpcResult<null>>;
+    setTargets(args: {
+        sourceType: string;
+        sourceId: string;
+        targetType: AssociationTargetType;
+        targetIds: string[];
+        orgId?: string;
+        role?: string;
+    }): Promise<AssociationsRpcResult<null>>;
+    addAgentResource(args: {
+        agentId: string;
+        sourceType: string;
+        sourceId: string;
+        label?: string;
+        metadata?: unknown;
+    }): Promise<AssociationsRpcResult<{
+        id: string;
+    }>>;
+    removeAgentResource(args: {
+        agentId: string;
+        sourceType: string;
+        sourceId: string;
+    }): Promise<AssociationsRpcResult<null>>;
+    removeForEntity(rawType: string, id: string): Promise<AssociationsRpcResult<null>>;
+}
+declare function createAssociationsService(deps: CoreDeps): AssociationsServiceApi;
+
+interface CategoriesServiceApi {
+    list(dimension?: CategoryDimension): Promise<AssociationsRpcResult<{
+        categories: PlatformCategory[];
+    }>>;
+    create(args: {
+        dimension: CategoryDimension;
+        name: string;
+        orgId: string;
+        parentId?: string | null;
+        color?: string | null;
+        icon?: string | null;
+        slug?: string | null;
+    }): Promise<AssociationsRpcResult<{
+        id: string;
+    }>>;
+    update(args: {
+        id: string;
+        name: string;
+        slug: string | null;
+        color: string | null;
+        icon: string | null;
+        position: number | null;
+    }): Promise<AssociationsRpcResult<{
+        id: string;
+    }>>;
+    reparent(args: {
+        id: string;
+        parentId: string | null;
+    }): Promise<AssociationsRpcResult<{
+        id: string;
+    }>>;
+    delete(id: string): Promise<AssociationsRpcResult<{
+        id: string;
+    }>>;
+}
+declare function createCategoriesService(deps: CoreDeps): CategoriesServiceApi;
+
+interface FavoritesServiceApi {
+    setState(args: {
+        entityType: string;
+        entityId: string;
+        isFavorite?: boolean;
+        isPinned?: boolean;
+        isHidden?: boolean;
+    }): Promise<AssociationsRpcResult<null>>;
+    setFavorite(entityType: string, entityId: string, isFavorite: boolean): Promise<AssociationsRpcResult<null>>;
+    setPinned(entityType: string, entityId: string, isPinned: boolean): Promise<AssociationsRpcResult<null>>;
+    setHidden(entityType: string, entityId: string, isHidden: boolean): Promise<AssociationsRpcResult<null>>;
+    list(kind?: UserStateKind): Promise<AssociationsRpcResult<{
+        items: UserEntityState[];
+    }>>;
+    getBulk(entityType: string, entityIds: string[]): Promise<AssociationsRpcResult<{
+        items: UserEntityState[];
+    }>>;
+    touch(entityType: string, entityId: string): Promise<AssociationsRpcResult<null>>;
+}
+declare function createFavoritesService(deps: CoreDeps): FavoritesServiceApi;
+
+interface CandidateRecord {
+    id: string;
+    title: string;
+}
+interface ListCandidatesArgs {
+    token: EntityTypeToken;
+    /** Scope to this owner's rows when the entity declares an owner column. */
+    ownerId?: string | null;
+    /** Case-insensitive title filter. */
+    search?: string;
+    limit?: number;
+}
+type CandidatesResult = {
+    ok: true;
+    data: CandidateRecord[];
+} | {
+    ok: false;
+    error: string;
+};
+interface UniversalCandidate extends CandidateRecord {
+    token: EntityTypeToken;
+}
+interface SearchAcrossTokensArgs {
+    /** Tokens to search. Defaults to every curated token in the registry. */
+    tokens?: EntityTypeToken[];
+    search: string;
+    ownerId?: string | null;
+    /** Cap per token — a universal search shows a few of everything. */
+    perTokenLimit?: number;
+    /** Max in-flight token queries. */
+    concurrency?: number;
+}
+interface ReferenceSearchCandidatesFn {
+    (args: {
+        p_token: string;
+        p_search?: string;
+        p_limit?: number;
+        p_ids?: string[];
+    }): Promise<{
+        data: Array<{
+            id: string;
+            title: string | null;
+        }>;
+        error: null;
+    } | {
+        data: null;
+        error: {
+            message: string;
+        };
+    }>;
+}
+interface CandidatesServiceApi {
+    /**
+     * The universal candidate reader RPC (`public.reference_search_candidates`)
+     * — shared by candidate search here and title resolution in titles.ts.
+     */
+    callReferenceSearchCandidates: ReferenceSearchCandidatesFn;
+    listAssociationCandidates(args: ListCandidatesArgs): Promise<CandidatesResult>;
+    /**
+     * ONE search over EVERY listable entity type — the "attach anything from
+     * anywhere" primitive. Registry-driven client fan-out, capped and
+     * concurrency-limited. Per-token failures are screamed and skipped — one
+     * broken table never blanks the search.
+     */
+    searchCandidatesAcrossTokens(args: SearchAcrossTokensArgs): Promise<UniversalCandidate[]>;
+}
+declare function createCandidatesService(deps: CoreDeps): CandidatesServiceApi;
+
+declare function entityTitleCacheKey(token: string, id: string): string;
+interface TitlesServiceApi {
+    /** Read the cache synchronously (for render paths after a fetch settled). */
+    get(token: string, id: string): string | null;
+    /**
+     * Push a known-fresh title into the cache (after a rename or a create), so
+     * surfaces that resolve through this service never show a stale name.
+     */
+    prime(token: string, id: string, title: string): void;
+    /** Display fallback when no label and no fetched title exist. */
+    fallback(token: string): string;
+    /**
+     * Resolve titles for `ids` of one token. Returns ONLY the resolved entries
+     * (cache + fresh reads); missing rows (deleted, no access) stay absent.
+     */
+    fetch(token: string, ids: string[]): Promise<Map<string, string>>;
+}
+declare function createTitlesService(deps: CoreDeps, candidates: CandidatesServiceApi): TitlesServiceApi;
+
+type EntityRowResult = {
+    ok: true;
+    data: {
+        id: string;
+        title: string;
+    };
+} | {
+    ok: false;
+    error: string;
+};
+interface CreateEntityRowArgs {
+    /** The new row's human name — written to the registry `titleColumn`. */
+    title: string;
+    /** Org to stamp (skipped when the token has no org column). */
+    orgId?: string | null;
+    /** Required NOT NULL columns the registry conventions can't know about. */
+    extraColumns?: Record<string, unknown>;
+}
+interface EntityRowsServiceApi {
+    createEntityRow(token: EntityTypeToken, args: CreateEntityRowArgs): Promise<EntityRowResult>;
+    renameEntityRow(token: EntityTypeToken, id: string, title: string): Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        error: string;
+    }>;
+}
+declare function createEntityRowsService(deps: CoreDeps, titles: TitlesServiceApi): EntityRowsServiceApi;
+
+/** A typed reference to a single row — `{ type, id }`. */
+interface EntityRef {
+    type: EntityTypeToken;
+    id: string;
+}
+/** A container reference — the deliberate set an edge may point at. */
+interface ContainerRef {
+    type: AssociationTargetType;
+    id: string;
+}
+/** Per-edge attributes shared by the link helpers. */
+interface EdgeAttrs {
+    orgId?: string;
+    label?: string;
+    metadata?: unknown;
+    role?: string;
+    position?: number;
+}
+/** One fully-specified edge for {@link AssociationHelpersApi.linkEdges}. */
+interface EdgeSpec extends EdgeAttrs {
+    source: EntityRef;
+    target: ContainerRef;
+}
+interface AssociationHelpersApi {
+    /**
+     * Add an arbitrary batch of edges in one call (idempotent per edge).
+     * Best-effort: every edge is attempted; the result is `ok` with the
+     * created ids only when ALL succeed, otherwise `err` whose `detail` lists
+     * every failure (the edges that DID succeed remain applied — re-running is
+     * safe via ON CONFLICT).
+     */
+    linkEdges(edges: EdgeSpec[]): Promise<AssociationsRpcResult<{
+        ids: string[];
+    }>>;
+    /** Attach ONE source to MANY containers in a single shot. */
+    linkOneToMany(args: {
+        source: EntityRef;
+        targets: ContainerRef[];
+        attrs?: EdgeAttrs;
+    }): Promise<AssociationsRpcResult<{
+        ids: string[];
+    }>>;
+    /** Attach MANY sources to ONE container in a single shot. */
+    linkManyToOne(args: {
+        sources: EntityRef[];
+        target: ContainerRef;
+        attrs?: EdgeAttrs;
+    }): Promise<AssociationsRpcResult<{
+        ids: string[];
+    }>>;
+    /**
+     * REPLACE the full set of a source's edges of one container type (adds
+     * missing, removes extras) in one DB transaction — the set-semantics
+     * one-shot. Thin, named pass-through to `assoc_set_targets`.
+     */
+    replaceTargets(args: {
+        source: EntityRef;
+        targetType: AssociationTargetType;
+        targetIds: string[];
+        orgId?: string;
+        role?: string;
+    }): Promise<AssociationsRpcResult<null>>;
+    /**
+     * Wire edges onto a JUST-CREATED entity. The caller inserts its own row
+     * (entity tables are feature-owned), then passes the new id here to attach
+     * it to any number of containers (orphan-on-partial-fail is harmless and
+     * re-runnable). `created` is the new entity; it becomes the edges' SOURCE.
+     */
+    linkCreated(args: {
+        created: EntityRef;
+        targets: ContainerRef[];
+        attrs?: EdgeAttrs;
+    }): Promise<AssociationsRpcResult<{
+        ids: string[];
+    }>>;
+    /** Remove an arbitrary batch of edges (best-effort; no-op per missing edge). */
+    unlinkEdges(edges: {
+        source: EntityRef;
+        target: ContainerRef;
+        role?: string;
+    }[]): Promise<AssociationsRpcResult<null>>;
+}
+declare function createAssociationHelpers(service: AssociationsServiceApi): AssociationHelpersApi;
+
+/** Cache key for one association endpoint. */
+declare function associationsKey(type: string, id: string): string;
+interface AssociationWriteResult {
+    ok: boolean;
+    /** Set on a successful single-edge `add`. */
+    id?: string;
+    error?: string;
+}
+interface CategoryMutationResult {
+    ok: boolean;
+    /** Set on a successful mutation. */
+    id?: string;
+    error?: string;
+}
+interface AssociationsStore {
+    /** Stable, sync read of one endpoint's entry (idle default when uncached). */
+    getEdges(type: string, id: string): AssociationsEntry;
+    /**
+     * Lazy load of every edge touching `${type}:${id}` (both directions).
+     * Deduped per key; `status === "ready"` short-circuits unless `force`.
+     */
+    load(type: string, id: string, opts?: {
+        force?: boolean;
+    }): Promise<void>;
+    /** External-store contract: notified whenever the key's entry changes. */
+    subscribe(key: string, cb: () => void): () => void;
+    /** Attach source → target; on success reloads BOTH endpoints. */
+    add(args: {
+        sourceType: string;
+        sourceId: string;
+        targetType: AssociationTargetType;
+        targetId: string;
+        orgId?: string;
+        label?: string;
+        role?: string;
+        metadata?: unknown;
+        replaceMetadata?: boolean;
+    }): Promise<AssociationWriteResult>;
+    /** Detach source → target; on success reloads BOTH endpoints. */
+    remove(args: {
+        sourceType: string;
+        sourceId: string;
+        targetType: string;
+        targetId: string;
+        role?: string;
+    }): Promise<AssociationWriteResult>;
+    /** Replace the source's `targetType` edge set; reloads the SOURCE. */
+    setTargets(args: {
+        sourceType: string;
+        sourceId: string;
+        targetType: AssociationTargetType;
+        targetIds: string[];
+        orgId?: string;
+        role?: string;
+    }): Promise<AssociationWriteResult>;
+    /** Reset one endpoint to idle and notify its subscribers. */
+    invalidate(type: string, id: string): void;
+    /** Reset every association endpoint AND every category facet. */
+    invalidateAll(): void;
+    getCategories(dimension: CategoryDimension): CategoriesEntry;
+    loadCategories(dimension: CategoryDimension, opts?: {
+        force?: boolean;
+    }): Promise<void>;
+    subscribeCategories(dimension: CategoryDimension, cb: () => void): () => void;
+    /** Create + echo-insert + authoritative force reload. Returns the new id. */
+    createCategory(args: {
+        dimension: CategoryDimension;
+        name: string;
+        orgId: string;
+        parentId?: string | null;
+        color?: string | null;
+        icon?: string | null;
+        slug?: string | null;
+    }): Promise<CategoryMutationResult>;
+    updateCategory(args: {
+        dimension: CategoryDimension;
+        id: string;
+        name: string;
+        slug: string | null;
+        color: string | null;
+        icon: string | null;
+        position: number | null;
+    }): Promise<CategoryMutationResult>;
+    reparentCategory(args: {
+        dimension: CategoryDimension;
+        id: string;
+        parentId: string | null;
+    }): Promise<CategoryMutationResult>;
+    deleteCategory(args: {
+        dimension: CategoryDimension;
+        id: string;
+    }): Promise<CategoryMutationResult>;
+    /** Batched title resolution + the session cache + prime. */
+    titles: TitlesServiceApi;
+    /** Per-user favorite/pinned/hidden state (`ues_*`). */
+    favorites: FavoritesServiceApi;
+    /** Candidate reads for the pickers. */
+    candidates: CandidatesServiceApi;
+    /** Generic registry-convention row create/rename. */
+    entityRows: EntityRowsServiceApi;
+    /** Composite link helpers over the chokepoint. */
+    helpers: AssociationHelpersApi;
+    /** The registry merge engine (generated metadata + host overlay). */
+    registry: EntityRegistry;
+    /**
+     * The raw chokepoint services — every RPC family, results-enveloped.
+     * `associations` writes here do NOT touch the cache; use the store-level
+     * `add`/`remove`/`setTargets` when a cached surface must stay fresh.
+     */
+    services: {
+        associations: AssociationsServiceApi;
+        categories: CategoriesServiceApi;
+    };
+    /** Merge more host overlay entries in (icons/routes/candidate loaders). */
+    registerEntityOverlay: EntityRegistry["registerEntityOverlay"];
+}
+/**
+ * Build the one store a host binds. REQUIRED ports (dataSource / identity /
+ * errorSink) throw at construction when absent — never degraded. Every
+ * optional port degrades per its documented contract.
+ */
+declare function createAssociationsStore(config: AssociationsConfig): AssociationsStore;
+
+/** The name the self-test probes; MUST NOT exist in any schema. */
+declare const SELF_TEST_MISSING_RPC = "assoc_probe_self_test_missing_fn";
+interface DemandedSchemaReport {
+    ok: boolean;
+    /** Demanded functions the database cannot answer (PGRST202). */
+    missing: string[];
+    /** Functions the probe could not reach (transport/unknown failure). */
+    unreachable: {
+        fn: string;
+        error: unknown;
+    }[];
+    /** Functions that answered (success or any non-PGRST202 refusal). */
+    answered: string[];
+}
+interface AssertDemandedSchemaOptions {
+    /**
+     * Also probe a fabricated function name and REQUIRE it to come back
+     * missing — proves the probe can fail (the falsifiability rule).
+     */
+    selfTest?: boolean;
+    /** Max in-flight probe calls (default 6). */
+    concurrency?: number;
+    /**
+     * Return the report instead of throwing on violation (for surfaces that
+     * render the report). The self-test failure ALWAYS throws.
+     */
+    throwOnViolation?: boolean;
+}
+/**
+ * Probe every demanded RPC against `dataSource`. Throws an `Error` naming
+ * every missing function when the database violates the demanded schema
+ * (unless `throwOnViolation: false`), and ALWAYS throws when the probe
+ * itself cannot be trusted (unreachable database, failed self-test).
+ */
+declare function assertDemandedSchema(dataSource: AssociationsDataSource, options?: AssertDemandedSchemaOptions): Promise<DemandedSchemaReport>;
+
+/** Source tokens that are structure, never container content. */
+declare const NON_CONTENT_SOURCE_TYPES: ReadonlySet<string>;
+/** True when edge metadata marks a container-membership edge. */
+declare function isMembershipMetadata(metadata: unknown): boolean;
+/**
+ * True when an edge into a container represents CONTENT the container holds.
+ * `sourceType` is the edge's raw `source_type` token; `metadata` the edge's
+ * jsonb (pass it when available so membership edges are excluded even if a
+ * structural token is ever missed).
+ */
+declare function isContentSourceEdge(sourceType: string, metadata?: unknown): boolean;
+
+export { type AddAssociationArgs, type AssertDemandedSchemaOptions, type AssociationGuards, type AssociationHelpersApi, type AssociationWriteResult, type AssociationsServiceApi, type AssociationsStore, type CandidateRecord, type CandidatesResult, type CandidatesServiceApi, type CategoriesServiceApi, type CategoryMutationResult, type ContainerRef, type ContentRole, type ConversationFileLink, type CoreDeps, type CreateEntityRowArgs, DEFAULT_ORG_COLUMN, DEFAULT_OWNER_COLUMN, type DemandedSchemaReport, type EdgeAttrs, type EdgeSpec, type EntityInfo, type EntityRef, type EntityRegistry, type EntityRowResult, type EntityRowsServiceApi, type FavoritesServiceApi, type ListCandidatesArgs, NON_CONTENT_SOURCE_TYPES, type PgErrorMapper, type RpcResultHelpers, SELF_TEST_MISSING_RPC, type SearchAcrossTokensArgs, type TitlesServiceApi, type UniversalCandidate, assertDemandedSchema, associationsKey, createAssociationGuards, createAssociationHelpers, createAssociationsService, createAssociationsStore, createCandidatesService, createCategoriesService, createEntityRegistry, createEntityRowsService, createFavoritesService, createRpcResultHelpers, createTitlesService, entityTitleCacheKey, err, firstError, isContentRole, isContentSourceEdge, isMembershipMetadata, isTransportFailure, isUuid, ok, resolveEntityToken };