@oxygen-agent/cli 1.720.7 → 1.739.0

package/node_modules/@oxygen/shared/dist/future-signup-lifecycle-projection.js

@@ -0,0 +1,1233 @@
+import { createHash } from "node:crypto";
+import { FUTURE_SIGNUP_LIFECYCLE_CONTRACT_VERSION, FUTURE_SIGNUP_LIFECYCLE_PROJECTION_CONTRACT_VERSION, futureSignupJourneyId, futureSignupLifecycleEventId, futureSignupLifecycleProjectionFactId, futureSignupLifecycleProjectionRefreshFactId, futureSignupLostFactId, futureSignupPaidFactId, futureSignupSubscriptionEndedFactId, futureSignupTrialStartedFactId, futureSignupWorkspaceDeletedFactId, } from "./future-signup-events.js";
+/** Fixed destination-head authority. Contract upgrades cannot reset this stream. */
+export const FUTURE_SIGNUP_LIFECYCLE_PROJECTION_AUTHORITY = "oxygen_product_lifecycle";
+export const FUTURE_SIGNUP_LIFECYCLE_PROJECTION_FACT_TYPES = [
+    "trial_started",
+    "paid",
+    "lost",
+    "subscription_ended",
+    "workspace_deleted",
+    "projection_refreshed",
+];
+export const FUTURE_SIGNUP_LIFECYCLE_PROJECTION_BILLING_STAGES = [
+    "free_trial",
+    "paid",
+    "lost",
+];
+export const FUTURE_SIGNUP_LIFECYCLE_PROJECTION_PREBILLING_STAGES = [
+    "lead",
+    "interested",
+    "demo_booked",
+];
+export const FUTURE_SIGNUP_LIFECYCLE_PROJECTION_SEMANTIC_STAGES = [
+    ...FUTURE_SIGNUP_LIFECYCLE_PROJECTION_PREBILLING_STAGES,
+    ...FUTURE_SIGNUP_LIFECYCLE_PROJECTION_BILLING_STAGES,
+];
+export const FUTURE_SIGNUP_LIFECYCLE_PROJECTION_ALIAS_TYPES = [
+    "clerk_organization",
+    "clerk_user",
+    "domain",
+    "email",
+    "stripe_customer",
+];
+export const FUTURE_SIGNUP_LIFECYCLE_PROJECTION_ACTIVITY_TYPES = [
+    "trial_started",
+    "plan_paid",
+    "customer_lost",
+    "workspace_deleted",
+];
+/** Typed, PII-free parse failure. Raw values are intentionally never reflected. */
+export class FutureSignupLifecycleProjectionContractError extends TypeError {
+    path;
+    rule;
+    code = "future_signup_lifecycle_projection_invalid";
+    constructor(path, rule) {
+        super(`${path}: ${rule}`);
+        this.path = path;
+        this.rule = rule;
+        this.name = "FutureSignupLifecycleProjectionContractError";
+    }
+}
+/** Exact fingerprint algorithm used by the shipped v1 control builder. */
+export function futureSignupLifecycleProjectionFingerprints(input) {
+    const sourceFactFingerprint = sha256Canonical(input.sourceFact);
+    const subjectSetFingerprint = sha256Canonical(input.snapshot.subjects.map((subject) => ({
+        kind: subject.kind,
+        key: subject.key,
+        aggregate_revision: subject.aggregate_revision,
+        aggregate_fingerprint: subject.aggregate_fingerprint,
+    })));
+    const snapshotFingerprint = sha256Canonical(input.snapshot);
+    const projectionFingerprint = sha256Canonical({
+        contract_version: FUTURE_SIGNUP_LIFECYCLE_PROJECTION_CONTRACT_VERSION,
+        event_id: input.eventId,
+        source_fact_fingerprint: sourceFactFingerprint,
+        snapshot_fingerprint: snapshotFingerprint,
+        subject_set_fingerprint: subjectSetFingerprint,
+    });
+    return {
+        source_fact_fingerprint: sourceFactFingerprint,
+        subject_set_fingerprint: subjectSetFingerprint,
+        snapshot_fingerprint: snapshotFingerprint,
+        projection_fingerprint: projectionFingerprint,
+    };
+}
+export function parseFutureSignupLifecycleProjectionJson(body) {
+    let value;
+    try {
+        value = JSON.parse(body);
+    }
+    catch {
+        invalid("$", "must be valid JSON");
+    }
+    return normalizeFutureSignupLifecycleProjectionEnvelope(value);
+}
+/** Validate shipped v1 and derive the closed destination view. No writes or sends. */
+export function normalizeFutureSignupLifecycleProjectionEnvelope(value) {
+    const root = exactRecord(value, "$", [
+        "contract_version",
+        "event_id",
+        "event_type",
+        "fact_id",
+        "fact_revision",
+        "occurred_at",
+        "provider",
+        "provider_event_id",
+        "upstream",
+        "source_fact",
+        "snapshot",
+        "activity",
+        "producer",
+        "validation",
+    ]);
+    literal(root.contract_version, FUTURE_SIGNUP_LIFECYCLE_PROJECTION_CONTRACT_VERSION, "$.contract_version");
+    literal(root.event_type, "lifecycle_projection", "$.event_type");
+    literal(root.provider, "oxygen", "$.provider");
+    const eventId = canonicalText(root.event_id, "$.event_id");
+    const factId = canonicalText(root.fact_id, "$.fact_id");
+    const factRevision = positiveInteger(root.fact_revision, "$.fact_revision");
+    const occurredAt = timestamp(root.occurred_at, "$.occurred_at");
+    const providerEventId = canonicalText(root.provider_event_id, "$.provider_event_id");
+    const upstreamRaw = exactRecord(root.upstream, "$.upstream", [
+        "provider",
+        "provider_event_id",
+        "source_revision",
+    ]);
+    const upstream = {
+        provider: enumValue(upstreamRaw.provider, ["clerk", "clerk_org_deletion", "stripe"], "$.upstream.provider"),
+        provider_event_id: canonicalText(upstreamRaw.provider_event_id, "$.upstream.provider_event_id"),
+        source_revision: positiveInteger(upstreamRaw.source_revision, "$.upstream.source_revision"),
+    };
+    const sourceFact = parseSourceFact(root.source_fact);
+    const snapshot = parseSnapshot(root.snapshot);
+    const activity = parseShippedActivity(root.activity);
+    const producerRaw = exactRecord(root.producer, "$.producer", [
+        "environment",
+        "version",
+        "commitSha",
+    ]);
+    const producer = {
+        environment: enumValue(producerRaw.environment, ["dev", "production"], "$.producer.environment"),
+        version: canonicalText(producerRaw.version, "$.producer.version"),
+        commitSha: canonicalText(producerRaw.commitSha, "$.producer.commitSha"),
+    };
+    const validationRaw = exactRecord(root.validation, "$.validation", ["synthetic", "no_send"]);
+    literal(validationRaw.synthetic, false, "$.validation.synthetic");
+    literal(validationRaw.no_send, true, "$.validation.no_send");
+    const expectedProjectionFactId = futureSignupLifecycleProjectionFactId(sourceFact.fact_id);
+    const expectedEventId = futureSignupLifecycleEventId(expectedProjectionFactId, sourceFact.fact_revision);
+    same(factId, expectedProjectionFactId, "$.fact_id", "must match the source fact identity");
+    same(factRevision, sourceFact.fact_revision, "$.fact_revision", "must match source_fact.fact_revision");
+    same(eventId, expectedEventId, "$.event_id", "must match the semantic projection event identity");
+    same(providerEventId, eventId, "$.provider_event_id", "must equal event_id");
+    same(occurredAt, sourceFact.occurred_at, "$.occurred_at", "must match source_fact.occurred_at");
+    same(upstream.provider, sourceFact.source, "$.upstream.provider", "must match source_fact.source");
+    same(upstream.provider_event_id, sourceFact.source_event_id, "$.upstream.provider_event_id", "must match source_fact.source_event_id");
+    same(upstream.source_revision, sourceFact.source_revision, "$.upstream.source_revision", "must match source_fact.source_revision");
+    same(snapshot.causal_clerk_org_id, sourceFact.clerk_org_id, "$.snapshot.causal_clerk_org_id", "must match source_fact.clerk_org_id");
+    assertProjectionClosure(snapshot);
+    assertShippedActivity(activity, sourceFact, snapshot);
+    const snapshotCore = {
+        complete: true,
+        causal_clerk_org_id: snapshot.causal_clerk_org_id,
+        organization_states: snapshot.organization_states,
+        membership_states: snapshot.membership_states,
+        subjects: snapshot.subjects,
+    };
+    const fingerprints = futureSignupLifecycleProjectionFingerprints({
+        eventId,
+        sourceFact,
+        snapshot: snapshotCore,
+    });
+    same(snapshot.subject_set_fingerprint, fingerprints.subject_set_fingerprint, "$.snapshot.subject_set_fingerprint", "does not match the canonical subject set");
+    same(snapshot.snapshot_fingerprint, fingerprints.snapshot_fingerprint, "$.snapshot.snapshot_fingerprint", "does not match the canonical shipped-v1 snapshot");
+    const envelope = {
+        contract_version: FUTURE_SIGNUP_LIFECYCLE_PROJECTION_CONTRACT_VERSION,
+        event_id: eventId,
+        event_type: "lifecycle_projection",
+        fact_id: factId,
+        fact_revision: factRevision,
+        occurred_at: occurredAt,
+        provider: "oxygen",
+        provider_event_id: providerEventId,
+        upstream,
+        source_fact: sourceFact,
+        snapshot,
+        activity,
+        producer,
+        validation: { synthetic: false, no_send: true },
+    };
+    const normalizedSubjects = normalizeSubjects(snapshot, sourceFact);
+    const normalizedActivity = normalizeActivity(activity, sourceFact, normalizedSubjects);
+    return {
+        envelope,
+        projection: {
+            contract_version: FUTURE_SIGNUP_LIFECYCLE_PROJECTION_CONTRACT_VERSION,
+            authority: FUTURE_SIGNUP_LIFECYCLE_PROJECTION_AUTHORITY,
+            event_id: eventId,
+            occurred_at: occurredAt,
+            source_fact: sourceFact,
+            snapshot: {
+                complete: true,
+                causal_clerk_org_id: snapshot.causal_clerk_org_id,
+                subjects: normalizedSubjects,
+            },
+            activity: normalizedActivity,
+            validation: { synthetic: false, no_send: true },
+        },
+        fingerprints,
+        idempotency_keys: {
+            delivery_receipt: eventId,
+            activity: normalizedActivity.emit ? eventId : null,
+            subjects: normalizedSubjects.map((subject) => ({
+                kind: subject.kind,
+                key: subject.key,
+                idempotency_key: `${eventId}:subject:${subject.kind}:${subject.key}`,
+            })),
+        },
+    };
+}
+export function normalizeFutureSignupLifecycleProjectionDestinationApplyOptions(value) {
+    const root = exactRecord(value, "$", [
+        "objects",
+        "stage_tokens",
+        "owner_if_blank",
+        "activity_policy",
+    ]);
+    const objectsRaw = exactRecord(root.objects, "$.objects", ["people", "companies"]);
+    literal(objectsRaw.people, "people", "$.objects.people");
+    literal(objectsRaw.companies, "companies", "$.objects.companies");
+    const stagesRaw = exactRecord(root.stage_tokens, "$.stage_tokens", ["people", "companies"]);
+    const peopleStages = parseStageMapping(stagesRaw.people, "$.stage_tokens.people");
+    const companyStages = parseStageMapping(stagesRaw.companies, "$.stage_tokens.companies");
+    let owner = null;
+    if (root.owner_if_blank !== null) {
+        const ownerRaw = exactRecord(root.owner_if_blank, "$.owner_if_blank", ["workspace_user_id"]);
+        owner = {
+            workspace_user_id: canonicalUuid(ownerRaw.workspace_user_id, "$.owner_if_blank.workspace_user_id"),
+        };
+    }
+    const policyRaw = exactRecord(root.activity_policy, "$.activity_policy", [
+        "customer_lifecycle_facts",
+        "projection_refreshed",
+        "subscription_ended",
+        "participants",
+        "idempotency",
+    ]);
+    literal(policyRaw.customer_lifecycle_facts, "emit_envelope_activity", "$.activity_policy.customer_lifecycle_facts");
+    literal(policyRaw.projection_refreshed, "suppress", "$.activity_policy.projection_refreshed");
+    literal(policyRaw.subscription_ended, "suppress", "$.activity_policy.subscription_ended");
+    literal(policyRaw.participants, "envelope_subjects_only", "$.activity_policy.participants");
+    literal(policyRaw.idempotency, "event_id", "$.activity_policy.idempotency");
+    const applyOptions = {
+        objects: { people: "people", companies: "companies" },
+        stage_tokens: { people: peopleStages, companies: companyStages },
+        owner_if_blank: owner,
+        activity_policy: {
+            customer_lifecycle_facts: "emit_envelope_activity",
+            projection_refreshed: "suppress",
+            subscription_ended: "suppress",
+            participants: "envelope_subjects_only",
+            idempotency: "event_id",
+        },
+    };
+    return {
+        apply_options: applyOptions,
+        apply_options_fingerprint: sha256Canonical(applyOptions),
+    };
+}
+function parseSourceFact(value) {
+    const path = "$.source_fact";
+    const row = exactRecord(value, path, [
+        "fact_id",
+        "fact_revision",
+        "contract_version",
+        "fact_type",
+        "clerk_org_id",
+        "occurred_at",
+        "source",
+        "source_event_id",
+        "source_revision",
+        "stripe_customer_id",
+        "stripe_subscription_id",
+        "stripe_invoice_id",
+        "stripe_period_start",
+        "stripe_period_end",
+        "amount_paid_cents",
+        "currency",
+        "loss_kind",
+        "termination_kind",
+    ]);
+    literal(row.contract_version, FUTURE_SIGNUP_LIFECYCLE_CONTRACT_VERSION, `${path}.contract_version`);
+    const fact = {
+        fact_id: canonicalText(row.fact_id, `${path}.fact_id`),
+        fact_revision: positiveInteger(row.fact_revision, `${path}.fact_revision`),
+        contract_version: FUTURE_SIGNUP_LIFECYCLE_CONTRACT_VERSION,
+        fact_type: enumValue(row.fact_type, FUTURE_SIGNUP_LIFECYCLE_PROJECTION_FACT_TYPES, `${path}.fact_type`),
+        clerk_org_id: canonicalText(row.clerk_org_id, `${path}.clerk_org_id`),
+        occurred_at: timestamp(row.occurred_at, `${path}.occurred_at`),
+        source: enumValue(row.source, ["clerk", "clerk_org_deletion", "stripe"], `${path}.source`),
+        source_event_id: canonicalText(row.source_event_id, `${path}.source_event_id`),
+        source_revision: positiveInteger(row.source_revision, `${path}.source_revision`),
+        stripe_customer_id: nullableText(row.stripe_customer_id, `${path}.stripe_customer_id`),
+        stripe_subscription_id: nullableText(row.stripe_subscription_id, `${path}.stripe_subscription_id`),
+        stripe_invoice_id: nullableText(row.stripe_invoice_id, `${path}.stripe_invoice_id`),
+        stripe_period_start: nullableTimestamp(row.stripe_period_start, `${path}.stripe_period_start`),
+        stripe_period_end: nullableTimestamp(row.stripe_period_end, `${path}.stripe_period_end`),
+        amount_paid_cents: nullableNonNegativeInteger(row.amount_paid_cents, `${path}.amount_paid_cents`),
+        currency: nullableCurrency(row.currency, `${path}.currency`),
+        loss_kind: nullableEnum(row.loss_kind, ["paid_churn", "trial_non_conversion"], `${path}.loss_kind`),
+        termination_kind: nullableEnum(row.termination_kind, ["replaced", "duplicate", "unqualified"], `${path}.termination_kind`),
+    };
+    assertSourceFactShape(fact);
+    return fact;
+}
+function assertSourceFactShape(fact) {
+    const path = "$.source_fact";
+    if (fact.fact_type === "trial_started") {
+        same(fact.source, "stripe", `${path}.source`, "must be stripe for trial_started");
+        present(fact.stripe_customer_id, `${path}.stripe_customer_id`);
+        present(fact.stripe_subscription_id, `${path}.stripe_subscription_id`);
+        allNull(fact, [
+            "stripe_invoice_id",
+            "stripe_period_start",
+            "stripe_period_end",
+            "amount_paid_cents",
+            "currency",
+            "loss_kind",
+            "termination_kind",
+        ], path);
+        same(fact.fact_id, futureSignupTrialStartedFactId(fact.stripe_subscription_id), `${path}.fact_id`, "must match the immutable Trial entry edge");
+        return;
+    }
+    if (fact.fact_type === "paid") {
+        same(fact.source, "stripe", `${path}.source`, "must be stripe for paid");
+        present(fact.stripe_customer_id, `${path}.stripe_customer_id`);
+        present(fact.stripe_subscription_id, `${path}.stripe_subscription_id`);
+        present(fact.stripe_invoice_id, `${path}.stripe_invoice_id`);
+        present(fact.stripe_period_start, `${path}.stripe_period_start`);
+        present(fact.stripe_period_end, `${path}.stripe_period_end`);
+        if (Date.parse(fact.stripe_period_end) <= Date.parse(fact.stripe_period_start)) {
+            invalid(`${path}.stripe_period_end`, "must be later than stripe_period_start");
+        }
+        if (fact.amount_paid_cents === null || fact.amount_paid_cents <= 0) {
+            invalid(`${path}.amount_paid_cents`, "must be a strict positive-payment witness");
+        }
+        present(fact.currency, `${path}.currency`);
+        allNull(fact, ["loss_kind", "termination_kind"], path);
+        same(fact.fact_id, futureSignupPaidFactId(fact.stripe_invoice_id), `${path}.fact_id`, "must match the immutable Paid invoice identity");
+        return;
+    }
+    if (fact.fact_type === "lost") {
+        if (fact.source !== "stripe" && fact.source !== "clerk_org_deletion") {
+            invalid(`${path}.source`, "must be stripe or clerk_org_deletion for lost");
+        }
+        present(fact.stripe_subscription_id, `${path}.stripe_subscription_id`);
+        present(fact.loss_kind, `${path}.loss_kind`);
+        allNull(fact, [
+            "stripe_invoice_id",
+            "stripe_period_start",
+            "stripe_period_end",
+            "amount_paid_cents",
+            "currency",
+            "termination_kind",
+        ], path);
+        same(fact.fact_id, futureSignupLostFactId(fact.stripe_subscription_id, fact.loss_kind), `${path}.fact_id`, "must match the classified Lost identity");
+        return;
+    }
+    if (fact.fact_type === "subscription_ended") {
+        if (fact.source !== "stripe" && fact.source !== "clerk_org_deletion") {
+            invalid(`${path}.source`, "must be stripe or clerk_org_deletion for subscription_ended");
+        }
+        present(fact.stripe_subscription_id, `${path}.stripe_subscription_id`);
+        present(fact.termination_kind, `${path}.termination_kind`);
+        allNull(fact, [
+            "stripe_invoice_id",
+            "stripe_period_start",
+            "stripe_period_end",
+            "amount_paid_cents",
+            "currency",
+            "loss_kind",
+        ], path);
+        same(fact.fact_id, futureSignupSubscriptionEndedFactId(fact.stripe_subscription_id, fact.termination_kind), `${path}.fact_id`, "must match the neutral subscription edge");
+        return;
+    }
+    allNull(fact, [
+        "stripe_customer_id",
+        "stripe_subscription_id",
+        "stripe_invoice_id",
+        "stripe_period_start",
+        "stripe_period_end",
+        "amount_paid_cents",
+        "currency",
+        "loss_kind",
+        "termination_kind",
+    ], path);
+    same(fact.source, "clerk", `${path}.source`, `must be clerk for ${fact.fact_type}`);
+    const expected = fact.fact_type === "workspace_deleted"
+        ? futureSignupWorkspaceDeletedFactId(fact.clerk_org_id)
+        : futureSignupLifecycleProjectionRefreshFactId(fact.clerk_org_id, fact.source_event_id);
+    same(fact.fact_id, expected, `${path}.fact_id`, "must match the immutable Clerk cause");
+}
+function parseSnapshot(value) {
+    const path = "$.snapshot";
+    const row = exactRecord(value, path, [
+        "complete",
+        "causal_clerk_org_id",
+        "organization_states",
+        "membership_states",
+        "subjects",
+        "subject_set_fingerprint",
+        "snapshot_fingerprint",
+    ]);
+    literal(row.complete, true, `${path}.complete`);
+    if (!Array.isArray(row.organization_states))
+        invalid(`${path}.organization_states`, "must be an array");
+    if (!Array.isArray(row.membership_states))
+        invalid(`${path}.membership_states`, "must be an array");
+    if (!Array.isArray(row.subjects))
+        invalid(`${path}.subjects`, "must be an array");
+    const organizations = row.organization_states.map((item, index) => parseOrganizationState(item, `${path}.organization_states[${index}]`));
+    assertSortedUnique(organizations, (item) => item.clerk_org_id, `${path}.organization_states`);
+    const memberships = row.membership_states.map((item, index) => parseMembershipState(item, `${path}.membership_states[${index}]`));
+    assertSortedUnique(memberships, (item) => `${item.clerk_user_id}\u0000${item.clerk_org_id}\u0000${item.clerk_membership_id}`, `${path}.membership_states`);
+    const subjects = row.subjects.map((item, index) => parseSubject(item, `${path}.subjects[${index}]`));
+    assertSortedUnique(subjects, (item) => `${item.kind}\u0000${item.key}`, `${path}.subjects`);
+    const subjectKeys = subjects.map((subject) => subject.key);
+    if (new Set(subjectKeys).size !== subjectKeys.length) {
+        invalid(`${path}.subjects`, "subject keys must be globally unique");
+    }
+    return {
+        complete: true,
+        causal_clerk_org_id: canonicalText(row.causal_clerk_org_id, `${path}.causal_clerk_org_id`),
+        organization_states: organizations,
+        membership_states: memberships,
+        subjects,
+        subject_set_fingerprint: fingerprint(row.subject_set_fingerprint, `${path}.subject_set_fingerprint`),
+        snapshot_fingerprint: fingerprint(row.snapshot_fingerprint, `${path}.snapshot_fingerprint`),
+    };
+}
+function parseOrganizationState(value, path) {
+    const row = exactRecord(value, path, [
+        "clerk_org_id",
+        "company_key",
+        "company_key_history",
+        "normalized_domain",
+        "billing_stage",
+        "stage_since",
+        "loss_kind",
+        "winning_fact_id",
+        "winning_fact_revision",
+        "organization_revision",
+        "billing_revision",
+        "state_revision",
+        "membership_set_revision",
+        "members_complete",
+        "state_fingerprint",
+        "membership_set_fingerprint",
+        "workspace_deleted_at",
+        "workspace_deleted_fact_id",
+        "workspace_deleted_fact_revision",
+    ]);
+    if (!Array.isArray(row.company_key_history))
+        invalid(`${path}.company_key_history`, "must be an array");
+    const history = row.company_key_history.map((item, index) => canonicalText(item, `${path}.company_key_history[${index}]`));
+    assertSortedUnique(history, (item) => item, `${path}.company_key_history`);
+    if (typeof row.members_complete !== "boolean")
+        invalid(`${path}.members_complete`, "must be a boolean");
+    const state = {
+        clerk_org_id: canonicalText(row.clerk_org_id, `${path}.clerk_org_id`),
+        company_key: canonicalText(row.company_key, `${path}.company_key`),
+        company_key_history: history,
+        normalized_domain: nullableDomain(row.normalized_domain, `${path}.normalized_domain`),
+        billing_stage: nullableEnum(row.billing_stage, FUTURE_SIGNUP_LIFECYCLE_PROJECTION_BILLING_STAGES, `${path}.billing_stage`),
+        stage_since: nullableTimestamp(row.stage_since, `${path}.stage_since`),
+        loss_kind: nullableEnum(row.loss_kind, ["paid_churn", "trial_non_conversion"], `${path}.loss_kind`),
+        winning_fact_id: nullableText(row.winning_fact_id, `${path}.winning_fact_id`),
+        winning_fact_revision: nullablePositiveInteger(row.winning_fact_revision, `${path}.winning_fact_revision`),
+        organization_revision: positiveInteger(row.organization_revision, `${path}.organization_revision`),
+        billing_revision: positiveInteger(row.billing_revision, `${path}.billing_revision`),
+        state_revision: positiveInteger(row.state_revision, `${path}.state_revision`),
+        membership_set_revision: nonNegativeInteger(row.membership_set_revision, `${path}.membership_set_revision`),
+        members_complete: row.members_complete,
+        state_fingerprint: fingerprint(row.state_fingerprint, `${path}.state_fingerprint`),
+        membership_set_fingerprint: fingerprint(row.membership_set_fingerprint, `${path}.membership_set_fingerprint`),
+        workspace_deleted_at: nullableTimestamp(row.workspace_deleted_at, `${path}.workspace_deleted_at`),
+        workspace_deleted_fact_id: nullableText(row.workspace_deleted_fact_id, `${path}.workspace_deleted_fact_id`),
+        workspace_deleted_fact_revision: nullablePositiveInteger(row.workspace_deleted_fact_revision, `${path}.workspace_deleted_fact_revision`),
+    };
+    const expectedCompanyKey = state.normalized_domain
+        ? `domain:${state.normalized_domain}`
+        : `clerk_org:${state.clerk_org_id}`;
+    same(state.company_key, expectedCompanyKey, `${path}.company_key`, "must match canonical organization identity");
+    assertBillingShape(state, path);
+    if ((state.workspace_deleted_at === null) !== (state.workspace_deleted_fact_id === null)
+        || (state.workspace_deleted_at === null) !== (state.workspace_deleted_fact_revision === null)) {
+        invalid(path, "workspace deletion evidence must be complete or entirely null");
+    }
+    return state;
+}
+function parseMembershipState(value, path) {
+    const row = exactRecord(value, path, [
+        "clerk_membership_id",
+        "journey_id",
+        "clerk_user_id",
+        "clerk_org_id",
+        "role",
+        "is_creator",
+        "contributes_to_lifecycle",
+        "membership_created_at",
+        "membership_revision",
+        "state_fingerprint",
+        "removed_at",
+        "removed_reason",
+    ]);
+    if (typeof row.is_creator !== "boolean")
+        invalid(`${path}.is_creator`, "must be a boolean");
+    if (typeof row.contributes_to_lifecycle !== "boolean") {
+        invalid(`${path}.contributes_to_lifecycle`, "must be a boolean");
+    }
+    const state = {
+        clerk_membership_id: canonicalText(row.clerk_membership_id, `${path}.clerk_membership_id`),
+        journey_id: nullableText(row.journey_id, `${path}.journey_id`),
+        clerk_user_id: canonicalText(row.clerk_user_id, `${path}.clerk_user_id`),
+        clerk_org_id: canonicalText(row.clerk_org_id, `${path}.clerk_org_id`),
+        role: canonicalText(row.role, `${path}.role`),
+        is_creator: row.is_creator,
+        contributes_to_lifecycle: row.contributes_to_lifecycle,
+        membership_created_at: timestamp(row.membership_created_at, `${path}.membership_created_at`),
+        membership_revision: positiveInteger(row.membership_revision, `${path}.membership_revision`),
+        state_fingerprint: fingerprint(row.state_fingerprint, `${path}.state_fingerprint`),
+        removed_at: nullableTimestamp(row.removed_at, `${path}.removed_at`),
+        removed_reason: nullableEnum(row.removed_reason, ["member_removed", "user_deleted", "workspace_deleted"], `${path}.removed_reason`),
+    };
+    if ((state.removed_at === null) !== (state.removed_reason === null)) {
+        invalid(path, "removed_at and removed_reason must be complete or entirely null");
+    }
+    if (state.removed_at && Date.parse(state.removed_at) < Date.parse(state.membership_created_at)) {
+        invalid(`${path}.removed_at`, "cannot predate membership_created_at");
+    }
+    if (state.journey_id !== null) {
+        same(state.journey_id, futureSignupJourneyId(state.clerk_user_id), `${path}.journey_id`, "must match the retained Clerk user journey");
+    }
+    const expectedContribution = state.removed_reason === null
+        || state.removed_reason === "workspace_deleted";
+    if (state.contributes_to_lifecycle !== expectedContribution) {
+        invalid(`${path}.contributes_to_lifecycle`, "does not match terminal membership policy");
+    }
+    return state;
+}
+function parseSubject(value, path) {
+    const row = exactRecord(value, path, [
+        "kind",
+        "key",
+        "billing_stage",
+        "stage_since",
+        "aggregate_revision",
+        "aggregate_fingerprint",
+        "winning_clerk_org_id",
+        "winning_fact_id",
+        "winning_fact_revision",
+        "source_state_revision",
+        "membership_set_revision",
+        "members_complete",
+        "projection_action",
+        "replacement_company_key",
+        "departed_clerk_org_ids",
+        "oxygen_product_lifecycle",
+        "external_identities",
+        "natural_identity",
+        "display",
+        "represented_clerk_org_ids",
+        "represented_company_keys",
+        "membership_ids",
+        "membership_contributors",
+    ]);
+    if (!Array.isArray(row.departed_clerk_org_ids))
+        invalid(`${path}.departed_clerk_org_ids`, "must be an array");
+    if (!Array.isArray(row.external_identities))
+        invalid(`${path}.external_identities`, "must be an array");
+    if (!Array.isArray(row.represented_clerk_org_ids))
+        invalid(`${path}.represented_clerk_org_ids`, "must be an array");
+    if (!Array.isArray(row.represented_company_keys))
+        invalid(`${path}.represented_company_keys`, "must be an array");
+    if (!Array.isArray(row.membership_ids))
+        invalid(`${path}.membership_ids`, "must be an array");
+    if (!Array.isArray(row.membership_contributors))
+        invalid(`${path}.membership_contributors`, "must be an array");
+    literal(row.members_complete, true, `${path}.members_complete`);
+    const aggregateRevision = positiveInteger(row.aggregate_revision, `${path}.aggregate_revision`);
+    const aggregateFingerprint = fingerprint(row.aggregate_fingerprint, `${path}.aggregate_fingerprint`);
+    const lifecycleRaw = exactRecord(row.oxygen_product_lifecycle, `${path}.oxygen_product_lifecycle`, [
+        "revision",
+        "fingerprint",
+    ]);
+    const lifecycle = {
+        revision: positiveInteger(lifecycleRaw.revision, `${path}.oxygen_product_lifecycle.revision`),
+        fingerprint: fingerprint(lifecycleRaw.fingerprint, `${path}.oxygen_product_lifecycle.fingerprint`),
+    };
+    same(lifecycle.revision, aggregateRevision, `${path}.oxygen_product_lifecycle.revision`, "must equal aggregate_revision");
+    same(lifecycle.fingerprint, aggregateFingerprint, `${path}.oxygen_product_lifecycle.fingerprint`, "must equal aggregate_fingerprint");
+    const identities = row.external_identities.map((item, index) => {
+        const identityPath = `${path}.external_identities[${index}]`;
+        const identity = exactRecord(item, identityPath, ["provider", "object", "id"]);
+        literal(identity.provider, "clerk", `${identityPath}.provider`);
+        return {
+            provider: "clerk",
+            object: enumValue(identity.object, ["user", "organization"], `${identityPath}.object`),
+            id: canonicalText(identity.id, `${identityPath}.id`),
+        };
+    });
+    assertSortedUnique(identities, (item) => `${item.object}\u0000${item.id}`, `${path}.external_identities`);
+    const naturalRaw = exactRecord(row.natural_identity, `${path}.natural_identity`, ["email", "domain"]);
+    const naturalIdentity = {
+        email: nullableEmail(naturalRaw.email, `${path}.natural_identity.email`),
+        domain: nullableDomain(naturalRaw.domain, `${path}.natural_identity.domain`),
+    };
+    const displayRaw = exactRecord(row.display, `${path}.display`, [
+        "first_name",
+        "last_name",
+        "company_name",
+    ]);
+    const display = {
+        first_name: nullableDisplayText(displayRaw.first_name, `${path}.display.first_name`),
+        last_name: nullableDisplayText(displayRaw.last_name, `${path}.display.last_name`),
+        company_name: nullableDisplayText(displayRaw.company_name, `${path}.display.company_name`),
+    };
+    const stringArray = (raw, field) => {
+        const values = raw.map((item, index) => canonicalText(item, `${path}.${field}[${index}]`));
+        assertSortedUnique(values, (item) => item, `${path}.${field}`);
+        return values;
+    };
+    const contributors = row.membership_contributors.map((item, index) => parseContributor(item, `${path}.membership_contributors[${index}]`));
+    assertSortedUnique(contributors, (item) => `${item.clerk_org_id}\u0000${item.clerk_membership_id}`, `${path}.membership_contributors`);
+    const subject = {
+        kind: enumValue(row.kind, ["company", "person"], `${path}.kind`),
+        key: canonicalText(row.key, `${path}.key`),
+        billing_stage: nullableEnum(row.billing_stage, FUTURE_SIGNUP_LIFECYCLE_PROJECTION_BILLING_STAGES, `${path}.billing_stage`),
+        stage_since: nullableTimestamp(row.stage_since, `${path}.stage_since`),
+        aggregate_revision: aggregateRevision,
+        aggregate_fingerprint: aggregateFingerprint,
+        winning_clerk_org_id: nullableText(row.winning_clerk_org_id, `${path}.winning_clerk_org_id`),
+        winning_fact_id: nullableText(row.winning_fact_id, `${path}.winning_fact_id`),
+        winning_fact_revision: nullablePositiveInteger(row.winning_fact_revision, `${path}.winning_fact_revision`),
+        source_state_revision: positiveInteger(row.source_state_revision, `${path}.source_state_revision`),
+        membership_set_revision: nonNegativeInteger(row.membership_set_revision, `${path}.membership_set_revision`),
+        members_complete: true,
+        projection_action: enumValue(row.projection_action, ["upsert", "neutralize"], `${path}.projection_action`),
+        replacement_company_key: nullableText(row.replacement_company_key, `${path}.replacement_company_key`),
+        departed_clerk_org_ids: stringArray(row.departed_clerk_org_ids, "departed_clerk_org_ids"),
+        oxygen_product_lifecycle: lifecycle,
+        external_identities: identities,
+        natural_identity: naturalIdentity,
+        display,
+        represented_clerk_org_ids: stringArray(row.represented_clerk_org_ids, "represented_clerk_org_ids"),
+        represented_company_keys: stringArray(row.represented_company_keys, "represented_company_keys"),
+        membership_ids: stringArray(row.membership_ids, "membership_ids"),
+        membership_contributors: contributors,
+    };
+    assertSubjectShape(subject, path);
+    return subject;
+}
+function parseContributor(value, path) {
+    const row = exactRecord(value, path, [
+        "clerk_membership_id",
+        "clerk_org_id",
+        "role",
+        "is_creator",
+        "active",
+        "removed_reason",
+    ]);
+    if (typeof row.is_creator !== "boolean")
+        invalid(`${path}.is_creator`, "must be a boolean");
+    if (typeof row.active !== "boolean")
+        invalid(`${path}.active`, "must be a boolean");
+    const removedReason = nullableEnum(row.removed_reason, ["member_removed", "user_deleted", "workspace_deleted"], `${path}.removed_reason`);
+    if (row.active !== (removedReason === null)) {
+        invalid(path, "active and removed_reason must describe the same terminal state");
+    }
+    return {
+        clerk_membership_id: canonicalText(row.clerk_membership_id, `${path}.clerk_membership_id`),
+        clerk_org_id: canonicalText(row.clerk_org_id, `${path}.clerk_org_id`),
+        role: canonicalText(row.role, `${path}.role`),
+        is_creator: row.is_creator,
+        active: row.active,
+        removed_reason: removedReason,
+    };
+}
+function assertSubjectShape(// skipcq: JS-R1005 -- closed discriminated-union validator keeps Person/Company identity rules auditable together.
+subject, path) {
+    assertBillingShape(subject, path);
+    const userIds = subject.external_identities
+        .filter((item) => item.object === "user")
+        .map((item) => item.id);
+    const organizationIds = subject.external_identities
+        .filter((item) => item.object === "organization")
+        .map((item) => item.id);
+    if (subject.kind === "person") {
+        if (subject.projection_action !== "upsert")
+            invalid(`${path}.projection_action`, "Person subjects can only be upserted");
+        if (userIds.length !== 1 || organizationIds.length !== 0) {
+            invalid(`${path}.external_identities`, "a Person requires exactly one Clerk user identity");
+        }
+        same(subject.key, `clerk_user:${userIds[0]}`, `${path}.key`, "must derive from the exact Clerk user identity");
+        if (subject.natural_identity.domain !== null || subject.display.company_name !== null) {
+            invalid(path, "Person domain and company_name must be null");
+        }
+        if (subject.replacement_company_key !== null || subject.departed_clerk_org_ids.length !== 0) {
+            invalid(path, "a Person cannot carry Company rekey departure fields");
+        }
+        if (subject.membership_contributors.length === 0) {
+            invalid(`${path}.membership_contributors`, "a Person requires retained membership evidence");
+        }
+        const contributorMembershipIds = subject.membership_contributors
+            .map((item) => item.clerk_membership_id)
+            .sort(codeUnitCompare);
+        sameJson(subject.membership_ids, contributorMembershipIds, `${path}.membership_ids`, "must match membership contributors");
+        const contributorOrgIds = uniqueSorted(subject.membership_contributors.map((item) => item.clerk_org_id));
+        sameJson(subject.represented_clerk_org_ids, contributorOrgIds, `${path}.represented_clerk_org_ids`, "must match membership contributors");
+        return;
+    }
+    if (userIds.length !== 0 || subject.natural_identity.email !== null) {
+        invalid(path, "Company subjects cannot contain Person identities");
+    }
+    if (subject.display.first_name !== null || subject.display.last_name !== null) {
+        invalid(`${path}.display`, "Company first_name and last_name must be null");
+    }
+    if (subject.membership_ids.length !== 0 || subject.membership_contributors.length !== 0) {
+        invalid(path, "Company membership evidence belongs on Person subjects");
+    }
+    sameJson(organizationIds, subject.represented_clerk_org_ids, `${path}.external_identities`, "Clerk organization identities must match represented_clerk_org_ids");
+    sameJson(subject.represented_company_keys, [subject.key], `${path}.represented_company_keys`, "must contain only the subject key");
+    if (subject.projection_action === "neutralize") {
+        if (organizationIds.length !== 0) {
+            invalid(path, "a neutralized Company cannot assert Clerk organization identities");
+        }
+        if (subject.replacement_company_key === null || subject.departed_clerk_org_ids.length === 0) {
+            invalid(path, "a neutralized Company requires an explicit replacement and departure");
+        }
+        if (subject.billing_stage !== null)
+            invalid(`${path}.billing_stage`, "must be null when neutralized");
+        if (subject.key.startsWith("domain:")) {
+            same(subject.natural_identity.domain, subject.key.slice("domain:".length), `${path}.natural_identity.domain`, "must preserve the historical domain as lookup-only identity");
+        }
+        else if (subject.natural_identity.domain !== null) {
+            invalid(`${path}.natural_identity.domain`, "must be null for a domainless Company key");
+        }
+        return;
+    }
+    if (organizationIds.length === 0) {
+        invalid(`${path}.external_identities`, "an upserted Company requires a Clerk organization identity");
+    }
+    const expectedKey = subject.natural_identity.domain
+        ? `domain:${subject.natural_identity.domain}`
+        : organizationIds.length === 1
+            ? `clerk_org:${organizationIds[0]}`
+            : null;
+    if (expectedKey === null) {
+        invalid(`${path}.external_identities`, "a domainless Company can represent exactly one Clerk organization");
+    }
+    same(subject.key, expectedKey, `${path}.key`, "must derive from canonical Company identity");
+}
+function assertProjectionClosure(// skipcq: JS-R1005 -- one closure pass verifies cross-linked organizations, memberships, subjects, winners, and creator evidence.
+snapshot) {
+    const organizationById = new Map(snapshot.organization_states.map((item) => [item.clerk_org_id, item]));
+    const membershipById = new Map(snapshot.membership_states.map((item) => [item.clerk_membership_id, item]));
+    if (membershipById.size !== snapshot.membership_states.length) {
+        invalid("$.snapshot.membership_states", "Clerk membership IDs must be globally unique");
+    }
+    if (snapshot.organization_states.some((item) => !item.members_complete)) {
+        invalid("$.snapshot.organization_states", "a complete projection requires members_complete=true");
+    }
+    if (!organizationById.has(snapshot.causal_clerk_org_id)) {
+        invalid("$.snapshot.organization_states", "must include causal_clerk_org_id");
+    }
+    const companies = snapshot.subjects.filter((subject) => subject.kind === "company");
+    const current = companies.filter((subject) => subject.projection_action === "upsert"
+        && subject.represented_clerk_org_ids.includes(snapshot.causal_clerk_org_id)
+        && subject.replacement_company_key === null
+        && subject.departed_clerk_org_ids.length === 0);
+    if (current.length !== 1) {
+        invalid("$.snapshot.subjects", "must contain exactly one current Company for causal_clerk_org_id");
+    }
+    const currentCompany = current[0];
+    if (!currentCompany) {
+        invalid("$.snapshot.subjects", "must contain a current Company for causal_clerk_org_id");
+    }
+    for (const [index, subject] of snapshot.subjects.entries()) {
+        const path = `$.snapshot.subjects[${index}]`;
+        if (subject.kind === "company") {
+            for (const clerkOrgId of subject.represented_clerk_org_ids) {
+                const organization = organizationById.get(clerkOrgId);
+                if (!organization || organization.company_key !== subject.key) {
+                    invalid(`${path}.represented_clerk_org_ids`, "must match organization_states Company identity");
+                }
+            }
+            const winner = subject.winning_clerk_org_id
+                ? organizationById.get(subject.winning_clerk_org_id)
+                : undefined;
+            if (subject.winning_clerk_org_id && !winner) {
+                invalid(`${path}.winning_clerk_org_id`, "must reference retained organization_states evidence");
+            }
+            if (winner) {
+                if (!subject.represented_clerk_org_ids.includes(winner.clerk_org_id)) {
+                    invalid(`${path}.winning_clerk_org_id`, "must be represented by this Company");
+                }
+                same(subject.billing_stage, winner.billing_stage, `${path}.billing_stage`, "must match the winning organization");
+                same(subject.stage_since, winner.stage_since, `${path}.stage_since`, "must match the winning organization");
+                same(subject.winning_fact_id, winner.winning_fact_id, `${path}.winning_fact_id`, "must match the winning organization");
+                same(subject.winning_fact_revision, winner.winning_fact_revision, `${path}.winning_fact_revision`, "must match the winning organization");
+            }
+            if (subject !== currentCompany) {
+                same(subject.replacement_company_key, currentCompany.key, `${path}.replacement_company_key`, "historical Companies must explicitly depart to the current Company");
+                sameJson(subject.departed_clerk_org_ids, [snapshot.causal_clerk_org_id], `${path}.departed_clerk_org_ids`, "must contain exactly the causal Clerk organization");
+                if (subject.represented_clerk_org_ids.includes(snapshot.causal_clerk_org_id)) {
+                    invalid(`${path}.represented_clerk_org_ids`, "a departed Company cannot retain the causal Clerk identity");
+                }
+            }
+            continue;
+        }
+        if (!subject.membership_contributors.some((item) => item.clerk_org_id === snapshot.causal_clerk_org_id)) {
+            invalid(`${path}.membership_contributors`, "each affected Person requires causal membership evidence");
+        }
+        const clerkUserId = subject.key.slice("clerk_user:".length);
+        for (const contributor of subject.membership_contributors) {
+            const membership = membershipById.get(contributor.clerk_membership_id);
+            if (!membership
+                || membership.clerk_user_id !== clerkUserId
+                || membership.clerk_org_id !== contributor.clerk_org_id
+                || membership.role !== contributor.role
+                || membership.is_creator !== contributor.is_creator
+                || (membership.removed_at === null) !== contributor.active
+                || membership.removed_reason !== contributor.removed_reason) {
+                invalid(`${path}.membership_contributors`, "must match retained membership_states evidence");
+            }
+        }
+        const contributorCompanyKeys = uniqueSorted(subject.membership_contributors.map((item) => {
+            const organization = organizationById.get(item.clerk_org_id);
+            if (!organization) {
+                invalid(`${path}.membership_contributors`, "must reference retained organization_states evidence");
+            }
+            return organization.company_key;
+        }));
+        sameJson(subject.represented_company_keys, contributorCompanyKeys, `${path}.represented_company_keys`, "must match retained organization identity evidence");
+        const winner = subject.winning_clerk_org_id
+            ? organizationById.get(subject.winning_clerk_org_id)
+            : undefined;
+        if (subject.winning_clerk_org_id && !winner) {
+            invalid(`${path}.winning_clerk_org_id`, "must reference retained organization_states evidence");
+        }
+        if (winner) {
+            if (!subject.membership_contributors.some((item) => item.clerk_org_id === winner.clerk_org_id)) {
+                invalid(`${path}.winning_clerk_org_id`, "must be represented by Person membership evidence");
+            }
+            same(subject.billing_stage, winner.billing_stage, `${path}.billing_stage`, "must match the winning organization");
+            same(subject.stage_since, winner.stage_since, `${path}.stage_since`, "must match the winning organization");
+            same(subject.winning_fact_id, winner.winning_fact_id, `${path}.winning_fact_id`, "must match the winning organization");
+            same(subject.winning_fact_revision, winner.winning_fact_revision, `${path}.winning_fact_revision`, "must match the winning organization");
+        }
+    }
+}
+function parseShippedActivity(value) {
+    const path = "$.activity";
+    const row = exactRecord(value, path, [
+        "type",
+        "source_provider",
+        "provider_event_id",
+        "occurred_at",
+        "summary",
+        "subject_keys",
+        "metadata",
+    ]);
+    literal(row.source_provider, FUTURE_SIGNUP_LIFECYCLE_PROJECTION_AUTHORITY, `${path}.source_provider`);
+    if (!Array.isArray(row.subject_keys))
+        invalid(`${path}.subject_keys`, "must be an array");
+    const subjectKeys = row.subject_keys.map((item, index) => canonicalText(item, `${path}.subject_keys[${index}]`));
+    assertSortedUnique(subjectKeys, (item) => item, `${path}.subject_keys`);
+    const metadataRaw = exactRecord(row.metadata, `${path}.metadata`, [
+        "source_fact_id",
+        "source_fact_revision",
+        "causal_clerk_org_id",
+        "loss_kind",
+        "termination_kind",
+    ]);
+    return {
+        type: enumValue(row.type, [...FUTURE_SIGNUP_LIFECYCLE_PROJECTION_ACTIVITY_TYPES, "note"], `${path}.type`),
+        source_provider: FUTURE_SIGNUP_LIFECYCLE_PROJECTION_AUTHORITY,
+        provider_event_id: canonicalText(row.provider_event_id, `${path}.provider_event_id`),
+        occurred_at: timestamp(row.occurred_at, `${path}.occurred_at`),
+        summary: displayText(row.summary, `${path}.summary`, 500),
+        subject_keys: subjectKeys,
+        metadata: {
+            source_fact_id: canonicalText(metadataRaw.source_fact_id, `${path}.metadata.source_fact_id`),
+            source_fact_revision: positiveInteger(metadataRaw.source_fact_revision, `${path}.metadata.source_fact_revision`),
+            causal_clerk_org_id: canonicalText(metadataRaw.causal_clerk_org_id, `${path}.metadata.causal_clerk_org_id`),
+            loss_kind: nullableEnum(metadataRaw.loss_kind, ["paid_churn", "trial_non_conversion"], `${path}.metadata.loss_kind`),
+            termination_kind: nullableEnum(metadataRaw.termination_kind, ["replaced", "duplicate", "unqualified"], `${path}.metadata.termination_kind`),
+        },
+    };
+}
+function assertShippedActivity(activity, sourceFact, snapshot) {
+    const expectedType = sourceFact.fact_type === "trial_started"
+        ? "trial_started"
+        : sourceFact.fact_type === "paid"
+            ? "plan_paid"
+            : sourceFact.fact_type === "lost"
+                ? "customer_lost"
+                : sourceFact.fact_type === "workspace_deleted"
+                    ? "workspace_deleted"
+                    : "note";
+    same(activity.type, expectedType, "$.activity.type", "does not match source_fact.fact_type");
+    same(activity.provider_event_id, futureSignupLifecycleEventId(futureSignupLifecycleProjectionFactId(sourceFact.fact_id), sourceFact.fact_revision), "$.activity.provider_event_id", "must equal the projection event identity");
+    same(activity.occurred_at, sourceFact.occurred_at, "$.activity.occurred_at", "must match source_fact.occurred_at");
+    same(activity.metadata.source_fact_id, sourceFact.fact_id, "$.activity.metadata.source_fact_id", "must match source_fact.fact_id");
+    same(activity.metadata.source_fact_revision, sourceFact.fact_revision, "$.activity.metadata.source_fact_revision", "must match source_fact.fact_revision");
+    same(activity.metadata.causal_clerk_org_id, sourceFact.clerk_org_id, "$.activity.metadata.causal_clerk_org_id", "must match source_fact.clerk_org_id");
+    same(activity.metadata.loss_kind, sourceFact.loss_kind, "$.activity.metadata.loss_kind", "must match source_fact.loss_kind");
+    same(activity.metadata.termination_kind, sourceFact.termination_kind, "$.activity.metadata.termination_kind", "must match source_fact.termination_kind");
+    const subjects = new Map(snapshot.subjects.map((item) => [item.key, item]));
+    for (const [index, key] of activity.subject_keys.entries()) {
+        const subject = subjects.get(key);
+        if (!subject)
+            invalid(`$.activity.subject_keys[${index}]`, "must reference a snapshot subject");
+        if (subject.projection_action === "neutralize") {
+            invalid(`$.activity.subject_keys[${index}]`, "cannot reference a neutralized subject");
+        }
+    }
+    if (expectedType !== "note" && activity.subject_keys.length === 0) {
+        invalid("$.activity.subject_keys", "customer lifecycle activity requires a participant");
+    }
+}
+function normalizeSubjects(snapshot, sourceFact) {
+    const organizationById = new Map(snapshot.organization_states.map((item) => [item.clerk_org_id, item]));
+    return snapshot.subjects.map((subject) => {
+        const aliases = subject.projection_action === "neutralize"
+            ? []
+            : [
+                ...subject.external_identities.map((identity) => ({
+                    type: identity.object === "user" ? "clerk_user" : "clerk_organization",
+                    value: identity.id,
+                })),
+                ...(subject.natural_identity.email
+                    ? [{ type: "email", value: subject.natural_identity.email }]
+                    : []),
+                ...(subject.natural_identity.domain
+                    ? [{ type: "domain", value: subject.natural_identity.domain }]
+                    : []),
+                ...(subject.kind === "company"
+                    && subject.represented_clerk_org_ids.includes(sourceFact.clerk_org_id)
+                    && sourceFact.stripe_customer_id
+                    ? [{ type: "stripe_customer", value: sourceFact.stripe_customer_id }]
+                    : []),
+            ].sort(compareAlias);
+        const winner = subject.winning_clerk_org_id
+            ? organizationById.get(subject.winning_clerk_org_id)
+            : undefined;
+        return {
+            kind: subject.kind,
+            key: subject.key,
+            aliases,
+            lookup_identities: subject.projection_action === "neutralize"
+                && subject.natural_identity.domain
+                ? [{ type: "domain", value: subject.natural_identity.domain }]
+                : [],
+            display: subject.display,
+            aggregate_revision: subject.aggregate_revision,
+            aggregate_fingerprint: subject.aggregate_fingerprint,
+            source_state_revision: subject.source_state_revision,
+            membership_set_revision: subject.membership_set_revision,
+            members_complete: true,
+            projection_action: subject.projection_action,
+            replacement_company_key: subject.replacement_company_key,
+            departed_clerk_org_ids: subject.departed_clerk_org_ids,
+            billing_stage: subject.billing_stage,
+            stage_since: subject.stage_since,
+            loss_kind: subject.billing_stage === "lost" ? winner?.loss_kind ?? null : null,
+            winning_clerk_org_id: subject.winning_clerk_org_id,
+            winning_fact_id: subject.winning_fact_id,
+            winning_fact_revision: subject.winning_fact_revision,
+            prebilling_candidate: null,
+            membership_contributors: subject.membership_contributors,
+        };
+    });
+}
+function normalizeActivity(activity, sourceFact, subjects) {
+    if (sourceFact.fact_type === "projection_refreshed" || sourceFact.fact_type === "subscription_ended") {
+        return {
+            emit: false,
+            type: null,
+            source_provider: null,
+            provider_event_id: null,
+            occurred_at: null,
+            summary: null,
+            participants: [],
+        };
+    }
+    const byKey = new Map(subjects.map((subject) => [subject.key, subject]));
+    const currentCompany = subjects.find((subject) => subject.kind === "company"
+        && subject.projection_action === "upsert"
+        && subject.aliases.some((alias) => alias.type === "clerk_organization" && alias.value === sourceFact.clerk_org_id));
+    const participants = activity.subject_keys.map((key) => {
+        const subject = byKey.get(key);
+        if (!subject) {
+            invalid("$.activity.subject_keys", "must reference a normalized snapshot subject");
+        }
+        return {
+            kind: subject.kind,
+            key,
+            role: key === currentCompany?.key ? "primary" : "related",
+        };
+    });
+    if (!participants.some((participant) => participant.role === "primary")) {
+        invalid("$.activity.subject_keys", "customer lifecycle activity must include the causal/current Company");
+    }
+    return {
+        emit: true,
+        type: activity.type,
+        source_provider: FUTURE_SIGNUP_LIFECYCLE_PROJECTION_AUTHORITY,
+        provider_event_id: activity.provider_event_id,
+        occurred_at: activity.occurred_at,
+        summary: activity.summary,
+        participants,
+    };
+}
+function assertBillingShape(state, path) {
+    if (state.billing_stage === null) {
+        if (state.stage_since !== null || state.winning_fact_id !== null || state.winning_fact_revision !== null
+            || ("winning_clerk_org_id" in state && state.winning_clerk_org_id !== null)
+            || ("loss_kind" in state && state.loss_kind !== null)) {
+            invalid(path, "a null billing stage requires null winning evidence");
+        }
+        return;
+    }
+    present(state.stage_since, `${path}.stage_since`);
+    present(state.winning_fact_id, `${path}.winning_fact_id`);
+    present(state.winning_fact_revision, `${path}.winning_fact_revision`);
+    if ("winning_clerk_org_id" in state)
+        present(state.winning_clerk_org_id ?? null, `${path}.winning_clerk_org_id`);
+    if ("loss_kind" in state) {
+        if (state.billing_stage === "lost")
+            present(state.loss_kind ?? null, `${path}.loss_kind`);
+        else if (state.loss_kind !== null)
+            invalid(`${path}.loss_kind`, "must be null unless billing_stage is lost");
+    }
+}
+function parseStageMapping(value, path) {
+    const row = exactRecord(value, path, FUTURE_SIGNUP_LIFECYCLE_PROJECTION_SEMANTIC_STAGES);
+    const mapping = Object.fromEntries(FUTURE_SIGNUP_LIFECYCLE_PROJECTION_SEMANTIC_STAGES.map((stage) => [
+        stage,
+        stageToken(row[stage], `${path}.${stage}`),
+    ]));
+    if (new Set(Object.values(mapping)).size !== FUTURE_SIGNUP_LIFECYCLE_PROJECTION_SEMANTIC_STAGES.length) {
+        invalid(path, "must map the six semantic stages to six distinct physical tokens");
+    }
+    return mapping;
+}
+function exactRecord(value, path, fields) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        invalid(path, "must be an object");
+    const row = value;
+    const allowed = new Set(fields);
+    for (const key of Object.keys(row)) {
+        if (!allowed.has(key))
+            invalid(`${path}.${key}`, "is not part of the closed contract");
+    }
+    for (const field of fields) {
+        if (!Object.hasOwn(row, field))
+            invalid(`${path}.${field}`, "is required");
+    }
+    return row;
+}
+function canonicalText(value, path, maxLength = 512) {
+    if (typeof value !== "string" || value.length === 0)
+        invalid(path, "must be a non-empty string");
+    if (value !== value.trim())
+        invalid(path, "must not contain surrounding whitespace");
+    if (value.length > maxLength)
+        invalid(path, `must be at most ${maxLength} characters`);
+    if (hasAsciiControlCharacter(value))
+        invalid(path, "must not contain control characters");
+    return value;
+}
+function hasAsciiControlCharacter(value) {
+    for (const character of value) {
+        const codePoint = character.codePointAt(0);
+        if (codePoint !== undefined && (codePoint <= 0x1f || codePoint === 0x7f))
+            return true;
+    }
+    return false;
+}
+function nullableText(value, path) {
+    return value === null ? null : canonicalText(value, path);
+}
+function displayText(value, path, maxLength = 256) {
+    return canonicalText(value, path, maxLength);
+}
+function nullableDisplayText(value, path) {
+    return value === null ? null : displayText(value, path);
+}
+function timestamp(value, path) {
+    if (typeof value !== "string")
+        invalid(path, "must be an ISO-8601 UTC string");
+    const parsed = new Date(value);
+    if (!Number.isFinite(parsed.getTime()) || parsed.toISOString() !== value) {
+        invalid(path, "must be canonical ISO-8601 UTC with millisecond precision");
+    }
+    return value;
+}
+function nullableTimestamp(value, path) {
+    return value === null ? null : timestamp(value, path);
+}
+function nullableEmail(value, path) {
+    if (value === null)
+        return null;
+    const email = canonicalText(value, path, 320);
+    if (email !== email.toLowerCase())
+        invalid(path, "must be a lowercase canonical email");
+    const at = email.lastIndexOf("@");
+    if (at < 1 || at !== email.indexOf("@") || at === email.length - 1) {
+        invalid(path, "must be a canonical email");
+    }
+    canonicalDomain(email.slice(at + 1), path);
+    return email;
+}
+function nullableDomain(value, path) {
+    return value === null ? null : canonicalDomain(canonicalText(value, path, 253), path);
+}
+const CANONICAL_DOMAIN = /^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
+function canonicalDomain(value, path) {
+    if (value !== value.toLowerCase() || value.startsWith("www.") || !CANONICAL_DOMAIN.test(value)) {
+        invalid(path, "must use canonical domain_v1 form");
+    }
+    return value;
+}
+function positiveInteger(value, path) {
+    if (!Number.isSafeInteger(value) || value < 1)
+        invalid(path, "must be a positive safe integer");
+    return value;
+}
+function nonNegativeInteger(value, path) {
+    if (!Number.isSafeInteger(value) || value < 0)
+        invalid(path, "must be a non-negative safe integer");
+    return value;
+}
+function nullablePositiveInteger(value, path) {
+    return value === null ? null : positiveInteger(value, path);
+}
+function nullableNonNegativeInteger(value, path) {
+    return value === null ? null : nonNegativeInteger(value, path);
+}
+function nullableCurrency(value, path) {
+    if (value === null)
+        return null;
+    if (typeof value !== "string" || !/^[a-z]{3}$/.test(value))
+        invalid(path, "must be a lowercase ISO currency code");
+    return value;
+}
+function fingerprint(value, path) {
+    if (typeof value !== "string" || !/^[0-9a-f]{64}$/.test(value))
+        invalid(path, "must be a lowercase SHA-256 fingerprint");
+    return value;
+}
+function enumValue(value, allowed, path) {
+    if (typeof value !== "string" || !allowed.includes(value)) {
+        invalid(path, `must be one of ${allowed.join(", ")}`);
+    }
+    return value;
+}
+function nullableEnum(value, allowed, path) {
+    return value === null ? null : enumValue(value, allowed, path);
+}
+function literal(value, expected, path) {
+    if (value !== expected)
+        invalid(path, `must equal ${String(expected)}`);
+}
+function same(actual, expected, path, rule) {
+    if (actual !== expected)
+        invalid(path, rule);
+}
+function sameJson(actual, expected, path, rule) {
+    if (canonicalJson(actual) !== canonicalJson(expected))
+        invalid(path, rule);
+}
+function present(value, path) {
+    if (value === null)
+        invalid(path, "is required for this fact or state");
+}
+function allNull(value, fields, path) {
+    const row = value;
+    for (const field of fields)
+        if (row[field] !== null)
+            invalid(`${path}.${field}`, "must be null for this fact or state");
+}
+function assertSortedUnique(values, key, path) {
+    let previous = null;
+    for (const value of values) {
+        const current = key(value);
+        if (previous !== null && current <= previous)
+            invalid(path, "must be strictly sorted and unique using code-unit order");
+        previous = current;
+    }
+}
+function uniqueSorted(values) {
+    return [...new Set(values)].sort(codeUnitCompare);
+}
+function compareAlias(left, right) {
+    return codeUnitCompare(left.type, right.type) || codeUnitCompare(left.value, right.value);
+}
+function stageToken(value, path) {
+    if (typeof value !== "string" || !/^[a-z][a-z0-9_]{0,63}$/.test(value)) {
+        invalid(path, "must be a canonical lowercase CRM stage token");
+    }
+    return value;
+}
+function canonicalUuid(value, path) {
+    if (typeof value !== "string"
+        || !/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/.test(value)) {
+        invalid(path, "must be a canonical lowercase workspace user UUID");
+    }
+    return value;
+}
+function sha256Canonical(value) {
+    return createHash("sha256").update(canonicalJson(value), "utf8").digest("hex");
+}
+function canonicalJson(value) {
+    return JSON.stringify(canonicalize(value));
+}
+function canonicalize(value) {
+    if (Array.isArray(value))
+        return value.map(canonicalize);
+    if (value && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value)
+            .sort(([left], [right]) => codeUnitCompare(left, right))
+            .map(([key, child]) => [key, canonicalize(child)]));
+    }
+    return value;
+}
+function codeUnitCompare(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function invalid(path, rule) {
+    throw new FutureSignupLifecycleProjectionContractError(path, rule);
+}