@wildo-ai/saas-models 1.0.1

package/dist/esm/guidance/lifecycle-state.shared.resources-config.schemas.js

@@ -0,0 +1,135 @@
+/**
+ * Lifecycle State Shared Resource Configurations
+ *
+ * Resource configurations for dual-scope lifecycle state management (USER / ORGANIZATION).
+ * Each scope tracks lifecycle stage progression (signed_up → activated → engaged → dormant → reactivated).
+ * Uses LifecycleStateSchema as mainSchema across all three scopes.
+ */
+import { LifecycleStateSchema } from './lifecycle-state.shared.schemas.js';
+import { CoreResourceOperation } from '../resources/resources.shared.core.definitions.js';
+import { ResourceOperationRiskLevel } from '../resources/resources.shared.schemas.js';
+import { CoreResourceType, coreResourceShared_FieldIdentifier } from '../resources/resources.shared.core.definitions.js';
+import { ResourceOperationVariantType } from '../resources/resources.shared.schemas.js';
+import { createResourceConfiguration_Initialization } from '../resources/resources-config.shared.factory.js';
+import { CORE_APP_ROLES, CORE_ORG_ROLES } from '../security/authorizations/roles.shared.schemas.js';
+export const userLifecycleStateResourceConfiguration_InitializationFactory = (resourcesRelationships) => createResourceConfiguration_Initialization({
+    mainSchema: LifecycleStateSchema,
+    resourceIdentifier: CoreResourceType.USER_LIFECYCLE_STATE,
+    resourceFieldIdentifier: coreResourceShared_FieldIdentifier[CoreResourceType.USER_LIFECYCLE_STATE],
+    resourceRelationships: resourcesRelationships,
+    isSystemResource: true,
+    coreOperations: [
+        CoreResourceOperation.READ,
+        CoreResourceOperation.SEARCH,
+        CoreResourceOperation.UPDATE,
+        CoreResourceOperation.CREATE,
+    ],
+    customOperation: {},
+    operationsConfiguration: {
+        [CoreResourceOperation.READ]: {
+            variants: [
+                {
+                    variantType: ResourceOperationVariantType.API_CALL,
+                    isDefault: true,
+                    roles: [CORE_APP_ROLES.APP_USER],
+                    riskLevel: ResourceOperationRiskLevel.LOW,
+                }
+            ]
+        },
+        [CoreResourceOperation.SEARCH]: {
+            variants: [{
+                    variantType: ResourceOperationVariantType.API_CALL,
+                    isDefault: true,
+                    roles: [CORE_APP_ROLES.APP_USER],
+                    riskLevel: ResourceOperationRiskLevel.LOW,
+                    isSearchable: false,
+                    searchableFields: [],
+                    searchableOptions: { caseSensitive: false, fullMatchOnly: false },
+                    filterFields: {},
+                    sortFields: [],
+                    maxPaginatedResultPerPageLimit: 50,
+                }],
+        },
+        [CoreResourceOperation.UPDATE]: {
+            variants: [
+                {
+                    variantType: ResourceOperationVariantType.REPOSITORY_ONLY,
+                    isDefault: true,
+                    roles: [CORE_APP_ROLES.APP_USER],
+                    riskLevel: ResourceOperationRiskLevel.LOW,
+                }
+            ],
+        },
+        [CoreResourceOperation.CREATE]: {
+            variants: [
+                {
+                    variantType: ResourceOperationVariantType.REPOSITORY_ONLY,
+                    isDefault: true,
+                    roles: [CORE_APP_ROLES.APP_USER],
+                    riskLevel: ResourceOperationRiskLevel.LOW,
+                }
+            ],
+        },
+    },
+});
+export const organizationLifecycleStateResourceConfiguration_InitializationFactory = (resourcesRelationships) => createResourceConfiguration_Initialization({
+    mainSchema: LifecycleStateSchema,
+    resourceIdentifier: CoreResourceType.ORGANIZATION_LIFECYCLE_STATE,
+    resourceFieldIdentifier: coreResourceShared_FieldIdentifier[CoreResourceType.ORGANIZATION_LIFECYCLE_STATE],
+    resourceRelationships: resourcesRelationships,
+    isSystemResource: true,
+    coreOperations: [
+        CoreResourceOperation.READ,
+        CoreResourceOperation.SEARCH,
+        CoreResourceOperation.UPDATE,
+        CoreResourceOperation.CREATE,
+    ],
+    customOperation: {},
+    operationsConfiguration: {
+        [CoreResourceOperation.READ]: {
+            variants: [
+                {
+                    variantType: ResourceOperationVariantType.API_CALL,
+                    isDefault: true,
+                    roles: [CORE_ORG_ROLES.ORG_MEMBER],
+                    riskLevel: ResourceOperationRiskLevel.LOW,
+                }
+            ]
+        },
+        [CoreResourceOperation.SEARCH]: {
+            variants: [{
+                    variantType: ResourceOperationVariantType.API_CALL,
+                    isDefault: true,
+                    roles: [CORE_ORG_ROLES.ORG_MEMBER],
+                    riskLevel: ResourceOperationRiskLevel.LOW,
+                    isSearchable: false,
+                    searchableFields: [],
+                    searchableOptions: { caseSensitive: false, fullMatchOnly: false },
+                    filterFields: {},
+                    sortFields: [],
+                    maxPaginatedResultPerPageLimit: 50,
+                }],
+        },
+        [CoreResourceOperation.UPDATE]: {
+            variants: [
+                {
+                    variantType: ResourceOperationVariantType.REPOSITORY_ONLY,
+                    isDefault: true,
+                    roles: [CORE_ORG_ROLES.ORG_ADMIN],
+                    riskLevel: ResourceOperationRiskLevel.LOW,
+                }
+            ],
+        },
+        [CoreResourceOperation.CREATE]: {
+            variants: [
+                {
+                    variantType: ResourceOperationVariantType.REPOSITORY_ONLY,
+                    isDefault: true,
+                    roles: [CORE_ORG_ROLES.ORG_ADMIN],
+                    riskLevel: ResourceOperationRiskLevel.LOW,
+                }
+            ],
+        },
+    },
+});
+//# sourceMappingURL=lifecycle-state.shared.resources-config.schemas.js.map

package/dist/esm/guidance/lifecycle-state.shared.resources-config.schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle-state.shared.resources-config.schemas.js","sourceRoot":"","sources":["../../../src/guidance/lifecycle-state.shared.resources-config.schemas.ts"],"names":[],"mappings":"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"}

package/dist/esm/guidance/lifecycle-state.shared.schemas.d.ts

@@ -0,0 +1,110 @@
+import { z } from 'zod';
+import { CoreResourceType } from '../resources/resources.shared.core.definitions.js';
+/** ──────────────────────────────────────────────────────────────
+ * Lifecycle Stage — Ordered Progression with Dormancy/Reactivation Branches
+ * ────────────────────────────────────────────────────────────── */
+/** Lifecycle stages — ordered progression with dormancy/reactivation branches */
+export declare enum LifecycleStage {
+    /** User has signed up but hasn't met activation criteria */
+    SIGNED_UP = "signed_up",
+    /** User has met activation criteria (reached product value) */
+    ACTIVATED = "activated",
+    /** User shows sustained engagement (optional — requires engagementThreshold config) */
+    ENGAGED = "engaged",
+    /** User has been inactive past the dormancy threshold */
+    DORMANT = "dormant",
+    /** Previously dormant user has returned */
+    REACTIVATED = "reactivated",
+    /** User has churned (billing-triggered — deferred) */
+    CHURNED = "churned",
+    /** User has been fully offboarded (deferred) */
+    OFFBOARDED = "offboarded"
+}
+/** ──────────────────────────────────────────────────────────────
+ * Lifecycle Scope — Bi-Scope (same as guidance/progression)
+ * ────────────────────────────────────────────────────────────── */
+/** Lifecycle state scope — bi-scope (same as guidance/progression) */
+export declare enum LifecycleScope {
+    USER = "user",
+    ORGANIZATION = "organization"
+}
+/** ──────────────────────────────────────────────────────────────
+ * Const Maps — State Machine, Stage Sets, Scope Mappings
+ * ────────────────────────────────────────────────────────────── */
+/** "Happy path" progression weight — used ONLY for the linear happy path.
+ *  The lifecycle is NOT a linear progression (it branches at dormancy/reactivation).
+ *  `hasReachedStage()` uses stagesVisited instead — see below. */
+export declare const LIFECYCLE_HAPPY_PATH_WEIGHT: Readonly<Record<LifecycleStage, number>>;
+/** Valid state transitions — the lifecycle state machine.
+ *  Key = source stage, Value = valid target stages. */
+export declare const LIFECYCLE_VALID_TRANSITIONS: Readonly<Record<LifecycleStage, readonly LifecycleStage[]>>;
+/** Stages that represent an "active" user (not dormant/churned/offboarded) */
+export declare const LIFECYCLE_ACTIVE_STAGES: readonly [LifecycleStage.SIGNED_UP, LifecycleStage.ACTIVATED, LifecycleStage.ENGAGED, LifecycleStage.REACTIVATED];
+/** Stages from which a user can become dormant (all active stages except SIGNED_UP) */
+export declare const LIFECYCLE_DORMANCY_SOURCE_STAGES: readonly [LifecycleStage.ACTIVATED, LifecycleStage.ENGAGED, LifecycleStage.REACTIVATED];
+/** Stages eligible for engagement threshold evaluation (can transition to ENGAGED) */
+export declare const LIFECYCLE_ENGAGEMENT_ELIGIBLE_STAGES: readonly [LifecycleStage.ACTIVATED, LifecycleStage.REACTIVATED];
+/** Maps LifecycleScope → corresponding CoreResourceType for lifecycle state storage */
+export declare const LIFECYCLE_SCOPE_TO_RESOURCE: Readonly<Record<LifecycleScope, CoreResourceType>>;
+/** Maps LifecycleScope → corresponding Progression resource type (for activation criteria eval).
+ *  Named to avoid collision with existing PROGRESSION_SCOPE_TO_RESOURCE in milestone-definition.shared.schemas.ts
+ *  (which is keyed by ProgressionScope, not LifecycleScope). */
+export declare const LIFECYCLE_TO_PROGRESSION_RESOURCE: Readonly<Record<LifecycleScope, CoreResourceType>>;
+/** Maps LifecycleScope → corresponding Guidance state resource type (for GUIDANCE_COMPLETED activation criteria). */
+export declare const LIFECYCLE_TO_GUIDANCE_RESOURCE: Readonly<Record<LifecycleScope, CoreResourceType>>;
+/** All lifecycle resource types — for conditional exclusion when lifecycle disabled
+ *  (same pattern as BILLING_RESOURCE_TYPES in resources.shared.core.definitions.ts) */
+export declare const LIFECYCLE_RESOURCE_TYPES: ReadonlySet<CoreResourceType>;
+/** Guidance state resource types — used to detect guidance state updates for activation criteria */
+export declare const GUIDANCE_STATE_RESOURCE_TYPES: ReadonlySet<CoreResourceType>;
+/** ──────────────────────────────────────────────────────────────
+ * Utility Functions
+ * ────────────────────────────────────────────────────────────── */
+/** Validate if a lifecycle transition is valid per the state machine. */
+export declare function isValidLifecycleTransition(from: LifecycleStage, to: LifecycleStage): boolean;
+/** ──────────────────────────────────────────────────────────────
+ * Zod Schemas — Lifecycle State Document
+ * ────────────────────────────────────────────────────────────── */
+/** Record of a single stage transition */
+export declare const LifecycleStageTransitionSchema: z.ZodObject<{
+    stage: z.ZodEnum<typeof LifecycleStage>;
+    enteredAt: z.ZodCoercedDate<unknown>;
+    exitedAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
+    trigger: z.ZodOptional<z.ZodString>;
+}, z.core.$strip, core.$ZodObjectExtra>;
+export type LifecycleStageTransition = z.infer<typeof LifecycleStageTransitionSchema>;
+/** Engagement metrics tracked while user is ACTIVATED */
+export declare const LifecycleEngagementSchema: z.ZodObject<{
+    operationsSinceActivation: z.ZodDefault<z.ZodNumber>;
+    activeDates: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strip, core.$ZodObjectExtra>;
+export type LifecycleEngagement = z.infer<typeof LifecycleEngagementSchema>;
+/** Top-level lifecycle state document (stored as core resource) */
+export declare const LifecycleStateSchema: z.ZodObject<{
+    currentStage: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodEnum<typeof LifecycleStage>>>;
+    stageEnteredAt: z.ZodCoercedDate<unknown>;
+    stageHistory: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        stage: z.ZodEnum<typeof LifecycleStage>;
+        enteredAt: z.ZodCoercedDate<unknown>;
+        exitedAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
+        trigger: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip, core.$ZodObjectExtra>>>;
+    stagesVisited: z.ZodDefault<z.ZodArray<z.ZodEnum<typeof LifecycleStage>>>;
+    lastActiveAt: z.ZodCoercedDate<unknown>;
+    activationCriteriaMet: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodBoolean>>;
+    engagement: z.ZodDefault<z.ZodObject<{
+        operationsSinceActivation: z.ZodDefault<z.ZodNumber>;
+        activeDates: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip, core.$ZodObjectExtra>>;
+}, z.core.$strip, core.$ZodObjectExtra>;
+export type LifecycleState = z.infer<typeof LifecycleStateSchema>;
+/** ──────────────────────────────────────────────────────────────
+ * State Factory + Stage History Utility
+ * ────────────────────────────────────────────────────────────── */
+/** Default initial lifecycle state factory — used by auto-create and custom implementations. */
+export declare function createInitialLifecycleState(now?: Date): LifecycleState;
+/** Check if the user has ACTUALLY visited a given stage (not a linear comparison).
+ *  Uses `stagesVisited` for reliable lookups that survive the stageHistory cap.
+ *  Falls back to `stageHistory` for documents created before `stagesVisited` was added. */
+export declare function hasReachedStage(state: LifecycleState, targetStage: LifecycleStage): boolean;
+//# sourceMappingURL=lifecycle-state.shared.schemas.d.ts.map

package/dist/esm/guidance/lifecycle-state.shared.schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle-state.shared.schemas.d.ts","sourceRoot":"","sources":["../../../src/guidance/lifecycle-state.shared.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,gBAAgB,EAAE,MAAM,gDAAgD,CAAC;AAElF;;oEAEoE;AAEpE,iFAAiF;AACjF,oBAAY,cAAc;IACxB,4DAA4D;IAC5D,SAAS,cAAc;IACvB,+DAA+D;IAC/D,SAAS,cAAc;IACvB,uFAAuF;IACvF,OAAO,YAAY;IACnB,yDAAyD;IACzD,OAAO,YAAY;IACnB,2CAA2C;IAC3C,WAAW,gBAAgB;IAC3B,sDAAsD;IACtD,OAAO,YAAY;IACnB,gDAAgD;IAChD,UAAU,eAAe;CAC1B;AAED;;oEAEoE;AAEpE,sEAAsE;AACtE,oBAAY,cAAc;IACxB,IAAI,SAAS;IACb,YAAY,iBAAiB;CAC9B;AAED;;oEAEoE;AAEpE;;kEAEkE;AAClE,eAAO,MAAM,2BAA2B,EAAE,QAAQ,CAAC,MAAM,CAAC,cAAc,EAAE,MAAM,CAAC,CAQvE,CAAC;AAEX;uDACuD;AACvD,eAAO,MAAM,2BAA2B,EAAE,QAAQ,CAAC,MAAM,CAAC,cAAc,EAAE,SAAS,cAAc,EAAE,CAAC,CAQ1F,CAAC;AAEX,8EAA8E;AAC9E,eAAO,MAAM,uBAAuB,mHAK1B,CAAC;AAEX,uFAAuF;AACvF,eAAO,MAAM,gCAAgC,yFAInC,CAAC;AAEX,sFAAsF;AACtF,eAAO,MAAM,oCAAoC,iEAGvC,CAAC;AAEX,uFAAuF;AACvF,eAAO,MAAM,2BAA2B,EAAE,QAAQ,CAAC,MAAM,CAAC,cAAc,EAAE,gBAAgB,CAAC,CAGjF,CAAC;AAEX;;gEAEgE;AAChE,eAAO,MAAM,iCAAiC,EAAE,QAAQ,CAAC,MAAM,CAAC,cAAc,EAAE,gBAAgB,CAAC,CAGvF,CAAC;AAEX,qHAAqH;AACrH,eAAO,MAAM,8BAA8B,EAAE,QAAQ,CAAC,MAAM,CAAC,cAAc,EAAE,gBAAgB,CAAC,CAGpF,CAAC;AAEX;uFACuF;AACvF,eAAO,MAAM,wBAAwB,EAAE,WAAW,CAAC,gBAAgB,CAGjE,CAAC;AAEH,oGAAoG;AACpG,eAAO,MAAM,6BAA6B,EAAE,WAAW,CAAC,gBAAgB,CAGtE,CAAC;AAEH;;oEAEoE;AAEpE,yEAAyE;AACzE,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,cAAc,EAAE,EAAE,EAAE,cAAc,GAAG,OAAO,CAE5F;AAED;;oEAEoE;AAEpE,0CAA0C;AAC1C,eAAO,MAAM,8BAA8B;;;;;uCASzC,CAAC;AACH,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,8BAA8B,CAAC,CAAC;AAEtF,yDAAyD;AACzD,eAAO,MAAM,yBAAyB;;;uCAKpC,CAAC;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAE5E,mEAAmE;AACnE,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;uCAmB/B,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE;;oEAEoE;AAEpE,gGAAgG;AAChG,wBAAgB,2BAA2B,CAAC,GAAG,GAAE,IAAiB,GAAG,cAAc,CAclF;AAED;;2FAE2F;AAC3F,wBAAgB,eAAe,CAAC,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,cAAc,GAAG,OAAO,CAM3F"}

package/dist/esm/guidance/lifecycle-state.shared.schemas.js

@@ -0,0 +1,184 @@
+import { z } from 'zod';
+import { CoreResourceType } from '../resources/resources.shared.core.definitions.js';
+/** ──────────────────────────────────────────────────────────────
+ * Lifecycle Stage — Ordered Progression with Dormancy/Reactivation Branches
+ * ────────────────────────────────────────────────────────────── */
+/** Lifecycle stages — ordered progression with dormancy/reactivation branches */
+export var LifecycleStage;
+(function (LifecycleStage) {
+    /** User has signed up but hasn't met activation criteria */
+    LifecycleStage["SIGNED_UP"] = "signed_up";
+    /** User has met activation criteria (reached product value) */
+    LifecycleStage["ACTIVATED"] = "activated";
+    /** User shows sustained engagement (optional — requires engagementThreshold config) */
+    LifecycleStage["ENGAGED"] = "engaged";
+    /** User has been inactive past the dormancy threshold */
+    LifecycleStage["DORMANT"] = "dormant";
+    /** Previously dormant user has returned */
+    LifecycleStage["REACTIVATED"] = "reactivated";
+    /** User has churned (billing-triggered — deferred) */
+    LifecycleStage["CHURNED"] = "churned";
+    /** User has been fully offboarded (deferred) */
+    LifecycleStage["OFFBOARDED"] = "offboarded";
+})(LifecycleStage || (LifecycleStage = {}));
+/** ──────────────────────────────────────────────────────────────
+ * Lifecycle Scope — Bi-Scope (same as guidance/progression)
+ * ────────────────────────────────────────────────────────────── */
+/** Lifecycle state scope — bi-scope (same as guidance/progression) */
+export var LifecycleScope;
+(function (LifecycleScope) {
+    LifecycleScope["USER"] = "user";
+    LifecycleScope["ORGANIZATION"] = "organization";
+})(LifecycleScope || (LifecycleScope = {}));
+/** ──────────────────────────────────────────────────────────────
+ * Const Maps — State Machine, Stage Sets, Scope Mappings
+ * ────────────────────────────────────────────────────────────── */
+/** "Happy path" progression weight — used ONLY for the linear happy path.
+ *  The lifecycle is NOT a linear progression (it branches at dormancy/reactivation).
+ *  `hasReachedStage()` uses stagesVisited instead — see below. */
+export const LIFECYCLE_HAPPY_PATH_WEIGHT = {
+    [LifecycleStage.SIGNED_UP]: 0,
+    [LifecycleStage.ACTIVATED]: 1,
+    [LifecycleStage.ENGAGED]: 2,
+    [LifecycleStage.REACTIVATED]: 2, // Same weight as ENGAGED — reactivated users regain engaged-level access
+    [LifecycleStage.DORMANT]: -1, // Not on happy path
+    [LifecycleStage.CHURNED]: -2, // Terminal negative
+    [LifecycleStage.OFFBOARDED]: -3, // Terminal negative
+};
+/** Valid state transitions — the lifecycle state machine.
+ *  Key = source stage, Value = valid target stages. */
+export const LIFECYCLE_VALID_TRANSITIONS = {
+    [LifecycleStage.SIGNED_UP]: [LifecycleStage.ACTIVATED],
+    [LifecycleStage.ACTIVATED]: [LifecycleStage.ENGAGED, LifecycleStage.DORMANT],
+    [LifecycleStage.ENGAGED]: [LifecycleStage.DORMANT],
+    [LifecycleStage.DORMANT]: [LifecycleStage.REACTIVATED, LifecycleStage.CHURNED],
+    [LifecycleStage.REACTIVATED]: [LifecycleStage.ENGAGED, LifecycleStage.DORMANT],
+    [LifecycleStage.CHURNED]: [LifecycleStage.OFFBOARDED],
+    [LifecycleStage.OFFBOARDED]: [],
+};
+/** Stages that represent an "active" user (not dormant/churned/offboarded) */
+export const LIFECYCLE_ACTIVE_STAGES = [
+    LifecycleStage.SIGNED_UP,
+    LifecycleStage.ACTIVATED,
+    LifecycleStage.ENGAGED,
+    LifecycleStage.REACTIVATED,
+];
+/** Stages from which a user can become dormant (all active stages except SIGNED_UP) */
+export const LIFECYCLE_DORMANCY_SOURCE_STAGES = [
+    LifecycleStage.ACTIVATED,
+    LifecycleStage.ENGAGED,
+    LifecycleStage.REACTIVATED,
+];
+/** Stages eligible for engagement threshold evaluation (can transition to ENGAGED) */
+export const LIFECYCLE_ENGAGEMENT_ELIGIBLE_STAGES = [
+    LifecycleStage.ACTIVATED,
+    LifecycleStage.REACTIVATED,
+];
+/** Maps LifecycleScope → corresponding CoreResourceType for lifecycle state storage */
+export const LIFECYCLE_SCOPE_TO_RESOURCE = {
+    [LifecycleScope.USER]: CoreResourceType.USER_LIFECYCLE_STATE,
+    [LifecycleScope.ORGANIZATION]: CoreResourceType.ORGANIZATION_LIFECYCLE_STATE,
+};
+/** Maps LifecycleScope → corresponding Progression resource type (for activation criteria eval).
+ *  Named to avoid collision with existing PROGRESSION_SCOPE_TO_RESOURCE in milestone-definition.shared.schemas.ts
+ *  (which is keyed by ProgressionScope, not LifecycleScope). */
+export const LIFECYCLE_TO_PROGRESSION_RESOURCE = {
+    [LifecycleScope.USER]: CoreResourceType.USER_PROGRESSION_STATE,
+    [LifecycleScope.ORGANIZATION]: CoreResourceType.ORGANIZATION_PROGRESSION_STATE,
+};
+/** Maps LifecycleScope → corresponding Guidance state resource type (for GUIDANCE_COMPLETED activation criteria). */
+export const LIFECYCLE_TO_GUIDANCE_RESOURCE = {
+    [LifecycleScope.USER]: CoreResourceType.USER_GUIDANCE_STATE,
+    [LifecycleScope.ORGANIZATION]: CoreResourceType.ORGANIZATION_GUIDANCE_STATE,
+};
+/** All lifecycle resource types — for conditional exclusion when lifecycle disabled
+ *  (same pattern as BILLING_RESOURCE_TYPES in resources.shared.core.definitions.ts) */
+export const LIFECYCLE_RESOURCE_TYPES = new Set([
+    CoreResourceType.USER_LIFECYCLE_STATE,
+    CoreResourceType.ORGANIZATION_LIFECYCLE_STATE,
+]);
+/** Guidance state resource types — used to detect guidance state updates for activation criteria */
+export const GUIDANCE_STATE_RESOURCE_TYPES = new Set([
+    CoreResourceType.USER_GUIDANCE_STATE,
+    CoreResourceType.ORGANIZATION_GUIDANCE_STATE,
+]);
+/** ──────────────────────────────────────────────────────────────
+ * Utility Functions
+ * ────────────────────────────────────────────────────────────── */
+/** Validate if a lifecycle transition is valid per the state machine. */
+export function isValidLifecycleTransition(from, to) {
+    return LIFECYCLE_VALID_TRANSITIONS[from]?.includes(to) ?? false;
+}
+/** ──────────────────────────────────────────────────────────────
+ * Zod Schemas — Lifecycle State Document
+ * ────────────────────────────────────────────────────────────── */
+/** Record of a single stage transition */
+export const LifecycleStageTransitionSchema = z.object({
+    /** Stage that was entered */
+    stage: z.enum(LifecycleStage),
+    /** When this stage was entered */
+    enteredAt: z.coerce.date(),
+    /** When this stage was exited (undefined if current) */
+    exitedAt: z.coerce.date().optional(),
+    /** What triggered this transition (milestone ref, cron, operation, etc.) */
+    trigger: z.string().optional(),
+});
+/** Engagement metrics tracked while user is ACTIVATED */
+export const LifecycleEngagementSchema = z.object({
+    /** Total operations since activation */
+    operationsSinceActivation: z.number().int().default(0),
+    /** Distinct active dates since activation (YYYY-MM-DD strings) */
+    activeDates: z.array(z.string()).default([]),
+});
+/** Top-level lifecycle state document (stored as core resource) */
+export const LifecycleStateSchema = z.object({
+    /** Current lifecycle stage */
+    currentStage: z.enum(LifecycleStage).default(LifecycleStage.SIGNED_UP).isSummaryField(),
+    /** When the current stage was entered */
+    stageEnteredAt: z.coerce.date(),
+    /** History of stage transitions (most recent first, capped at last 20) */
+    stageHistory: z.array(LifecycleStageTransitionSchema).default([]),
+    /** Deduplicated set of all stages ever visited (survives stageHistory cap).
+     *  Used by `hasReachedStage()` for reliable stage visitation checks. */
+    stagesVisited: z.array(z.enum(LifecycleStage)).default([]),
+    /** Last activity timestamp (updated on operations, debounced ~30 min) */
+    lastActiveAt: z.coerce.date(),
+    /** Which activation criteria have been met (keyed by criterion ref) */
+    activationCriteriaMet: z.record(z.string(), z.boolean()).default({}),
+    /** Engagement metrics (tracked while ACTIVATED, used for ENGAGED transition) */
+    engagement: LifecycleEngagementSchema.default({
+        operationsSinceActivation: 0,
+        activeDates: [],
+    }),
+});
+/** ──────────────────────────────────────────────────────────────
+ * State Factory + Stage History Utility
+ * ────────────────────────────────────────────────────────────── */
+/** Default initial lifecycle state factory — used by auto-create and custom implementations. */
+export function createInitialLifecycleState(now = new Date()) {
+    return {
+        currentStage: LifecycleStage.SIGNED_UP,
+        stageEnteredAt: now,
+        stageHistory: [{
+                stage: LifecycleStage.SIGNED_UP,
+                enteredAt: now,
+                trigger: 'auto_create',
+            }],
+        stagesVisited: [LifecycleStage.SIGNED_UP],
+        lastActiveAt: now,
+        activationCriteriaMet: {},
+        engagement: { operationsSinceActivation: 0, activeDates: [] },
+    };
+}
+/** Check if the user has ACTUALLY visited a given stage (not a linear comparison).
+ *  Uses `stagesVisited` for reliable lookups that survive the stageHistory cap.
+ *  Falls back to `stageHistory` for documents created before `stagesVisited` was added. */
+export function hasReachedStage(state, targetStage) {
+    if (state.currentStage === targetStage)
+        return true;
+    if (state.stagesVisited?.length) {
+        return state.stagesVisited.includes(targetStage);
+    }
+    return state.stageHistory.some(entry => entry.stage === targetStage);
+}
+//# sourceMappingURL=lifecycle-state.shared.schemas.js.map

package/dist/esm/guidance/lifecycle-state.shared.schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle-state.shared.schemas.js","sourceRoot":"","sources":["../../../src/guidance/lifecycle-state.shared.schemas.ts"],"names":[],"mappings":"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"}

package/dist/esm/guidance/milestone-builders.shared.d.ts

@@ -0,0 +1,49 @@
+import { MilestoneType, MilestoneRewardType, ProgressionScope } from './milestone-definition.shared.schemas.js';
+import type { MilestoneDefinition, MilestoneReward, MilestoneTrigger, MilestoneLifecycleTransition } from './milestone-definition.shared.schemas.js';
+/**
+ * defineMilestone() — Milestone Builder
+ *
+ * Creates a MilestoneDefinition with sensible defaults.
+ * Follows the same pattern as defineFeature() / defineLimitFeature().
+ *
+ * @example // Personal milestone (scope defaults to USER)
+ * defineMilestone('FIRST_PROJECT_CREATED', {
+ *   type: MilestoneType.FIRST_TIME,
+ *   trigger: { resourceType: 'PROJECTS', operation: CoreResourceOperation.CREATE },
+ *   reward: { type: MilestoneRewardType.CELEBRATION, celebrationLevel: 'high' },
+ *   category: 'getting-started',
+ *   points: 10,
+ *   labels: { description: true },
+ * })
+ *
+ * @example // Org-wide milestone — any member creating the 100th project triggers it
+ * defineMilestone('ORG_100_PROJECTS', {
+ *   type: MilestoneType.COUNT_THRESHOLD,
+ *   scope: ProgressionScope.ORGANIZATION,
+ *   trigger: { resourceType: 'PROJECTS', operation: CoreResourceOperation.CREATE },
+ *   threshold: 100,
+ *   reward: { type: MilestoneRewardType.CELEBRATION, celebrationLevel: 'high' },
+ *   category: 'team-achievements',
+ *   points: 50,
+ * })
+ */
+export declare function defineMilestone(identifier: string, options: {
+    type: MilestoneType;
+    /** Scope of this milestone — defaults to USER if omitted.
+     *  ORGANIZATION milestones track collective achievements (any member can trigger). */
+    scope?: ProgressionScope;
+    trigger: MilestoneTrigger;
+    threshold?: number;
+    conditionRef?: string;
+    reward: MilestoneReward;
+    category: string;
+    points?: number;
+    labels?: {
+        description?: boolean;
+    };
+    lifecycleTransition?: MilestoneLifecycleTransition;
+    dependencies?: string[];
+}): MilestoneDefinition;
+export { MilestoneType, MilestoneRewardType, ProgressionScope };
+export type { MilestoneDefinition, MilestoneReward, MilestoneTrigger, MilestoneLifecycleTransition };
+//# sourceMappingURL=milestone-builders.shared.d.ts.map

package/dist/esm/guidance/milestone-builders.shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"milestone-builders.shared.d.ts","sourceRoot":"","sources":["../../../src/guidance/milestone-builders.shared.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,uCAAuC,CAAC;AAC7G,OAAO,KAAK,EAAE,mBAAmB,EAAE,eAAe,EAAE,gBAAgB,EAAE,4BAA4B,EAAE,MAAM,uCAAuC,CAAC;AAElJ;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,eAAe,CAC7B,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE;IACP,IAAI,EAAE,aAAa,CAAC;IACpB;0FACsF;IACtF,KAAK,CAAC,EAAE,gBAAgB,CAAC;IACzB,OAAO,EAAE,gBAAgB,CAAC;IAC1B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,eAAe,CAAC;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IACnC,mBAAmB,CAAC,EAAE,4BAA4B,CAAC;IACnD,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB,GACA,mBAAmB,CAerB;AAGD,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,CAAC;AAChE,YAAY,EAAE,mBAAmB,EAAE,eAAe,EAAE,gBAAgB,EAAE,4BAA4B,EAAE,CAAC"}

package/dist/esm/guidance/milestone-builders.shared.js

@@ -0,0 +1,47 @@
+import { MilestoneType, MilestoneRewardType, ProgressionScope } from './milestone-definition.shared.schemas.js';
+/**
+ * defineMilestone() — Milestone Builder
+ *
+ * Creates a MilestoneDefinition with sensible defaults.
+ * Follows the same pattern as defineFeature() / defineLimitFeature().
+ *
+ * @example // Personal milestone (scope defaults to USER)
+ * defineMilestone('FIRST_PROJECT_CREATED', {
+ *   type: MilestoneType.FIRST_TIME,
+ *   trigger: { resourceType: 'PROJECTS', operation: CoreResourceOperation.CREATE },
+ *   reward: { type: MilestoneRewardType.CELEBRATION, celebrationLevel: 'high' },
+ *   category: 'getting-started',
+ *   points: 10,
+ *   labels: { description: true },
+ * })
+ *
+ * @example // Org-wide milestone — any member creating the 100th project triggers it
+ * defineMilestone('ORG_100_PROJECTS', {
+ *   type: MilestoneType.COUNT_THRESHOLD,
+ *   scope: ProgressionScope.ORGANIZATION,
+ *   trigger: { resourceType: 'PROJECTS', operation: CoreResourceOperation.CREATE },
+ *   threshold: 100,
+ *   reward: { type: MilestoneRewardType.CELEBRATION, celebrationLevel: 'high' },
+ *   category: 'team-achievements',
+ *   points: 50,
+ * })
+ */
+export function defineMilestone(identifier, options) {
+    return {
+        identifier,
+        type: options.type,
+        scope: options.scope ?? ProgressionScope.USER,
+        trigger: options.trigger,
+        threshold: options.threshold,
+        conditionRef: options.conditionRef,
+        reward: options.reward,
+        category: options.category,
+        points: options.points ?? 0,
+        labels: options.labels,
+        lifecycleTransition: options.lifecycleTransition,
+        dependencies: options.dependencies ?? [],
+    };
+}
+// Re-export types and enums for convenience from a single import point
+export { MilestoneType, MilestoneRewardType, ProgressionScope };
+//# sourceMappingURL=milestone-builders.shared.js.map

package/dist/esm/guidance/milestone-builders.shared.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"milestone-builders.shared.js","sourceRoot":"","sources":["../../../src/guidance/milestone-builders.shared.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,uCAAuC,CAAC;AAG7G;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,UAAU,eAAe,CAC7B,UAAkB,EAClB,OAcC;IAED,OAAO;QACL,UAAU;QACV,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,gBAAgB,CAAC,IAAI;QAC7C,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,YAAY,EAAE,OAAO,CAAC,YAAY;QAClC,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,CAAC;QAC3B,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,mBAAmB,EAAE,OAAO,CAAC,mBAAmB;QAChD,YAAY,EAAE,OAAO,CAAC,YAAY,IAAI,EAAE;KACzC,CAAC;AACJ,CAAC;AAED,uEAAuE;AACvE,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,CAAC"}