@captiveorigins/payload-plugin-onepedigree 0.0.0-stage → 0.1.0-alpha.4

package/dist/fields.js

@@ -0,0 +1,135 @@
+import { PARENT_TERM_PRESETS, REPRODUCTIVE_MODES, resolveParentTerms } from '@captiveorigins/onepedigree-core';
+const BUILT_IN_ROLES = ['mother', 'father', 'dam', 'sire', 'egg', 'sperm', 'donor', 'parent', 'contributor'];
+const MODE_LABELS = {
+    sexual: 'Sexual',
+    parthenogenesis: 'Parthenogenesis',
+    self: 'Self',
+    asexual: 'Asexual',
+    cloning: 'Cloning',
+    other: 'Other',
+};
+const label = (s) => s[0].toUpperCase() + s.slice(1);
+/** The canonical parents array: any number of contributors, each with an optional role. */
+export const createParentsField = (o) => ({
+    name: 'parents',
+    label: 'All parents',
+    type: 'array',
+    admin: {
+        initCollapsed: true,
+        description: 'Every recorded parent (the pickers above edit the rows with their roles). Add other contributors or unknown-role parents here; roles are never inferred from sex.',
+    },
+    fields: [
+        {
+            type: 'row',
+            fields: [
+                // Indexed: descendant queries look parents up by this path.
+                { name: 'individual', type: 'relationship', relationTo: o.individuals, required: true, index: true, admin: { width: '60%' } },
+                {
+                    name: 'role',
+                    type: 'select',
+                    options: [...new Set([...BUILT_IN_ROLES, ...(o.roles ?? [])])].map((value) => ({ label: label(value), value })),
+                    admin: { width: '40%' },
+                },
+            ],
+        },
+    ],
+});
+export const createReproductiveModeField = (o = {}) => ({
+    name: 'reproductiveMode',
+    type: 'select',
+    options: REPRODUCTIVE_MODES.map((value) => ({ label: MODE_LABELS[value], value })),
+    ...(o.defaultValue ? { defaultValue: o.defaultValue } : {}),
+    admin: { description: 'How this individual originated. Empty means unknown. Changing it never adds or removes parents.' },
+});
+export const createCohortField = (o) => ({
+    name: 'cohort',
+    type: 'relationship',
+    relationTo: o.cohorts,
+    index: true,
+    admin: { description: 'The birthing event: a clutch, litter or other group born to the same mother at the same time. Fathers may differ.' },
+});
+const CLIENT = '@captiveorigins/payload-plugin-onepedigree/client';
+const rowId = (v) => (v && typeof v === 'object' && 'id' in v ? String(v.id) : v ? String(v) : null);
+/**
+ * A Mother/Father (or Dam/Sire) picker backed by the canonical parents array:
+ * shows the first parent with the role, and on save replaces the rows with
+ * that role when the picker changed. Not stored itself (virtual).
+ */
+export const createRoleSelectorField = (o) => {
+    const role = o.side === 'maternal' ? 'mother' : 'father';
+    const terms = resolveParentTerms(o.terms);
+    return {
+        name: role,
+        label: terms[o.side],
+        type: 'relationship',
+        relationTo: o.individuals,
+        virtual: true,
+        admin: {
+            width: '50%',
+            // Payload makes virtual fields read-only unless told otherwise.
+            readOnly: false,
+            // The label follows the signed-in user's preferred terms (e.g. Dam/Sire).
+            components: { Label: { path: `${CLIENT}#ParentRoleLabel`, clientProps: { side: o.side, defaultTerms: terms, userPreference: o.userPreference ?? null } } },
+        },
+        hooks: {
+            afterRead: [({ siblingData }) => rowId((siblingData?.parents ?? []).find((r) => r.role === role)?.individual)],
+            beforeChange: [
+                ({ value, siblingData, previousSiblingDoc }) => {
+                    if (value === undefined)
+                        return undefined;
+                    const before = rowId((previousSiblingDoc?.parents ?? []).find((r) => r.role === role)?.individual);
+                    const next = rowId(value);
+                    if (next === before)
+                        return undefined;
+                    const rows = (siblingData.parents ?? []).filter((r) => r.role !== role);
+                    siblingData.parents = next ? [{ individual: next, role }, ...rows] : rows;
+                    return undefined;
+                },
+            ],
+        },
+    };
+};
+/**
+ * A user's own words for the parent roles (add to your users collection and
+ * pass its path as `terminology.userPreference`). Display only.
+ */
+export const createParentTermsPreferenceField = (o = {}) => ({
+    name: o.name ?? 'parentTerms',
+    label: 'Parent labels',
+    type: 'group',
+    admin: { description: 'How pedigrees name the two parents for you. Stored data is the same either way.' },
+    fields: [
+        {
+            name: 'preset',
+            type: 'select',
+            options: [...Object.entries(PARENT_TERM_PRESETS).map(([value, p]) => ({ label: p.label, value })), { label: 'Custom', value: 'custom' }],
+            admin: { description: 'Empty: the site default.' },
+        },
+        {
+            type: 'row',
+            admin: { condition: (_, sibling) => sibling?.preset === 'custom' },
+            fields: [
+                { name: 'maternal', type: 'text', maxLength: 40, admin: { width: '50%', placeholder: 'Mother' } },
+                { name: 'paternal', type: 'text', maxLength: 40, admin: { width: '50%', placeholder: 'Father' } },
+            ],
+        },
+    ],
+});
+/** The standard `parentage` group (parents, reproductive mode, cohort), with Mother/Father pickers unless `selectors` is false. */
+export const createParentageField = (o) => ({
+    name: 'parentage',
+    type: 'group',
+    fields: [
+        ...(o.selectors === false
+            ? []
+            : [
+                {
+                    type: 'row',
+                    fields: ['maternal', 'paternal'].map((side) => createRoleSelectorField({ individuals: o.individuals, side, terms: o.terms, userPreference: o.userPreference })),
+                },
+            ]),
+        createParentsField({ individuals: o.individuals, roles: o.roles }),
+        createReproductiveModeField({ defaultValue: o.defaultMode }),
+        ...(o.cohorts ? [createCohortField({ cohorts: o.cohorts })] : []),
+    ],
+});

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export { onePedigree } from './plugin.js';
+export { createCohortsCollection, createIndividualsCollection } from './collections.js';
+export { createCohortField, createParentageField, createParentsField, createParentTermsPreferenceField, createReproductiveModeField, createRoleSelectorField } from './fields.js';
+export { checkParentage, cohortBirthParentBeforeChange, parentageBeforeChange, parentBeforeDelete, SKIP } from './integrity.js';
+export { getPedigree, getRelatives, payloadRepository, redact, type PedigreeQuery, type Summary } from './endpoints.js';
+export { documentAdapter, readParents, resolveOptions, termsFor, toIndividual } from './mapping.js';
+export type { OnePedigreePluginOptions, ParentageMapping, ResolvedOptions } from './types.js';
+/** The resolved options of the installed plugin (for host pages calling getPedigree / getRelatives). */
+export declare const pluginOptions: (config: {
+    custom?: Record<string, unknown>;
+}) => import("./types.js").ResolvedOptions;

package/dist/index.js

@@ -0,0 +1,8 @@
+export { onePedigree } from './plugin.js';
+export { createCohortsCollection, createIndividualsCollection } from './collections.js';
+export { createCohortField, createParentageField, createParentsField, createParentTermsPreferenceField, createReproductiveModeField, createRoleSelectorField } from './fields.js';
+export { checkParentage, cohortBirthParentBeforeChange, parentageBeforeChange, parentBeforeDelete, SKIP } from './integrity.js';
+export { getPedigree, getRelatives, payloadRepository, redact } from './endpoints.js';
+export { documentAdapter, readParents, resolveOptions, termsFor, toIndividual } from './mapping.js';
+/** The resolved options of the installed plugin (for host pages calling getPedigree / getRelatives). */
+export const pluginOptions = (config) => config.custom?.onepedigree;

package/dist/integrity.d.ts

@@ -0,0 +1,41 @@
+import { type ParentReference, type PedigreeIssue, type ReproductiveModeId } from '@captiveorigins/onepedigree-core';
+import { type CollectionBeforeChangeHook, type CollectionBeforeDeleteHook, type CollectionBeforeOperationHook, type PayloadRequest } from 'payload';
+import type { ResolvedOptions } from './types.js';
+/** Context flag for the plugin's own writes (detaching references, internal updates). */
+export declare const SKIP = "onepedigreeInternal";
+/** Set per operation: whether access control is bypassed (trusted server code), so parent readability is not checked. */
+export declare const TRUSTED = "onepedigreeOverrideAccess";
+/**
+ * Checks a proposed parentage for one individual against the stored graph:
+ * self-reference, duplicates, parents the requester cannot read (or that do
+ * not exist), cycles through the full descendant line (read with full access:
+ * integrity must not depend on what the editor can see), host rules, and
+ * structural notices.
+ */
+export declare function checkParentage(req: PayloadRequest, opts: ResolvedOptions, proposal: {
+    id?: string | null;
+    parents: readonly ParentReference[];
+    reproductiveMode?: ReproductiveModeId | null;
+    cohort?: string | null;
+    doc?: Record<string, unknown>;
+}, { trusted }?: {
+    trusted?: boolean;
+}): Promise<PedigreeIssue[]>;
+/**
+ * Validates parentage on every write path (Admin, REST, GraphQL, Local API,
+ * imports) and serializes parentage changes: the graph revision global is
+ * updated in the same transaction, so two concurrent parentage writes cannot
+ * both commit (MongoDB write conflict) and jointly create a cycle.
+ */
+export declare const parentageBeforeChange: (opts: ResolvedOptions) => CollectionBeforeChangeHook;
+/** Records whether this create/update bypasses access control (Local API default), for the readability check. */
+export declare const rememberAccessMode: CollectionBeforeOperationHook;
+/** Deleting a recorded parent: refuse (archive instead) or remove the references, per the plugin option. */
+export declare const parentBeforeDelete: (opts: ResolvedOptions) => CollectionBeforeDeleteHook;
+/** Structure of a document's recorded parentage (for Admin notices). */
+export declare const structureOf: (doc: Record<string, unknown>, opts: ResolvedOptions) => import("@captiveorigins/onepedigree-core").ReproductiveStructure;
+/**
+ * Cohorts: setting or changing the birthing parent is refused while members
+ * record a different mother (fix the members first, or move them to their own cohort).
+ */
+export declare const cohortBirthParentBeforeChange: (opts: ResolvedOptions) => CollectionBeforeChangeHook;

package/dist/integrity.js

@@ -0,0 +1,211 @@
+import { reproductiveStructure, validatePedigree, } from '@captiveorigins/onepedigree-core';
+import { APIError, ValidationError, } from 'payload';
+import { childrenWhere, getAt, graphSelect, idOf, maternalRoles, readCohort, readMode, readParents, toIndividual } from './mapping.js';
+/** Context flag for the plugin's own writes (detaching references, internal updates). */
+export const SKIP = 'onepedigreeInternal';
+/** Set per operation: whether access control is bypassed (trusted server code), so parent readability is not checked. */
+export const TRUSTED = 'onepedigreeOverrideAccess';
+const MAX_DESCENDANTS = 100_000;
+const err = (code, message, path, relatedIds) => ({
+    severity: 'error',
+    code,
+    message,
+    ...(path ? { path } : {}),
+    ...(relatedIds ? { relatedIds } : {}),
+});
+const parentsPath = (opts) => (opts.fields.parentage.kind === 'parent-array' ? `${opts.fields.parentage.path}.parents` : Object.values(opts.fields.parentage.roles)[0]);
+/**
+ * Checks a proposed parentage for one individual against the stored graph:
+ * self-reference, duplicates, parents the requester cannot read (or that do
+ * not exist), cycles through the full descendant line (read with full access:
+ * integrity must not depend on what the editor can see), host rules, and
+ * structural notices.
+ */
+export async function checkParentage(req, opts, proposal, { trusted = false } = {}) {
+    const issues = [];
+    const path = parentsPath(opts);
+    const ids = proposal.parents.map((p) => p.individual);
+    if (proposal.id && ids.includes(proposal.id))
+        issues.push(err('SELF_PARENT', 'An individual cannot be its own parent.', path));
+    if (new Set(ids).size !== ids.length)
+        issues.push(err('DUPLICATE_PARENT', 'The same parent is listed more than once.', path));
+    const unique = [...new Set(ids)];
+    const visible = unique.length
+        ? (await req.payload.find({
+            collection: opts.collection,
+            where: { id: { in: unique } },
+            depth: 0,
+            pagination: false,
+            select: graphSelect(opts),
+            overrideAccess: trusted,
+            req,
+        })).docs
+        : [];
+    const seen = new Set(visible.map((d) => String(d.id)));
+    // Same message whether missing or private: nothing is revealed about records the editor cannot read.
+    for (const p of unique)
+        if (!seen.has(p))
+            issues.push(err('UNRESOLVED_PARENT', 'A parent does not exist or you cannot access it.', path, [p]));
+    if (proposal.id && unique.length) {
+        const proposed = new Set(unique);
+        const reached = new Set([proposal.id]);
+        let frontier = [proposal.id];
+        while (frontier.length && !issues.some((i) => i.code === 'PARENT_IS_DESCENDANT')) {
+            const { docs } = await req.payload.find({
+                collection: opts.collection,
+                where: childrenWhere(opts, frontier),
+                depth: 0,
+                pagination: false,
+                select: {},
+                overrideAccess: true,
+                req,
+            });
+            frontier = [];
+            for (const d of docs) {
+                const c = String(d.id);
+                if (reached.has(c))
+                    continue;
+                reached.add(c);
+                if (proposed.has(c))
+                    issues.push(err('PARENT_IS_DESCENDANT', 'This parent already descends from the individual; the pedigree would loop.', path, [c]));
+                frontier.push(c);
+            }
+            if (reached.size > MAX_DESCENDANTS) {
+                issues.push(err('TRAVERSAL_LIMIT', 'Too many descendants to verify this change safely.', path));
+                break;
+            }
+        }
+    }
+    // A cohort is one birthing event: the member's recorded mother must be the cohort's birthing parent.
+    if (proposal.cohort && opts.cohorts?.birthParentField) {
+        const cohort = await req.payload.findByID({
+            collection: opts.cohorts.collection,
+            id: proposal.cohort,
+            depth: 0,
+            overrideAccess: true,
+            disableErrors: true,
+            req,
+        });
+        const birthParent = idOf(cohort ? getAt(cohort, opts.cohorts.birthParentField) : null);
+        const mothers = proposal.parents.filter((p) => p.role && maternalRoles(opts).includes(p.role)).map((p) => p.individual);
+        if (birthParent && mothers.some((m) => m !== birthParent))
+            issues.push(err('COHORT_BIRTH_PARENT_MISMATCH', 'This mother differs from the mother of the selected birthing event (cohort).', opts.fields.parentage.cohort ?? path));
+    }
+    // Host rules and structural notices on the proposed record with its visible parents.
+    const self = {
+        ...(proposal.doc ? toIndividual({ ...proposal.doc, id: proposal.id ?? '(new)' }, opts) : { id: proposal.id ?? '(new)' }),
+        parentage: { parents: proposal.parents, reproductiveMode: proposal.reproductiveMode ?? null, cohort: proposal.cohort ?? null },
+    };
+    // The record itself is never one of its own parents here (reported above as SELF_PARENT).
+    const others = visible.filter((d) => String(d.id) !== self.id).map((d) => toIndividual(d, opts));
+    const document = { schemaVersion: 1, individuals: [self, ...others] };
+    const result = validatePedigree(document, { complete: false, rules: opts.rules, birthParentRoles: maternalRoles(opts) });
+    for (const i of result.issues)
+        if (i.individualId === self.id && !['SELF_PARENT', 'DUPLICATE_PARENT', 'ANCESTRY_CYCLE'].includes(i.code))
+            issues.push({ ...i, path: i.path ?? path });
+    // Rules may report on other records too; only errors about this write block it.
+    return issues;
+}
+const same = (a, b) => a.length === b.length && a.every((p, i) => p.individual === b[i].individual && (p.role ?? null) === (b[i].role ?? null));
+/**
+ * Validates parentage on every write path (Admin, REST, GraphQL, Local API,
+ * imports) and serializes parentage changes: the graph revision global is
+ * updated in the same transaction, so two concurrent parentage writes cannot
+ * both commit (MongoDB write conflict) and jointly create a cycle.
+ */
+export const parentageBeforeChange = (opts) => async ({ data, originalDoc, req, context, operation }) => {
+    if (context[SKIP])
+        return data;
+    const merged = { ...(originalDoc ?? {}), ...data };
+    const id = operation === 'update' ? (idOf(originalDoc?.id) ?? null) : null;
+    const parents = readParents(merged, opts);
+    const mode = readMode(merged, opts);
+    const cohort = readCohort(merged, opts);
+    const before = originalDoc ? readParents(originalDoc, opts) : [];
+    if (operation === 'update' && same(parents, before) && mode === readMode(originalDoc, opts) && cohort === readCohort(originalDoc, opts))
+        return data;
+    const issues = await checkParentage(req, opts, { id, parents, reproductiveMode: mode, cohort, doc: merged }, { trusted: context[TRUSTED] === true });
+    const errors = issues.filter((i) => i.severity === 'error');
+    if (errors.length)
+        throw new ValidationError({
+            collection: opts.collection,
+            errors: errors.map((e) => ({ path: e.path ?? 'parentage', message: e.message })),
+        });
+    if (!same(parents, before)) {
+        const current = (await req.payload.findGlobal({ slug: opts.graphGlobal, depth: 0, overrideAccess: true, req }));
+        await req.payload.updateGlobal({
+            slug: opts.graphGlobal,
+            data: { revision: (current?.revision ?? 0) + 1 },
+            overrideAccess: true,
+            context: { [SKIP]: true },
+            req,
+        });
+    }
+    return data;
+};
+/** Records whether this create/update bypasses access control (Local API default), for the readability check. */
+export const rememberAccessMode = ({ args, operation, context }) => {
+    if (operation === 'create' || operation === 'update' || operation === 'updateByID')
+        context[TRUSTED] = args.overrideAccess !== false;
+    return args;
+};
+/** Deleting a recorded parent: refuse (archive instead) or remove the references, per the plugin option. */
+export const parentBeforeDelete = (opts) => async ({ id, req, context }) => {
+    if (context[SKIP])
+        return;
+    const { docs } = await req.payload.find({
+        collection: opts.collection,
+        where: childrenWhere(opts, [String(id)]),
+        depth: 0,
+        pagination: false,
+        limit: opts.onReferencedIndividualDelete === 'restrict' ? 1 : 0,
+        overrideAccess: true,
+        req,
+    });
+    if (!docs.length)
+        return;
+    if (opts.onReferencedIndividualDelete === 'restrict')
+        throw new APIError('This individual is a recorded parent. Archive it instead, or remove it from its offspring first.', 409);
+    const m = opts.fields.parentage;
+    for (const child of docs) {
+        const data = m.kind === 'role-fields'
+            ? Object.fromEntries(Object.values(m.roles).filter((p) => idOf(getAt(child, p)) === String(id)).map((p) => [p, null]))
+            : {
+                [m.path]: {
+                    ...(getAt(child, m.path) ?? {}),
+                    parents: (getAt(child, `${m.path}.parents`) ?? []).filter((r) => idOf(r[m.individualField]) !== String(id)),
+                },
+            };
+        await req.payload.update({ collection: opts.collection, id: child.id, data: data, overrideAccess: true, context: { [SKIP]: true }, req });
+    }
+};
+/** Structure of a document's recorded parentage (for Admin notices). */
+export const structureOf = (doc, opts) => reproductiveStructure(toIndividual(doc, opts));
+/**
+ * Cohorts: setting or changing the birthing parent is refused while members
+ * record a different mother (fix the members first, or move them to their own cohort).
+ */
+export const cohortBirthParentBeforeChange = (opts) => async ({ data, originalDoc, req, operation, context }) => {
+    const field = opts.cohorts?.birthParentField;
+    if (!field || operation !== 'update' || context[SKIP])
+        return data;
+    const next = idOf(getAt({ ...originalDoc, ...data }, field));
+    if (!next || next === idOf(getAt(originalDoc, field)))
+        return data;
+    const { docs } = await req.payload.find({
+        collection: opts.collection,
+        where: { [opts.fields.parentage.cohort]: { equals: originalDoc.id } },
+        depth: 0,
+        pagination: false,
+        select: graphSelect(opts),
+        overrideAccess: true,
+        req,
+    });
+    const conflicting = docs.filter((d) => readParents(d, opts).some((p) => p.role && maternalRoles(opts).includes(p.role) && p.individual !== next)).length;
+    if (conflicting)
+        throw new ValidationError({
+            collection: opts.cohorts.collection,
+            errors: [{ path: field, message: `${conflicting} member(s) of this birthing event record a different mother.` }],
+        });
+    return data;
+};

package/dist/mapping.d.ts

@@ -0,0 +1,22 @@
+import { type Individual, type ParentReference, type PedigreeAdapter, type ReproductiveModeId } from '@captiveorigins/onepedigree-core';
+import type { Where } from 'payload';
+import type { OnePedigreePluginOptions, ResolvedOptions } from './types.js';
+export declare const idOf: (v: unknown) => string | null;
+export declare const getAt: (doc: unknown, path: string) => unknown;
+export declare function resolveOptions(o: OnePedigreePluginOptions): ResolvedOptions;
+/** The stored parent references of a document (relationship values may be IDs or populated docs). */
+export declare function readParents(doc: unknown, opts: ResolvedOptions): ParentReference[];
+export declare const readMode: (doc: unknown, opts: ResolvedOptions) => ReproductiveModeId | null;
+export declare const readCohort: (doc: unknown, opts: ResolvedOptions) => string | null;
+/** Paths that hold parent IDs, for queries and indexes. */
+export declare function parentPaths(opts: ResolvedOptions): string[];
+/** Records that list any of `ids` as a parent. */
+export declare const childrenWhere: (opts: ResolvedOptions, ids: readonly string[]) => Where;
+/** Fields to read for the graph (keeps queries small; never the whole document). */
+export declare function graphSelect(opts: ResolvedOptions): Record<string, true>;
+export declare function documentAdapter(opts: ResolvedOptions): PedigreeAdapter<Record<string, unknown>>;
+export declare const toIndividual: (doc: Record<string, unknown>, opts: ResolvedOptions) => Individual;
+/** Maternal (birthing) roles. */
+export declare const maternalRoles: (opts: ResolvedOptions) => readonly string[];
+/** Parent terms for a request: the user's preference (if configured), else the installation default. */
+export declare function termsFor(opts: ResolvedOptions, user: unknown): Promise<import("@captiveorigins/onepedigree-core").ParentTerms>;

package/dist/mapping.js

@@ -0,0 +1,105 @@
+import { adaptIndividual, REPRODUCTIVE_MODES } from '@captiveorigins/onepedigree-core';
+export const idOf = (v) => v && typeof v === 'object' && 'id' in v ? String(v.id) : v !== undefined && v !== null && v !== '' ? String(v) : null;
+export const getAt = (doc, path) => path.split('.').reduce((o, k) => (o && typeof o === 'object' ? o[k] : undefined), doc);
+export function resolveOptions(o) {
+    const mapping = o.fields?.parentage ?? { kind: 'parent-array' };
+    const parentage = mapping.kind === 'role-fields'
+        ? mapping
+        : {
+            kind: 'parent-array',
+            path: mapping.path ?? 'parentage',
+            individualField: mapping.individualField ?? 'individual',
+            roleField: mapping.roleField ?? 'role',
+            reproductiveMode: mapping.reproductiveMode ?? `${mapping.path ?? 'parentage'}.reproductiveMode`,
+            cohort: mapping.cohort ?? `${mapping.path ?? 'parentage'}.cohort`,
+        };
+    return {
+        ...o,
+        mode: o.mode ?? 'standard-fields',
+        hiddenRecords: o.hiddenRecords ?? 'omit',
+        onReferencedIndividualDelete: o.onReferencedIndividualDelete ?? 'restrict',
+        fields: { label: o.fields?.label ?? 'name', sex: o.fields?.sex ?? 'sex', parentage, display: o.fields?.display ?? [] },
+        cohorts: o.cohorts
+            ? { collection: o.cohorts.collection, label: o.cohorts.label ?? 'name', managed: o.cohorts.managed ?? false, birthParentField: o.cohorts.birthParentField ?? null }
+            : null,
+        limits: { maxDepth: o.limits?.maxDepth ?? 10, maxNodes: o.limits?.maxNodes ?? 500 },
+        graphGlobal: `${o.collection}-pedigree-graph`,
+        settingsGlobal: 'pedigree-settings',
+    };
+}
+/** The stored parent references of a document (relationship values may be IDs or populated docs). */
+export function readParents(doc, opts) {
+    const m = opts.fields.parentage;
+    if (m.kind === 'role-fields')
+        return Object.entries(m.roles).flatMap(([role, path]) => {
+            const id = idOf(getAt(doc, path));
+            return id ? [{ individual: id, role }] : [];
+        });
+    const rows = getAt(doc, `${m.path}.parents`);
+    if (!Array.isArray(rows))
+        return [];
+    return rows.flatMap((r) => {
+        const id = idOf(r?.[m.individualField]);
+        const role = r?.[m.roleField];
+        return id ? [{ individual: id, role: typeof role === 'string' && role ? role : null }] : [];
+    });
+}
+export const readMode = (doc, opts) => {
+    const path = opts.fields.parentage.reproductiveMode;
+    const v = path ? getAt(doc, path) : null;
+    return typeof v === 'string' && REPRODUCTIVE_MODES.includes(v) ? v : null;
+};
+export const readCohort = (doc, opts) => {
+    const path = opts.fields.parentage.cohort;
+    return path && opts.cohorts ? idOf(getAt(doc, path)) : null;
+};
+/** Paths that hold parent IDs, for queries and indexes. */
+export function parentPaths(opts) {
+    const m = opts.fields.parentage;
+    return m.kind === 'role-fields' ? Object.values(m.roles) : [`${m.path}.parents.${m.individualField}`];
+}
+/** Records that list any of `ids` as a parent. */
+export const childrenWhere = (opts, ids) => ({
+    or: parentPaths(opts).map((p) => ({ [p]: { in: [...ids] } })),
+});
+/** Fields to read for the graph (keeps queries small; never the whole document). */
+export function graphSelect(opts) {
+    const m = opts.fields.parentage;
+    const top = (p) => p.split('.')[0];
+    const keys = new Set([opts.fields.label, ...(opts.fields.sex ? [opts.fields.sex] : []), ...opts.fields.display.map(top)]);
+    if (m.kind === 'role-fields')
+        for (const p of Object.values(m.roles))
+            keys.add(top(p));
+    else
+        keys.add(top(m.path));
+    for (const p of [m.reproductiveMode, m.cohort])
+        if (p)
+            keys.add(top(p));
+    return Object.fromEntries([...keys].map((k) => [k, true]));
+}
+export function documentAdapter(opts) {
+    return {
+        getId: (d) => String(d.id),
+        getParents: (d) => readParents(d, opts),
+        getReproductiveMode: (d) => readMode(d, opts),
+        getCohortId: (d) => readCohort(d, opts),
+        getLabel: (d) => {
+            const v = getAt(d, opts.fields.label);
+            return typeof v === 'string' && v ? v : null;
+        },
+        getSexLabel: (d) => {
+            const v = opts.fields.sex ? getAt(d, opts.fields.sex) : null;
+            return typeof v === 'string' && v ? v : null;
+        },
+        getDisplayData: (d) => Object.fromEntries(opts.fields.display.map((p) => [p, getAt(d, p) ?? null])),
+    };
+}
+export const toIndividual = (doc, opts) => adaptIndividual(doc, documentAdapter(opts));
+/** Maternal (birthing) roles. */
+export const maternalRoles = (opts) => opts.lineageRoles?.maternal ?? ['mother', 'dam', 'egg'];
+/** Parent terms for a request: the user's preference (if configured), else the installation default. */
+export async function termsFor(opts, user) {
+    const { resolveParentTerms } = await import('@captiveorigins/onepedigree-core');
+    const pref = opts.terminology?.userPreference && user ? getAt(user, opts.terminology.userPreference) : undefined;
+    return resolveParentTerms(pref, opts.terminology?.parents ?? 'mother-father');
+}

package/dist/plugin.d.ts

@@ -0,0 +1,10 @@
+import type { Plugin } from 'payload';
+import type { OnePedigreePluginOptions } from './types.js';
+/**
+ * OnePedigree for Payload. Maps (or creates) an individuals collection,
+ * validates parentage on every write, serializes parentage changes, applies
+ * the deletion policy, and adds permission-aware pedigree endpoints and Admin
+ * components. Never creates collections for parents, roles, modes, edges or
+ * occurrences.
+ */
+export declare const onePedigree: (options: OnePedigreePluginOptions) => Plugin;