@wildo-ai/saas-models 1.0.1 → 1.1.0

package/dist/esm/compliance/privacy/subject-export.shared.schemas.js

@@ -0,0 +1,549 @@
+import { getPortabilityProvenance, isBackendOnlyField, isWriteOnlySecretField } from '@wildo-ai/zod-decorators';
+import { RelationshipLifecycleModel, } from '../../resources/resources.shared.schemas.js';
+import { Resources_SharedUtils } from '../../resources/resources.shared.utils.js';
+const compareCanonicalText = (left, right) => (left < right ? -1 : left > right ? 1 : 0);
+/**
+ * WHICH data-subject right an export is answering.
+ *
+ * ## Why this is an enum and not a boolean flag on one bundle
+ *
+ * GDPR Art. 15 (right of access) and Art. 20 (right to data portability) are DIFFERENT rights over
+ * DIFFERENT data, and conflating them is the defect this capability was built to correct: the four
+ * routed export operations removed on 2026-08-01 declared themselves "portability / GDPR" while
+ * their actual options (`includeActivityData`, `includeOrganizationData`) described an *access*
+ * bundle. One output with a flag would reproduce that merge.
+ *
+ * - **Access** is a disclosure obligation: everything the controller holds *concerning* the subject,
+ *   including data the controller itself derived about them, in any readable form.
+ * - **Portability** is a transfer obligation: only the data the subject *provided* — actively, or by
+ *   using the service — and it must be machine-readable and re-importable elsewhere. Data the
+ *   controller inferred is deliberately OUT of scope; a competitor must not receive a rival's
+ *   analytics through a subject's portability request.
+ *
+ * The two therefore diverge at BOTH levels this module classifies: per-edge (see
+ * {@link classifySubjectExportDisposition}) and per-field (see
+ * {@link resolveSubjectExportFieldScope}).
+ *
+ * assurance-control: WILDO.PRIVACY.SUBJECT_DATA_EXPORT
+ */
+export var SubjectExportPurpose;
+(function (SubjectExportPurpose) {
+    /**
+     * Art. 15 — right of access. The broadest bundle: every row concerning the subject, whoever
+     * produced it, including rows the subject does not own (an audit log about them, a membership an
+     * administrator created).
+     */
+    SubjectExportPurpose["ACCESS_ART_15"] = "access_art_15";
+    /**
+     * Art. 20 — right to data portability. Narrower on purpose: only data the subject supplied or
+     * generated by using the service, and only from rows the subject owns. Controller-derived data is
+     * excluded by {@link DataPortabilityProvenance.DERIVED}.
+     */
+    SubjectExportPurpose["PORTABILITY_ART_20"] = "portability_art_20";
+})(SubjectExportPurpose || (SubjectExportPurpose = {}));
+/**
+ * WHERE one field's value came from — the axis that decides Art. 20 scope.
+ *
+ * ## Why three values and not `isSubjectProvided: boolean`
+ *
+ * EDPB/WP29 guidance splits "provided by the data subject" into data supplied *knowingly* and data
+ * *observed* from the subject's use of the service, and puts BOTH in Art. 20 scope while excluding
+ * data the controller *inferred*. A boolean forces `OBSERVED` to be mis-filed against whichever
+ * side the author guesses — and it is the member most often got wrong, because "the user did not
+ * type it" reads as "the user did not provide it", which is precisely the wrong conclusion.
+ *
+ * ## Why this is per-FIELD and not per-resource
+ *
+ * A single row routinely mixes the two: a user profile holds `firstName` (supplied) beside a
+ * controller-computed status or score. A resource-level answer would have to round one way for the
+ * whole row. The resource-level declaration exists only as a DEFAULT
+ * (`portabilityPolicy.defaultProvenance`) so that annotating a resource stays a one-line cost; the
+ * per-field decorator overrides it where a field differs.
+ *
+ * ⚠️ NOT a redaction or scrub concept. This says where a value CAME FROM, for a disclosure
+ * decision. What happens to a value on ERASURE is `.impersonalizeWith()` / `RedactionType`, a
+ * different axis entirely — a field can be `SUBJECT_PROVIDED` and also masked on erasure.
+ */
+export var DataPortabilityProvenance;
+(function (DataPortabilityProvenance) {
+    /**
+     * The subject actively and knowingly supplied this value — form input, an uploaded file, a
+     * setting they chose. Unambiguously in scope for both rights.
+     */
+    DataPortabilityProvenance["SUBJECT_PROVIDED"] = "subject_provided";
+    /**
+     * Generated by the subject's USE of the service rather than typed by them — activity timestamps,
+     * event history, usage counters, telemetry. **In scope for Art. 20**, which is the whole reason
+     * this member exists separately from {@link DERIVED}.
+     */
+    DataPortabilityProvenance["OBSERVED"] = "observed";
+    /**
+     * Produced BY the controller about the subject — inferred classifications, computed scores,
+     * risk or segmentation labels, server-assigned lifecycle state. Disclosed under Art. 15 (the
+     * subject may see what we concluded about them) but **excluded from Art. 20** (a portability
+     * request is not a channel for exporting the controller's own analysis).
+     */
+    DataPortabilityProvenance["DERIVED"] = "derived";
+})(DataPortabilityProvenance || (DataPortabilityProvenance = {}));
+/**
+ * What an export does with ONE child-direction edge of the subject.
+ *
+ * ## Why this is NOT `SubjectErasureDisposition`
+ *
+ * Erasure and export share a traversal and answer opposite questions — *what do I destroy?* versus
+ * *what must I disclose?* — and they diverge on exactly the edges erasure calls `NOT_OWNED`.
+ *
+ * Erasure leaves audit logs, memberships and job executions alone, correctly: you do not delete an
+ * audit log because a user exercised a right. But those same rows hold personal data CONCERNING the
+ * subject, and Art. 15 covers "all personal data concerning him or her" — not "rows he owns".
+ * Reusing erasure's vocabulary verbatim would have silently omitted the data an access request most
+ * often targets. Hence {@link INCLUDED_REFERENCES_SUBJECT}, a case erasure has no use for.
+ *
+ * The two classifiers still read the SAME upstream authority for what an edge *says*
+ * (`requireResolvedRelationshipSemantics`), so they can never disagree about ownership — only about
+ * what to do with it.
+ *
+ * ## Why there is no blocking disposition here
+ *
+ * Erasure refuses up-front on `UNCLASSIFIED` / `UNSUPPORTED_DEFERRED` because it is about to
+ * WRITE, cannot half-destroy a subject, and needs a teardown declaration nobody made. An export
+ * writes nothing: ownership alone answers the edge question, a deferred teardown is irrelevant to a
+ * read, and a cross-adapter dependent is merely a second query rather than a broken transaction.
+ * The one genuine refusal in an export is field-level and Art. 20-only — see
+ * {@link SubjectExportFieldScope.UNDECLARED}. Manufacturing an edge-level blocker for symmetry
+ * would be false symmetry.
+ */
+export var SubjectExportEdgeDisposition;
+(function (SubjectExportEdgeDisposition) {
+    /**
+     * The subject OWNS this dependent (`lifecycleModelMode: DEPENDENT`), so its rows are the
+     * subject's own data. Included for both purposes — for Art. 20 the per-field provenance filter
+     * still applies to what comes back.
+     */
+    SubjectExportEdgeDisposition["INCLUDED_OWNED"] = "included_owned";
+    /**
+     * The subject does NOT own these rows, but they REFERENCE the subject — the far side carries a
+     * foreign key back to them (an audit log, an organization membership, a job execution).
+     *
+     * **Art. 15 only.** These are personal data concerning the subject, so an access request must
+     * disclose them. A portability request must not: the subject did not provide a row that a third
+     * party or the controller created about them, and shipping them would export the controller's
+     * operational records under a transfer right. For `PORTABILITY_ART_20` this same edge classifies
+     * as {@link EXCLUDED_NOT_SUBJECT_PROVIDED}.
+     */
+    SubjectExportEdgeDisposition["INCLUDED_REFERENCES_SUBJECT"] = "included_references_subject";
+    /**
+     * The edge carries no personal data of the subject at all: an independent or link-only
+     * relationship whose far side does not even reference them, or a disabled relationship that is
+     * not part of the live graph. Out of scope for both rights.
+     */
+    SubjectExportEdgeDisposition["EXCLUDED_NOT_SUBJECT_DATA"] = "excluded_not_subject_data";
+    /**
+     * In scope for access, but excluded from THIS export because the export is a portability request
+     * and the rows were not provided by the subject. Kept as its own member rather than collapsing
+     * into {@link EXCLUDED_NOT_SUBJECT_DATA}: a reviewer asking "why is my audit trail missing from
+     * my portability export?" needs "because Art. 20 does not cover controller records" and "because
+     * that edge holds nothing about you" to be different answers, and only the first is a legal
+     * position someone took.
+     */
+    SubjectExportEdgeDisposition["EXCLUDED_NOT_SUBJECT_PROVIDED"] = "excluded_not_subject_provided";
+    /**
+     * The rows ARE the subject's data and the right covers them, but the resource is declared
+     * `systemAccessPolicy.exportSubject = FORBIDDEN` — someone decided it must never reach a data
+     * subject (an authentication-credential store, a security audit trail).
+     *
+     * ## Why this excludes rather than refusing
+     *
+     * An UNDECLARED resource refuses the whole export, because nobody has decided yet and refusing is
+     * what forces the decision. A FORBIDDEN one is the opposite: the decision exists, and refusing
+     * would make it permanent sabotage — a `USERS` access export whose graph touches a credential
+     * store could then NEVER run, no matter how many other resources opted in. Honouring the
+     * declaration means leaving those rows out and saying so.
+     *
+     * ⚠️ This applies to EDGES only. A subject whose OWN resource is FORBIDDEN still refuses: there is
+     * no export of a person whose identity row may not be disclosed, and silently returning an
+     * edges-only bundle would be a disclosure that omits its own subject.
+     */
+    SubjectExportEdgeDisposition["EXCLUDED_NOT_DISCLOSABLE"] = "excluded_not_disclosable";
+})(SubjectExportEdgeDisposition || (SubjectExportEdgeDisposition = {}));
+/** Whether an edge disposition puts the far side's rows INTO the bundle. */
+export function isIncludedSubjectExportEdgeDisposition(disposition) {
+    return disposition === SubjectExportEdgeDisposition.INCLUDED_OWNED
+        || disposition === SubjectExportEdgeDisposition.INCLUDED_REFERENCES_SUBJECT;
+}
+/**
+ * Classify what an export must do with ONE child-direction edge — the disclose-vs-omit decision,
+ * DERIVED FROM CONFIGURATION rather than a hardcoded list of resource types.
+ *
+ * ## Where the answer comes from
+ *
+ * Two declarations the author already makes, read through the same shared authorities the delete
+ * cascade and the erasure orchestrator read, so the three can never disagree about what an edge is:
+ *
+ *  1. **`handling.lifecycleModelMode`** — does the subject own this related resource's lifecycle?
+ *     `DEPENDENT` means the rows are the subject's own data.
+ *  2. **Foreign-key topology** (`resolveForeignKeyHolderResourceType`, cardinality-only and
+ *     therefore pure) — for a NON-owned edge, does the far side nonetheless carry a reference back
+ *     to the subject? If it does, its rows are *about* the subject and Art. 15 must disclose them.
+ *
+ * ## The `purpose` parameter, and why it is a parameter
+ *
+ * Art. 15 and Art. 20 diverge on exactly one edge case — the referencing-but-not-owned edge — and
+ * keeping that divergence in ONE switch here is what stops two near-identical classifiers from
+ * drifting apart. Exposing `classifyForAccess` / `classifyForPortability` would duplicate the
+ * ownership logic, and the day someone fixes a bug in one they would miss the other.
+ *
+ * ## Caller contract
+ *
+ * `relationship.resourceType2` MUST be the far side and `resourceType1` the subject — the same
+ * child-direction normalization {@link classifySubjectErasureDisposition} requires. The caller
+ * filters to child-direction edges before classifying.
+ *
+ * Pure and side-effect free — no registry lookups, no I/O, no row reads — so it is equally usable
+ * from a runtime orchestrator and from a boot-time coherence guard.
+ */
+export function classifySubjectExportDisposition(relationship, purpose) {
+    const relatedResourceType = relationship.resourceType2;
+    const classify = (disposition, reason) => ({ relatedResourceType, disposition, reason });
+    // A disabled relationship is not part of the live graph — the runtime never traverses it, so
+    // there are no rows behind it to disclose.
+    if (relationship.isDisabled === true) {
+        return classify(SubjectExportEdgeDisposition.EXCLUDED_NOT_SUBJECT_DATA, 'the relationship is disabled (isDisabled: true), so it is not part of the live graph');
+    }
+    const semantics = Resources_SharedUtils.requireResolvedRelationshipSemantics(relationship);
+    const lifecycleModel = semantics.handling.lifecycleModelMode;
+    if (lifecycleModel === RelationshipLifecycleModel.DEPENDENT) {
+        return classify(SubjectExportEdgeDisposition.INCLUDED_OWNED, 'lifecycleModelMode is DEPENDENT: the subject owns these rows, so they are the subject\'s '
+            + 'own data and belong in the bundle');
+    }
+    // NOT owned from here on. The rows still count as personal data if they POINT AT the subject —
+    // which is the Art. 15 / Art. 20 fork.
+    const foreignKeyHolder = Resources_SharedUtils.resolveForeignKeyHolderResourceType(relationship);
+    const farSideReferencesSubject = foreignKeyHolder === relationship.resourceType2;
+    if (!farSideReferencesSubject) {
+        return classify(SubjectExportEdgeDisposition.EXCLUDED_NOT_SUBJECT_DATA, `lifecycleModelMode is '${lifecycleModel}' (not DEPENDENT) and the far side does not hold a `
+            + 'foreign key to the subject, so these rows are neither owned by nor about the subject');
+    }
+    switch (purpose) {
+        case SubjectExportPurpose.ACCESS_ART_15:
+            return classify(SubjectExportEdgeDisposition.INCLUDED_REFERENCES_SUBJECT, `lifecycleModelMode is '${lifecycleModel}' (not DEPENDENT), but the far side holds a `
+                + 'foreign key to the subject, so these rows are personal data CONCERNING the subject '
+                + 'and Art. 15 requires disclosing them');
+        case SubjectExportPurpose.PORTABILITY_ART_20:
+            return classify(SubjectExportEdgeDisposition.EXCLUDED_NOT_SUBJECT_PROVIDED, `lifecycleModelMode is '${lifecycleModel}' (not DEPENDENT): these rows reference the `
+                + 'subject but were created by the controller or a third party rather than provided by '
+                + 'the subject, so Art. 20 does not cover them (they ARE disclosed under Art. 15)');
+        default: {
+            // Compile-time exhaustiveness: a new SubjectExportPurpose without an arm here is a TYPE
+            // error, not a silent runtime discovery on someone's disclosure request.
+            const _exhaustivePurposeCheck = purpose;
+            throw new Error(`classifySubjectExportDisposition has no arm for export purpose `
+                + `'${String(_exhaustivePurposeCheck)}'`);
+        }
+    }
+}
+/**
+ * Enumerate every edge touching one export subject, including child-first reference declarations.
+ *
+ * Resource configurations deliberately preserve parent/child/self buckets. Subject disclosure is
+ * different: personal data can point *to* the subject from either authored orientation. This helper
+ * joins both directional buckets, includes self edges once, and swaps only the positional topology
+ * needed by {@link classifySubjectExportDisposition}. It preserves the original compiled edge for
+ * FK resolution and never collapses multiple foreign keys between the same resource pair.
+ */
+export function enumerateSubjectExportRelationshipTraversals(subjectResourceType, relationships, purpose) {
+    const touchingRelationships = [
+        ...relationships.childRelationships,
+        ...relationships.parentRelationships,
+        ...relationships.selfRelationships,
+    ];
+    return touchingRelationships
+        .map((relationship) => {
+        if (relationship.resourceType1 !== subjectResourceType && relationship.resourceType2 !== subjectResourceType) {
+            throw new Error(`Subject-export relationship traversal for ${String(subjectResourceType)} received unrelated edge `
+                + `${String(relationship.resourceType1)} -> ${String(relationship.resourceType2)}.`);
+        }
+        const normalizedRelationship = relationship.resourceType1 === subjectResourceType
+            ? relationship
+            : {
+                ...relationship,
+                resourceType1: relationship.resourceType2,
+                resourceType2: relationship.resourceType1,
+                cardinality1: relationship.cardinality2,
+                cardinality2: relationship.cardinality1,
+            };
+        return {
+            relationship,
+            normalizedRelationship,
+            classification: classifySubjectExportDisposition(normalizedRelationship, purpose),
+        };
+    })
+        .sort((left, right) => compareCanonicalText(subjectExportRelationshipTraversalKey(left), subjectExportRelationshipTraversalKey(right)));
+}
+/** Stable identity retaining distinct foreign keys between otherwise identical resource pairs. */
+export function subjectExportRelationshipTraversalKey(traversal) {
+    const relationship = traversal.normalizedRelationship;
+    return [
+        relationship.resourceType1,
+        relationship.resourceType2,
+        relationship.cardinality1,
+        relationship.cardinality2,
+        relationship.nature,
+        relationship.foreignKeyField ?? '',
+        traversal.classification.disposition,
+    ].join('\0');
+}
+/**
+ * Whether ONE field's value joins the bundle, for a given purpose.
+ *
+ * Separate from {@link SubjectExportEdgeDisposition} because the two answer different questions at
+ * different granularities: an edge decides whether a RESOURCE's rows are in scope at all, a field
+ * scope decides which COLUMNS of an in-scope row survive the Art. 20 narrowing.
+ */
+export var SubjectExportFieldScope;
+(function (SubjectExportFieldScope) {
+    /** The field's value belongs in this bundle. */
+    SubjectExportFieldScope["INCLUDED"] = "included";
+    /**
+     * Excluded because the value is controller-DERIVED and this is a portability request. Never
+     * reached for `ACCESS_ART_15`, which discloses derived data.
+     */
+    SubjectExportFieldScope["EXCLUDED_DERIVED"] = "excluded_derived";
+    /**
+     * ⛔ NO ANSWER — the field carries no provenance declaration and none is inherited from its
+     * resource, while the export is a portability request that needs one.
+     *
+     * The export REFUSES rather than guessing, because both guesses are harmful and neither is the
+     * conservative one: excluding an undeclared field UNDER-DELIVERS a legal right the subject is
+     * owed, and including it OVER-SHARES data the controller derived. There is no safe default to
+     * fall back on, which is exactly the condition that justifies failing loud — the same reasoning
+     * that makes `SubjectErasureDisposition.UNCLASSIFIED` refuse an erasure.
+     *
+     * `ACCESS_ART_15` never produces this: access includes every field regardless of provenance, so
+     * an application can serve access requests before annotating anything.
+     */
+    SubjectExportFieldScope["UNDECLARED"] = "undeclared";
+})(SubjectExportFieldScope || (SubjectExportFieldScope = {}));
+/** Whether a field scope must ABORT the export rather than merely omitting a value. */
+export function isBlockingSubjectExportFieldScope(scope) {
+    return scope === SubjectExportFieldScope.UNDECLARED;
+}
+/**
+ * Decide whether one field's value belongs in the bundle.
+ *
+ * `provenance` is the field's EFFECTIVE provenance — its own `.portabilityProvenance()` declaration
+ * if it carries one, otherwise the resource's `portabilityPolicy.defaultProvenance`, otherwise
+ * `undefined`. Resolving that fallback chain is the factory's job (Phase 0B); this function only
+ * judges the resolved value, which keeps it pure and independently testable.
+ */
+export function resolveSubjectExportFieldScope(provenance, purpose) {
+    switch (purpose) {
+        // Access discloses everything concerning the subject, so provenance is simply not a question it
+        // asks — an unannotated application can still answer an Art. 15 request in full.
+        case SubjectExportPurpose.ACCESS_ART_15:
+            return SubjectExportFieldScope.INCLUDED;
+        case SubjectExportPurpose.PORTABILITY_ART_20:
+            return resolvePortabilityFieldScope(provenance);
+        default: {
+            // Compile-time exhaustiveness on the PURPOSE axis too. Without this arm a third right added
+            // to the enum would silently inherit the portability narrowing — a disclosure boundary
+            // decided by fall-through rather than by anyone.
+            const _exhaustivePurposeCheck = purpose;
+            throw new Error(`resolveSubjectExportFieldScope has no arm for export purpose `
+                + `'${String(_exhaustivePurposeCheck)}'`);
+        }
+    }
+}
+/**
+ * The Art. 20 narrowing, split out so {@link resolveSubjectExportFieldScope} can switch
+ * exhaustively on `purpose` while this switches exhaustively on `provenance`. Module-private: the
+ * purpose gate is not optional, and a caller reaching this directly would bypass it.
+ */
+function resolvePortabilityFieldScope(provenance) {
+    if (provenance === undefined) {
+        return SubjectExportFieldScope.UNDECLARED;
+    }
+    switch (provenance) {
+        // Both are "provided by the data subject" in the Art. 20 sense — OBSERVED is data generated by
+        // the subject's USE of the service, which the guidance places in scope even though the subject
+        // never typed it.
+        case DataPortabilityProvenance.SUBJECT_PROVIDED:
+        case DataPortabilityProvenance.OBSERVED:
+            return SubjectExportFieldScope.INCLUDED;
+        case DataPortabilityProvenance.DERIVED:
+            return SubjectExportFieldScope.EXCLUDED_DERIVED;
+        default: {
+            // Compile-time exhaustiveness: a new provenance member without an arm is a TYPE error here.
+            const _exhaustiveProvenanceCheck = provenance;
+            throw new Error(`resolvePortabilityFieldScope has no arm for provenance `
+                + `'${String(_exhaustiveProvenanceCheck)}'`);
+        }
+    }
+}
+/**
+ * Is this field withheld from EVERY subject export, whatever right is being answered?
+ *
+ * ## Why this exists at all — the layering trap it closes
+ *
+ * The export orchestrator collects rows at the REPOSITORY layer, which sits BELOW the service-layer
+ * DTO projection that normally strips `.isBackendOnly()` fields on their way to a client. Without an
+ * explicit check here, a subject export would disclose exactly the values that projection exists to
+ * hide — `passwordHash` and `backupCodesHashed` on `USER_CREDENTIALS` are the motivating case, and
+ * the config change that exposed them would have looked entirely routine.
+ *
+ * ## Why it is deliberately CONSERVATIVE
+ *
+ * This withholds every backend-only field, not only the secrets. Some backend-only fields are
+ * genuinely disclosable under Art. 15 (`passwordChangedAt`, `firstMfaPromptAt` — facts about the
+ * subject they may ask for), so this errs toward withholding.
+ *
+ * That asymmetry is intentional. Under-disclosing produces a complaint that is answerable and
+ * fixable; disclosing an authentication secret is neither, and it degrades the security of
+ * processing the framework is separately obliged to maintain (GDPR Art. 32). Between an
+ * over-cautious bundle and a leaked credential, only one is recoverable.
+ *
+ * The withheld fields are REPORTED (`SubjectExportReport.fieldsWithheldAsNonDisclosable`) so the
+ * caution is visible rather than silent. When a resource needs a specific backend-only field
+ * disclosed, the expressible extension is a per-field opt-in on this predicate — NOT loosening it
+ * wholesale.
+ *
+ * assurance-control: WILDO.PRIVACY.SUBJECT_DATA_EXPORT
+ */
+export function isFieldWithheldFromSubjectExport(fieldSchema) {
+    // `isWriteOnlySecret` is checked explicitly rather than assumed to imply backend-only: they are
+    // separate decorators, and a future authoring form that sets one without the other must not
+    // silently open a disclosure path.
+    return isBackendOnlyField(fieldSchema) || isWriteOnlySecretField(fieldSchema);
+}
+/** Every legal {@link DataPortabilityProvenance} value, for validating an opaque decorator string. */
+const KNOWN_PORTABILITY_PROVENANCES = new Set(Object.values(DataPortabilityProvenance));
+/**
+ * Resolve ONE field's EFFECTIVE provenance by joining the two declaration levels.
+ *
+ * ## The fallback chain, and why it has exactly two rungs
+ *
+ * 1. the field's own `.portabilityProvenance()` declaration, if it carries one;
+ * 2. otherwise the resource's `portabilityPolicy.defaultProvenance`;
+ * 3. otherwise `undefined` — which {@link resolveSubjectExportFieldScope} turns into a REFUSAL for
+ *    an Art. 20 export and ignores entirely for Art. 15.
+ *
+ * Two rungs is what makes the fail-loud rule adoptable: without the resource default, every field of
+ * every resource would need a decorator before a single portability request could be answered, and a
+ * capability that expensive to adopt does not get adopted. With it, annotating a resource is one
+ * line and only the exceptions carry a decorator.
+ *
+ * ## Why the enum check lives HERE
+ *
+ * `zod-decorators` sits below this package and cannot import {@link DataPortabilityProvenance}, so
+ * it stores whatever non-empty string it was given — it can reject a BLANK but not a WRONG value.
+ * This is the first layer that knows the vocabulary, so it is where a typo'd `'subject-provided'`
+ * (hyphen, not underscore) must fail rather than silently resolving to `undefined` and turning a
+ * declared field into a refusal — or worse, into a silent omission if the caller treats unknown as
+ * derived. Mirrors how `RedactionType` validity is checked in this layer for `.impersonalizeWith()`.
+ *
+ * @param fieldSchema the field's Zod schema; the reader walks wrapper types, so a declaration made
+ *   before or after `.optional()` / `.nullish()` / `.default()` is observed either way.
+ * @param resourceDefaultProvenance the owning resource's `portabilityPolicy.defaultProvenance`.
+ *   Taken as a bare value rather than the policy object so this module stays free of the
+ *   resource-config import (which imports THIS module for the enum).
+ * @param fieldLocator `resourceType.fieldName`, used only to make a rejection actionable.
+ */
+export function resolveEffectiveFieldPortabilityProvenance(fieldSchema, resourceDefaultProvenance, fieldLocator) {
+    const declared = getPortabilityProvenance(fieldSchema);
+    if (declared === undefined) {
+        return resourceDefaultProvenance;
+    }
+    if (!KNOWN_PORTABILITY_PROVENANCES.has(declared)) {
+        throw new Error(`[${fieldLocator}] portabilityProvenance('${declared}') is not a DataPortabilityProvenance `
+            + `value. Expected one of: ${[...KNOWN_PORTABILITY_PROVENANCES].join(', ')}. An unrecognised `
+            + `value would resolve as UNDECLARED and make an Art. 20 export refuse, hiding the typo `
+            + `behind what looks like a deliberate omission.`);
+    }
+    return declared;
+}
+/** Why a compiled leaf-field decision has its effective export meaning. */
+export var SubjectExportFieldDecisionBasis;
+(function (SubjectExportFieldDecisionBasis) {
+    SubjectExportFieldDecisionBasis["FIELD_DECLARATION"] = "field_declaration";
+    SubjectExportFieldDecisionBasis["RESOURCE_DEFAULT"] = "resource_default";
+    SubjectExportFieldDecisionBasis["WITHHELD_NON_DISCLOSABLE"] = "withheld_non_disclosable";
+    SubjectExportFieldDecisionBasis["UNDECLARED"] = "undeclared";
+    SubjectExportFieldDecisionBasis["DEPTH_LIMIT"] = "depth_limit";
+})(SubjectExportFieldDecisionBasis || (SubjectExportFieldDecisionBasis = {}));
+const SUBJECT_EXPORT_FIELD_MAX_DEPTH = 10;
+/**
+ * Resolve an object shape through the same bounded wrapper protocol used by subject export.
+ * Returning `undefined` means the value is a leaf. Reaching the bound is handled fail-closed by
+ * {@link compileSubjectExportFieldDecisions}, never as an implicit leaf inclusion.
+ */
+export function resolveSubjectExportObjectShapeThroughWrappers(schema) {
+    let current = schema;
+    for (let unwrapDepth = 0; current && unwrapDepth < SUBJECT_EXPORT_FIELD_MAX_DEPTH; unwrapDepth += 1) {
+        if (current.shape && typeof current.shape === 'object')
+            return current.shape;
+        const inner = current.def?.innerType ?? current._def?.innerType;
+        if (!inner)
+            return undefined;
+        current = inner;
+    }
+    return undefined;
+}
+/**
+ * Compile every runtime-effective leaf-field decision for one resource and right.
+ *
+ * Both the backend executor and application authority proof consume this function. A field-level
+ * decorator, inherited default, withheld marker, wrapper layout or depth refusal therefore changes
+ * one shared decision inventory instead of two independently maintained interpretations.
+ */
+export function compileSubjectExportFieldDecisions(input) {
+    const rootShape = resolveSubjectExportObjectShapeThroughWrappers(input.mainSchema);
+    if (!rootShape)
+        return [];
+    const decisions = [];
+    const visit = (shape, locatorPrefix, depth) => {
+        for (const [fieldName, fieldSchema] of Object.entries(shape)) {
+            const locator = `${locatorPrefix}.${fieldName}`;
+            if (depth >= SUBJECT_EXPORT_FIELD_MAX_DEPTH) {
+                decisions.push({
+                    locator,
+                    purpose: input.purpose,
+                    scope: SubjectExportFieldScope.UNDECLARED,
+                    provenance: null,
+                    basis: SubjectExportFieldDecisionBasis.DEPTH_LIMIT,
+                });
+                continue;
+            }
+            if (isFieldWithheldFromSubjectExport(fieldSchema)) {
+                decisions.push({
+                    locator,
+                    purpose: input.purpose,
+                    scope: null,
+                    provenance: null,
+                    basis: SubjectExportFieldDecisionBasis.WITHHELD_NON_DISCLOSABLE,
+                });
+                continue;
+            }
+            const nestedShape = resolveSubjectExportObjectShapeThroughWrappers(fieldSchema);
+            if (nestedShape) {
+                visit(nestedShape, locator, depth + 1);
+                continue;
+            }
+            const declared = getPortabilityProvenance(fieldSchema);
+            const provenance = resolveEffectiveFieldPortabilityProvenance(fieldSchema, input.defaultProvenance, locator);
+            decisions.push({
+                locator,
+                purpose: input.purpose,
+                scope: resolveSubjectExportFieldScope(provenance, input.purpose),
+                provenance: provenance ?? null,
+                basis: declared !== undefined
+                    ? SubjectExportFieldDecisionBasis.FIELD_DECLARATION
+                    : provenance !== undefined
+                        ? SubjectExportFieldDecisionBasis.RESOURCE_DEFAULT
+                        : SubjectExportFieldDecisionBasis.UNDECLARED,
+            });
+        }
+    };
+    visit(rootShape, String(input.resourceType), 0);
+    return decisions.sort((left, right) => compareCanonicalText(left.locator, right.locator));
+}
+//# sourceMappingURL=subject-export.shared.schemas.js.map