@memberjunction/core-actions 6.2.0-edge.2 → 6.2.0-edge.3

package/dist/custom/interactive-forms/_shared.d.ts

@@ -1,13 +1,14 @@
 /**
- * Shared helpers for the Interactive Forms action family. These all touch
- * the same two entities (`MJ: Components`, `MJ: Entity Form Overrides`),
- * lint the same spec shape, and need the same parameter conventions —
- * extracting here keeps each action thin.
+ * Shared helpers for the Interactive Forms action family. These touch the
+ * same entities (`MJ: Components`, `MJ: Entity Form Overrides`,
+ * `MJ: Entity Form Contributions`), lint the same spec shape, and need the
+ * same parameter conventions — extracting here keeps each action thin.
  */
 import { ActionResultSimple, RunActionParams } from "@memberjunction/actions-base";
-import { IMetadataProvider, UserInfo } from "@memberjunction/core";
-import { MJComponentEntity, MJEntityFormOverrideEntity } from "@memberjunction/core-entities";
+import { IMetadataProvider, RunInEntityTransaction, UserInfo } from "@memberjunction/core";
+import { type ContributionRowOptions, type FormScope, MJComponentEntity, MJEntityFormContributionEntity, MJEntityFormOverrideEntity } from "@memberjunction/core-entities";
 import type { ComponentSpec } from "@memberjunction/interactive-component-types";
+import { type NormalizedFormContributionSpec } from "@memberjunction/interactive-component-types/forms";
 export declare function GetParam(params: RunActionParams, name: string): unknown;
 /** @deprecated Use {@link GetParam}. */
 export declare function getParam(params: RunActionParams, name: string): unknown;
@@ -15,6 +16,8 @@ export declare function GetStringParam(params: RunActionParams, name: string): s
 /** @deprecated Use {@link GetStringParam}. */
 export declare function getStringParam(params: RunActionParams, name: string): string | null;
 export declare function GetNumberParam(params: RunActionParams, name: string): number | null;
+/** The `Precedence` input as a whole number of zero or more, or null when absent or not one. */
+export declare function GetPrecedenceParam(params: RunActionParams): number | null;
 /** @deprecated Use {@link GetNumberParam}. */
 export declare function getNumberParam(params: RunActionParams, name: string): number | null;
 export declare function AddOutput(params: RunActionParams, name: string, value: unknown): void;
@@ -34,14 +37,10 @@ export declare function ParseSpecParam(raw: unknown): ComponentSpec | {
 export declare function parseSpecParam(raw: unknown): ComponentSpec | {
     error: string;
 };
-/**
- * Lint a form-role ComponentSpec. Returns null on success, a fail-fast
- * ActionResultSimple on failure. Two rules are suppressed for form-role
- * specs (component-props-validation, callback-event-validation) — see
- * lint comments in the original create-interactive-form action for the
- * rationale.
- */
+/** Lint a whole-form spec — `componentRole: 'form'`. */
 export declare function LintFormSpec(spec: ComponentSpec, contextUser: UserInfo): Promise<ActionResultSimple | null>;
+/** Lint a form-panel spec — `componentRole: 'form-panel'`. Same rules as {@link LintFormSpec}. */
+export declare function LintFormPanelSpec(spec: ComponentSpec, contextUser: UserInfo): Promise<ActionResultSimple | null>;
 /** @deprecated Use {@link LintFormSpec}. */
 export declare function lintFormSpec(spec: ComponentSpec, contextUser: UserInfo): Promise<ActionResultSimple | null>;
 /** Load a Component entity object by primary key. */
@@ -52,26 +51,57 @@ export declare function loadComponent(provider: IMetadataProvider, user: UserInf
 export declare function LoadOverride(provider: IMetadataProvider, user: UserInfo, overrideID: string): Promise<MJEntityFormOverrideEntity | null>;
 /** @deprecated Use {@link LoadOverride}. */
 export declare function loadOverride(provider: IMetadataProvider, user: UserInfo, overrideID: string): Promise<MJEntityFormOverrideEntity | null>;
+/** Load a Contribution entity object by primary key. */
+export declare function LoadContribution(provider: IMetadataProvider, user: UserInfo, contributionID: string): Promise<MJEntityFormContributionEntity | null>;
 /**
- * Defense-in-depth ownership check for the override-mutation actions
- * (Modify / Activate / Revert).
+ * Filter for the `MJ: Entity Form Contributions` rows a caller may see: their own
+ * User-scope rows, their roles' rows, and Global rows.
  *
- * `Create` is naturally self-scoped — it always emits a fresh User-scope
- * row owned by the caller. The mutation actions, however, take an
- * `OverrideID` from the caller and operate on it; without this guard a
- * user could mutate another user's User-scope override by guessing the ID.
- * Row-level security may catch some of this, but we don't rely on it.
+ * Shared so every reader applies the same visibility. Two readers that disagree would
+ * show a contribution in one place and hide it in another, and the apply flow's
+ * duplicate check would miss a row the form is already rendering.
+ */
+export declare function ContributionScopeFilter(entityID: string, user: NonNullable<RunActionParams['ContextUser']>): string;
+/**
+ * Whether metadata contributions are on for a server answer.
  *
- * Rules:
- *   - `Scope='User'`   → caller must be the owning user.
- *   - `Scope='Role'`   → caller must be a member of the override's role.
- *   - `Scope='Global'` → caller must be a system admin (`UserInfo.Type==='Owner'`).
+ * Off when the Node switch is off (`MJ_FORMS_METADATA_CONTRIBUTIONS=false`, read into
+ * `InteractiveFormsEngine.MetadataContributionsEnabled`), or when the instance configuration
+ * Explorer reads (`Forms.MetadataContributions.Enabled`) is `false`. The instance configuration
+ * comes from the cached `InstanceConfigEngine`, which is refreshed after a save in the same
+ * process or by cross-server cache invalidation, so setting it back to `true` turns the answer
+ * back on once the cache has the new value. When Instance Config cannot load, only the Node
+ * switch counts.
+ */
+export declare function MetadataContributionsOn(provider: IMetadataProvider, user: UserInfo): Promise<boolean>;
+/** What {@link CheckPersonalWrite} reads from a form override or contribution row. */
+export interface ScopedFormRow {
+    ID: string;
+    Scope: FormScope;
+    UserID: string | null;
+}
+/**
+ * Why an action may not change this form or panel, as a `FORBIDDEN` result, or null.
  *
- * Returns `null` on success; a `FORBIDDEN` failure result on rejection.
+ * Actions change the caller's own personal forms and panels only. A row whose Scope is not
+ * `User` is refused for every caller, a Manage Form Defaults holder included: shared forms and
+ * panels are managed by people, from Form Builder or the form's Manage drawer. A `User` row is
+ * then checked with `FormScopeWriteRefusal`, the rule the server entity applies on save, which
+ * refuses a row that belongs to someone else.
  */
-export declare function CheckOverrideOwnership(override: Pick<MJEntityFormOverrideEntity, 'ID' | 'Scope' | 'UserID' | 'RoleID'>, user: UserInfo): ActionResultSimple | null;
-/** @deprecated Use {@link CheckOverrideOwnership}. */
-export declare function checkOverrideOwnership(override: Pick<MJEntityFormOverrideEntity, 'ID' | 'Scope' | 'UserID' | 'RoleID'>, user: UserInfo): ActionResultSimple | null;
+export declare function CheckPersonalWrite(row: ScopedFormRow, user: UserInfo): ActionResultSimple | null;
+/** The provider shape `RunInEntityTransaction` reads. */
+export type TransactableProvider = Parameters<typeof RunInEntityTransaction>[0];
+/**
+ * Runs `work` in one entity transaction. When `work` returns an `{ error }` result, every write
+ * it made is rolled back and that result is returned; anything `work` throws also rolls back and
+ * is rethrown. A provider without entity transactions runs `work` without one.
+ */
+export declare function WriteAtomically<T extends object>(provider: IMetadataProvider, work: () => Promise<T | {
+    error: ActionResultSimple;
+}>): Promise<T | {
+    error: ActionResultSimple;
+}>;
 /**
  * Lifecycle mapping. EntityFormOverride.Status uses
  * 'Active' / 'Pending' / 'Inactive' (it's the resolver-facing union). The
@@ -108,6 +138,8 @@ export declare function InsertComponent(opts: {
     version: string;
     versionSequence: number;
     componentStatus: FormLifecycle;
+    /** 'Form' for whole forms (default), 'Widget' for form panels. */
+    componentType?: 'Form' | 'Widget';
 }): Promise<{
     id: string;
 } | {
@@ -123,15 +155,17 @@ export declare function insertComponent(opts: {
     version: string;
     versionSequence: number;
     componentStatus: FormLifecycle;
+    /** 'Form' for whole forms (default), 'Widget' for form panels. */
+    componentType?: 'Form' | 'Widget';
 }): Promise<{
     id: string;
 } | {
     error: ActionResultSimple;
 }>;
 /**
- * Insert a new EntityFormOverride row. Always User-scoped (security clamp)
- * unless `allowGlobalOrRole` is explicitly true — which is reserved for the
- * future "promote variant" UI path, not the agent.
+ * Insert a new EntityFormOverride row, always User-scoped to the caller. Actions
+ * write personal forms only; sharing a form with a role or everyone is done from
+ * Form Builder or the form's Manage drawer.
  */
 export declare function InsertOverride(opts: {
     provider: IMetadataProvider;
@@ -210,4 +244,52 @@ export declare function bumpVersion(current: string | null | undefined, kind: Ve
 export declare function ParseVersionBumpKind(raw: unknown): VersionBumpKind | null;
 /** @deprecated Use {@link ParseVersionBumpKind}. */
 export declare function parseVersionBumpKind(raw: unknown): VersionBumpKind | null;
+/**
+ * A form-panel spec's registration intent, with its related entity resolved and the key its
+ * row will carry derived and checked.
+ */
+export interface ContributionRegistration {
+    Contribution: NormalizedFormContributionSpec;
+    /** What {@link ApplyContributionSpecToRow} needs beyond the spec. */
+    RowOptions: ContributionRowOptions;
+    /** The key the row will carry, or null when nothing supplies one. */
+    WriteKey: string | null;
+}
+/**
+ * Reads the `formContribution` block of a linted form-panel spec, resolves the related entity it
+ * claims to its registered name and ID, and derives the row's key with
+ * `ResolveContributionWriteKey`, seeding a panel key from `spec.name`.
+ *
+ * Fails with `LINT_FAILED` when the block cannot be read, `RELATED_ENTITY_NOT_FOUND` when the
+ * related entity is not registered, `INVALID_CLAIM` when the row the spec maps to breaks a claim
+ * rule the database enforces (`ContributionClaimRefusal`), and `INVALID_CONTRIBUTION_KEY` when the
+ * key does not match `CONTRIBUTION_KEY_PATTERN`. Callers run it before any write.
+ *
+ * @param currentKey The key of the row being modified; omit for a new row. When the spec names
+ * no key and claims no grid, a panel key here is kept, so renaming the component does not change
+ * the contribution's identity.
+ */
+export declare function ResolveContributionRegistration(provider: IMetadataProvider, spec: ComponentSpec, currentKey?: string | null): ContributionRegistration | {
+    error: ActionResultSimple;
+};
+/**
+ * Insert a new EntityFormContribution row. Always User-scoped — promotion to Role or
+ * Global is a deliberate human act, not something an agent write path can reach.
+ */
+export declare function InsertContribution(opts: {
+    provider: IMetadataProvider;
+    user: UserInfo;
+    entityID: string;
+    componentID: string;
+    name: string;
+    description: string | null;
+    notes?: string | null;
+    registration: ContributionRegistration;
+    status: 'Active' | 'Pending';
+    precedence: number;
+}): Promise<{
+    id: string;
+} | {
+    error: ActionResultSimple;
+}>;
 //# sourceMappingURL=_shared.d.ts.map

package/dist/custom/interactive-forms/_shared.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"_shared.d.ts","sourceRoot":"","sources":["../../../src/custom/interactive-forms/_shared.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"_shared.d.ts","sourceRoot":"","sources":["../../../src/custom/interactive-forms/_shared.ts"],"names":[],"mappings":"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"}

package/dist/custom/interactive-forms/_shared.js

@@ -1,5 +1,7 @@
-import { UUIDsEqual } from "@memberjunction/global";
-import { isFormRole } from "@memberjunction/interactive-component-types/forms";
+import { LogError, RunInEntityTransaction } from "@memberjunction/core";
+import { EscapeSQLString } from "@memberjunction/global";
+import { ApplyContributionSpecToRow, ContributionClaimRefusal, ContributionSpecColumns, FormLifecycleComponentStatus, FormScopeWriteRefusal, InstanceConfigEngine, InteractiveFormsEngine, } from "@memberjunction/core-entities";
+import { CONTRIBUTION_KEY_PATTERN, GetDeclaredFormContribution, IsFormPanelRole, isFormRole, IsPanelContributionKey, ResolveContributionWriteKey, } from "@memberjunction/interactive-component-types/forms";
 import { ComponentLinter } from "@memberjunction/react-linter";
 // ── parameter helpers ────────────────────────────────────────────────────
 export function GetParam(params, name) {
@@ -28,6 +30,11 @@ export function GetNumberParam(params, name) {
     const n = typeof v === 'number' ? v : Number(String(v));
     return Number.isFinite(n) ? n : null;
 }
+/** The `Precedence` input as a whole number of zero or more, or null when absent or not one. */
+export function GetPrecedenceParam(params) {
+    const precedence = GetNumberParam(params, "Precedence");
+    return precedence != null && precedence >= 0 ? Math.floor(precedence) : null;
+}
 /** @deprecated Use {@link GetNumberParam}. */
 export function getNumberParam(params, name) {
     return GetNumberParam(params, name);
@@ -72,15 +79,24 @@ export function parseSpecParam(raw) {
     return ParseSpecParam(raw);
 }
 /**
- * Lint a form-role ComponentSpec. Returns null on success, a fail-fast
- * ActionResultSimple on failure. Two rules are suppressed for form-role
- * specs (component-props-validation, callback-event-validation) — see
- * lint comments in the original create-interactive-form action for the
- * rationale.
+ * Rules suppressed for both form roles. The form host (mj-react-component) creates
+ * `callbacks` / `utilities` / `components` / `styles` once per instance (stable refs),
+ * so depending on them in useEffect does not loop here; the prop and callback shape
+ * rules only know the generic component surface, not the host-provided one.
  */
-export async function LintFormSpec(spec, contextUser) {
-    if (!isFormRole(spec)) {
-        return Failure("LINT_FAILED", `Spec must declare componentRole='form'. Got '${spec.componentRole ?? "(unset)"}'. The InteractiveForm runtime refuses to mount any other role.`);
+const ROLE_SUPPRESSED_RULES = new Set([
+    "component-props-validation",
+    "callback-event-validation",
+    "useeffect-unstable-dependencies",
+]);
+/**
+ * Lint body shared by both roles. `roleCheck` decides which role the spec must
+ * declare; `roleLabel` names it in the failure message. Returns null on success,
+ * a fail-fast ActionResultSimple on failure.
+ */
+async function lintRoleSpec(spec, contextUser, roleCheck, roleLabel) {
+    if (!roleCheck(spec)) {
+        return Failure("LINT_FAILED", `Spec must declare componentRole='${roleLabel}'. Got '${spec.componentRole ?? "(unset)"}'. The InteractiveForm runtime refuses to mount any other role.`);
     }
     if (!spec.name || spec.name.trim().length === 0) {
         return Failure("LINT_FAILED", "Spec.name is required.");
@@ -91,22 +107,13 @@ export async function LintFormSpec(spec, contextUser) {
     if (!spec.location) {
         return Failure("LINT_FAILED", "Spec.location is required (use 'embedded' for inline JSX or 'registry' to reference a published component).");
     }
-    const FORM_ROLE_SUPPRESSED_RULES = new Set([
-        "component-props-validation",
-        "callback-event-validation",
-        // The form host (mj-react-component) creates `callbacks`/`utilities`/`components`/
-        // `styles` once per instance (stable refs), so depending on them in useEffect does
-        // not loop here. This rule only flags those host-provided prop names, making it a
-        // false positive on the form-role surface.
-        "useeffect-unstable-dependencies",
-    ]);
     try {
         const result = await ComponentLinter.lintComponent(spec.code, spec.name, spec, true, contextUser);
         const blocking = (result.violations ?? []).filter(v => {
             const isBlocking = v.severity === "critical" || v.severity === "high";
             if (!isBlocking)
                 return false;
-            if (v.rule && FORM_ROLE_SUPPRESSED_RULES.has(v.rule))
+            if (v.rule && ROLE_SUPPRESSED_RULES.has(v.rule))
                 return false;
             return true;
         });
@@ -123,6 +130,14 @@ export async function LintFormSpec(spec, contextUser) {
     }
     return null;
 }
+/** Lint a whole-form spec — `componentRole: 'form'`. */
+export async function LintFormSpec(spec, contextUser) {
+    return lintRoleSpec(spec, contextUser, isFormRole, 'form');
+}
+/** Lint a form-panel spec — `componentRole: 'form-panel'`. Same rules as {@link LintFormSpec}. */
+export async function LintFormPanelSpec(spec, contextUser) {
+    return lintRoleSpec(spec, contextUser, IsFormPanelRole, 'form-panel');
+}
 /** @deprecated Use {@link LintFormSpec}. */
 export async function lintFormSpec(spec, contextUser) {
     return LintFormSpec(spec, contextUser);
@@ -148,65 +163,105 @@ export async function LoadOverride(provider, user, overrideID) {
 export async function loadOverride(provider, user, overrideID) {
     return LoadOverride(provider, user, overrideID);
 }
+/** Load a Contribution entity object by primary key. */
+export async function LoadContribution(provider, user, contributionID) {
+    const c = await provider.GetEntityObject("MJ: Entity Form Contributions", user);
+    const loaded = await c.Load(contributionID);
+    return loaded ? c : null;
+}
 /**
- * Defense-in-depth ownership check for the override-mutation actions
- * (Modify / Activate / Revert).
+ * Filter for the `MJ: Entity Form Contributions` rows a caller may see: their own
+ * User-scope rows, their roles' rows, and Global rows.
  *
- * `Create` is naturally self-scoped — it always emits a fresh User-scope
- * row owned by the caller. The mutation actions, however, take an
- * `OverrideID` from the caller and operate on it; without this guard a
- * user could mutate another user's User-scope override by guessing the ID.
- * Row-level security may catch some of this, but we don't rely on it.
+ * Shared so every reader applies the same visibility. Two readers that disagree would
+ * show a contribution in one place and hide it in another, and the apply flow's
+ * duplicate check would miss a row the form is already rendering.
+ */
+export function ContributionScopeFilter(entityID, user) {
+    const roleIDs = (user.UserRoles ?? [])
+        .map(r => r.RoleID).filter((x) => !!x);
+    const roleClause = roleIDs.length > 0
+        ? `(Scope='Role' AND RoleID IN (${roleIDs.map(id => `'${EscapeSQLString(id)}'`).join(',')}))`
+        : `(1=0)`;
+    return `EntityID='${EscapeSQLString(entityID)}' AND ((Scope='User' AND UserID='${EscapeSQLString(user.ID)}') OR ${roleClause} OR Scope='Global')`;
+}
+/**
+ * Whether metadata contributions are on for a server answer.
  *
- * Rules:
- *   - `Scope='User'`   → caller must be the owning user.
- *   - `Scope='Role'`   → caller must be a member of the override's role.
- *   - `Scope='Global'` → caller must be a system admin (`UserInfo.Type==='Owner'`).
+ * Off when the Node switch is off (`MJ_FORMS_METADATA_CONTRIBUTIONS=false`, read into
+ * `InteractiveFormsEngine.MetadataContributionsEnabled`), or when the instance configuration
+ * Explorer reads (`Forms.MetadataContributions.Enabled`) is `false`. The instance configuration
+ * comes from the cached `InstanceConfigEngine`, which is refreshed after a save in the same
+ * process or by cross-server cache invalidation, so setting it back to `true` turns the answer
+ * back on once the cache has the new value. When Instance Config cannot load, only the Node
+ * switch counts.
+ */
+export async function MetadataContributionsOn(provider, user) {
+    if (!InteractiveFormsEngine.MetadataContributionsEnabled)
+        return false;
+    try {
+        const config = InstanceConfigEngine.Instance;
+        await config.Config(false, user, provider);
+        return config.GetBoolean(InteractiveFormsEngine.MetadataContributionsConfigKey, true);
+    }
+    catch (err) {
+        LogError(`Instance Config did not load, so form contributions stay on: ${err instanceof Error ? err.message : String(err)}`);
+        return true;
+    }
+}
+/**
+ * Why an action may not change this form or panel, as a `FORBIDDEN` result, or null.
  *
- * Returns `null` on success; a `FORBIDDEN` failure result on rejection.
+ * Actions change the caller's own personal forms and panels only. A row whose Scope is not
+ * `User` is refused for every caller, a Manage Form Defaults holder included: shared forms and
+ * panels are managed by people, from Form Builder or the form's Manage drawer. A `User` row is
+ * then checked with `FormScopeWriteRefusal`, the rule the server entity applies on save, which
+ * refuses a row that belongs to someone else.
  */
-export function CheckOverrideOwnership(override, user) {
-    const ID = override.ID;
-    switch (override.Scope) {
-        case 'User': {
-            if (!UUIDsEqual(override.UserID, user.ID)) {
-                return Failure("FORBIDDEN", `Override ${ID} is User-scoped to a different user. Only the owning user can mutate it.`);
-            }
-            return null;
-        }
-        case 'Role': {
-            const userRoleIds = (user.UserRoles ?? [])
-                .map(r => r.RoleID).filter((x) => !!x);
-            if (!override.RoleID || !userRoleIds.includes(override.RoleID)) {
-                return Failure("FORBIDDEN", `Override ${ID} is Role-scoped (${override.RoleID}). Only members of that role can mutate it.`);
-            }
-            return null;
-        }
-        case 'Global': {
-            // `UserInfo.Type === 'Owner'` is MJ's canonical admin marker —
-            // see packages/MJCore/src/userInfo.ts (Type is a Pick from the
-            // generated entity field). Owners can manage Global overrides;
-            // everyone else is rejected.
-            const isOwner = (user.Type ?? '').toLowerCase() === 'owner';
-            if (!isOwner) {
-                return Failure("FORBIDDEN", `Override ${ID} is Global. Only Owner-type users can mutate Global overrides; promote / demote them via Component Studio with appropriate privileges.`);
-            }
-            return null;
-        }
-        default:
-            return Failure("FORBIDDEN", `Override ${ID} has an unrecognized Scope ('${override.Scope}').`);
+export function CheckPersonalWrite(row, user) {
+    if (row.Scope !== 'User') {
+        return Failure("FORBIDDEN", `${row.ID} is shared (Scope '${row.Scope}'). Actions change only your own personal forms and panels; ` +
+            `shared ones are managed from Form Builder or the form's Manage drawer.`);
+    }
+    const refusal = FormScopeWriteRefusal({
+        Operation: 'update',
+        PriorScope: row.Scope, PriorUserID: row.UserID,
+        NextScope: row.Scope, NextUserID: row.UserID,
+        CallerID: user.ID,
+        // A User row needs no grant, so only the ownership half of the rule can refuse it.
+        CallerHoldsGrant: false,
+    });
+    return refusal ? Failure("FORBIDDEN", refusal) : null;
+}
+/** Carries a failed write step out of the transaction, so the transaction rolls back. */
+class RolledBackWrite extends Error {
+    constructor(Outcome) {
+        super(Outcome.error.Message);
+        this.Outcome = Outcome;
     }
 }
-/** @deprecated Use {@link CheckOverrideOwnership}. */
-export function checkOverrideOwnership(override, user) {
-    return CheckOverrideOwnership(override, user);
+/**
+ * Runs `work` in one entity transaction. When `work` returns an `{ error }` result, every write
+ * it made is rolled back and that result is returned; anything `work` throws also rolls back and
+ * is rethrown. A provider without entity transactions runs `work` without one.
+ */
+export async function WriteAtomically(provider, work) {
+    try {
+        return await RunInEntityTransaction(provider, async () => {
+            const outcome = await work();
+            if ('error' in outcome)
+                throw new RolledBackWrite(outcome);
+            return outcome;
+        });
+    }
+    catch (err) {
+        if (err instanceof RolledBackWrite)
+            return err.Outcome;
+        throw err;
+    }
 }
 export function MapToComponentStatus(lifecycle) {
-    switch (lifecycle) {
-        case 'Active': return 'Published';
-        case 'Pending': return 'Draft';
-        case 'Inactive': return 'Deprecated';
-    }
+    return FormLifecycleComponentStatus(lifecycle);
 }
 /** @deprecated Use {@link MapToComponentStatus}. */
 export function mapToComponentStatus(lifecycle) {
@@ -242,7 +297,7 @@ export async function InsertComponent(opts) {
     component.Name = spec.name ?? fallbackName;
     component.Title = spec.title ?? fallbackName;
     component.Description = description ?? spec.description ?? null;
-    component.Type = "Form";
+    component.Type = opts.componentType ?? "Form";
     component.Status = MapToComponentStatus(componentStatus);
     component.Version = version;
     component.VersionSequence = versionSequence;
@@ -259,9 +314,9 @@ export async function insertComponent(opts) {
     return InsertComponent(opts);
 }
 /**
- * Insert a new EntityFormOverride row. Always User-scoped (security clamp)
- * unless `allowGlobalOrRole` is explicitly true — which is reserved for the
- * future "promote variant" UI path, not the agent.
+ * Insert a new EntityFormOverride row, always User-scoped to the caller. Actions
+ * write personal forms only; sharing a form with a role or everyone is done from
+ * Form Builder or the form's Manage drawer.
  */
 export async function InsertOverride(opts) {
     const { provider, user, entityID, componentID, name, description, notes, status, priority } = opts;
@@ -382,4 +437,73 @@ export function ParseVersionBumpKind(raw) {
 export function parseVersionBumpKind(raw) {
     return ParseVersionBumpKind(raw);
 }
+/**
+ * Reads the `formContribution` block of a linted form-panel spec, resolves the related entity it
+ * claims to its registered name and ID, and derives the row's key with
+ * `ResolveContributionWriteKey`, seeding a panel key from `spec.name`.
+ *
+ * Fails with `LINT_FAILED` when the block cannot be read, `RELATED_ENTITY_NOT_FOUND` when the
+ * related entity is not registered, `INVALID_CLAIM` when the row the spec maps to breaks a claim
+ * rule the database enforces (`ContributionClaimRefusal`), and `INVALID_CONTRIBUTION_KEY` when the
+ * key does not match `CONTRIBUTION_KEY_PATTERN`. Callers run it before any write.
+ *
+ * @param currentKey The key of the row being modified; omit for a new row. When the spec names
+ * no key and claims no grid, a panel key here is kept, so renaming the component does not change
+ * the contribution's identity.
+ */
+export function ResolveContributionRegistration(provider, spec, currentKey = null) {
+    const contribution = GetDeclaredFormContribution(spec);
+    if (!contribution)
+        return { error: Failure("LINT_FAILED", "Spec.formContribution could not be read.") };
+    let relatedEntityID = null;
+    if (contribution.relatedEntity) {
+        const related = provider.EntityByName(contribution.relatedEntity);
+        if (!related) {
+            return { error: Failure("RELATED_ENTITY_NOT_FOUND", `Related entity '${contribution.relatedEntity}' is not registered.`) };
+        }
+        relatedEntityID = related.ID;
+        // The registered casing keeps the derived key stable.
+        contribution.relatedEntity = related.Name;
+    }
+    const relatedEntityName = contribution.relatedEntity ?? null;
+    if (!contribution.contributionKey && !relatedEntityName && IsPanelContributionKey(currentKey)) {
+        contribution.contributionKey = currentKey;
+    }
+    const componentName = spec.name?.trim() || null;
+    const rowOptions = { relatedEntityID, relatedEntityName, componentName };
+    const claimRefusal = ContributionClaimRefusal(ContributionSpecColumns(contribution, rowOptions));
+    if (claimRefusal)
+        return { error: Failure("INVALID_CLAIM", claimRefusal) };
+    const writeKey = ResolveContributionWriteKey(contribution, relatedEntityName, componentName);
+    if (writeKey && !CONTRIBUTION_KEY_PATTERN.test(writeKey)) {
+        return { error: Failure("INVALID_CONTRIBUTION_KEY", `Contribution key '${writeKey}' must match ${CONTRIBUTION_KEY_PATTERN.source}.`) };
+    }
+    return { Contribution: contribution, RowOptions: rowOptions, WriteKey: writeKey };
+}
+/**
+ * Insert a new EntityFormContribution row. Always User-scoped — promotion to Role or
+ * Global is a deliberate human act, not something an agent write path can reach.
+ */
+export async function InsertContribution(opts) {
+    const { provider, user, entityID, componentID, name, description, notes, registration, status, precedence } = opts;
+    const row = await provider.GetEntityObject("MJ: Entity Form Contributions", user);
+    row.NewRecord();
+    row.EntityID = entityID;
+    row.ComponentID = componentID;
+    row.Name = name;
+    row.Description = description;
+    row.Notes = notes ?? null;
+    ApplyContributionSpecToRow(row, registration.Contribution, registration.RowOptions);
+    // Security clamp: agents write User scope only. Promotion is a human act.
+    row.Scope = "User";
+    row.UserID = user.ID;
+    row.RoleID = null;
+    row.Precedence = precedence;
+    row.Status = status;
+    const saved = await row.Save();
+    if (!saved) {
+        return { error: Failure("PERSIST_FAILED", `Contribution insert failed: ${row.LatestResult?.CompleteMessage ?? "unknown error"}`) };
+    }
+    return { id: row.ID };
+}
 //# sourceMappingURL=_shared.js.map