@kernhq/module-hr 0.2.0 → 0.4.0

package/dist/server/services/approvals.js

@@ -0,0 +1,325 @@
+import { KernError, uuidv7 } from '@kernhq/kernel';
+import { and, desc, eq, inArray, isNull, lte, or, sql } from 'drizzle-orm';
+import { approvalChains, approvalDecisions, approvalRequests, approvalSteps, delegations, employments, officeAssignments, offices, orgUnits, people, } from '../schema.js';
+import { inForceOn, todayIso } from './db.js';
+/**
+ * The approval engine. One of these, for everything that needs signing off.
+ *
+ * Three decisions carry most of the weight:
+ *
+ * - **The chain is snapshotted when the request is raised.** Editing the workflow afterwards must
+ *   not change who has to sign something already in flight. Discovering that approved leave now
+ *   needs another signature is very hard to explain to the person who already took the week.
+ * - **Approvers are resolved to people at request time**, not looked up at decision time. A
+ *   reorganisation in the middle of an approval would otherwise silently move it to somebody else.
+ * - **One decision per approver per step**, enforced by a unique index. A double click is one
+ *   decision; the database refuses the second rather than counting it towards the quorum twice.
+ */
+export class ApprovalService {
+    kernel;
+    constructor(kernel) {
+        this.kernel = kernel;
+    }
+    /**
+     * Expand a subject — "the manager", "whoever heads this office" — into people.
+     *
+     * Everything is resolved as of `on` rather than now, so a request raised in March is signed by
+     * March's manager even when it is decided in May.
+     */
+    async resolveSubject(tx, workspaceId, subject, requesterId, on) {
+        switch (subject.kind) {
+            case 'person':
+                return subject.id ? [subject.id] : [];
+            case 'manager': {
+                const m = await this.managerOf(tx, workspaceId, requesterId, on);
+                return m ? [m] : [];
+            }
+            case 'manager_of_manager': {
+                const m = await this.managerOf(tx, workspaceId, requesterId, on);
+                if (!m)
+                    return [];
+                const above = await this.managerOf(tx, workspaceId, m, on);
+                // Falls back to the direct manager rather than returning nobody: an empty step would either
+                // block the request forever or wave it through, and both are worse than one signature.
+                return above ? [above] : [m];
+            }
+            case 'org_unit_head': {
+                const [employment] = await tx
+                    .select({ orgUnitId: employments.orgUnitId })
+                    .from(employments)
+                    .where(and(eq(employments.workspaceId, workspaceId), eq(employments.personId, requesterId), inForceOn(employments.effectiveFrom, employments.effectiveTo, on)))
+                    .limit(1);
+                if (!employment?.orgUnitId)
+                    return [];
+                const [unit] = await tx
+                    .select({ headPersonId: orgUnits.headPersonId })
+                    .from(orgUnits)
+                    .where(and(eq(orgUnits.workspaceId, workspaceId), eq(orgUnits.id, employment.orgUnitId)))
+                    .limit(1);
+                return unit?.headPersonId ? [unit.headPersonId] : [];
+            }
+            case 'office_head': {
+                // The local-HR step: whoever heads the requester's *primary* office. Non-primary offices
+                // grant presence, not authority, so they do not get a say here either.
+                const [assignment] = await tx
+                    .select({ officeId: officeAssignments.officeId })
+                    .from(officeAssignments)
+                    .where(and(eq(officeAssignments.workspaceId, workspaceId), eq(officeAssignments.personId, requesterId), eq(officeAssignments.isPrimary, true), inForceOn(officeAssignments.effectiveFrom, officeAssignments.effectiveTo, on)))
+                    .limit(1);
+                if (!assignment)
+                    return [];
+                const [office] = await tx
+                    .select({ headPersonId: offices.headPersonId })
+                    .from(offices)
+                    .where(and(eq(offices.workspaceId, workspaceId), eq(offices.id, assignment.officeId)))
+                    .limit(1);
+                return office?.headPersonId ? [office.headPersonId] : [];
+            }
+            case 'permission': {
+                if (!subject.id)
+                    return [];
+                // Asks core who holds the key, then maps those users to HR people. A permission-based step
+                // is how "any HR administrator" is expressed without naming anybody.
+                const members = await this.kernel
+                    .call('core.workspaces.members', { workspaceId, permission: subject.id }, this.kernel.system)
+                    .catch(() => []);
+                const userIds = members.map((m) => m.userId);
+                if (!userIds.length)
+                    return [];
+                const rows = await tx
+                    .select({ id: people.id })
+                    .from(people)
+                    .where(and(eq(people.workspaceId, workspaceId), inArray(people.userId, userIds)));
+                return rows.map((r) => r.id);
+            }
+            case 'group': {
+                if (!subject.id)
+                    return [];
+                const members = await this.kernel
+                    .call('core.groups.members', { workspaceId, groupId: subject.id }, this.kernel.system)
+                    .catch(() => []);
+                const userIds = members.map((m) => m.userId);
+                if (!userIds.length)
+                    return [];
+                const rows = await tx
+                    .select({ id: people.id })
+                    .from(people)
+                    .where(and(eq(people.workspaceId, workspaceId), inArray(people.userId, userIds)));
+                return rows.map((r) => r.id);
+            }
+            default:
+                return [];
+        }
+    }
+    async managerOf(tx, workspaceId, personId, on) {
+        const [row] = await tx
+            .select({ managerPersonId: employments.managerPersonId })
+            .from(employments)
+            .where(and(eq(employments.workspaceId, workspaceId), eq(employments.personId, personId), inForceOn(employments.effectiveFrom, employments.effectiveTo, on)))
+            .limit(1);
+        return row?.managerPersonId ?? null;
+    }
+    /**
+     * The chain for a subject type: the workspace's default, or a single implicit manager step.
+     *
+     * The implicit fallback is what makes Level 1 work. A company with one approver should not have
+     * to build a chain to discover that it has one, and a workspace with the `approvals` capability
+     * off never sees a chain editor at all.
+     */
+    async chainFor(tx, workspaceId, subjectType) {
+        const [row] = await tx
+            .select()
+            .from(approvalChains)
+            .where(and(eq(approvalChains.workspaceId, workspaceId), eq(approvalChains.subjectType, subjectType), eq(approvalChains.isDefault, true), isNull(approvalChains.archivedAt)))
+            .limit(1);
+        if (row)
+            return row.spec;
+        return {
+            steps: [
+                {
+                    name: 'Manager',
+                    approvers: [{ kind: 'manager' }],
+                    mode: 'any',
+                    minApprovals: 1,
+                    slaHours: null,
+                    onTimeout: 'remind',
+                },
+            ],
+        };
+    }
+    /**
+     * Raise an approval, resolving every step's approvers now.
+     *
+     * Returns the request and the people the first step is waiting on, so the caller can notify them
+     * without re-reading.
+     */
+    async raise(tx, workspaceId, input) {
+        const on = input.on ?? todayIso();
+        const spec = await this.chainFor(tx, workspaceId, input.subjectType);
+        const resolved = [];
+        for (const step of spec.steps) {
+            const ids = new Set();
+            for (const subject of step.approvers)
+                for (const id of await this.resolveSubject(tx, workspaceId, subject, input.requesterPersonId, on))
+                    ids.add(id);
+            // Nobody approves their own request. Where that would empty a step, the step is dropped
+            // rather than left unsatisfiable — a manager requesting leave is approved by the step above.
+            ids.delete(input.requesterPersonId);
+            resolved.push({ step, approverIds: [...ids] });
+        }
+        const usable = resolved.filter((r) => r.approverIds.length > 0);
+        const [request] = await tx
+            .insert(approvalRequests)
+            .values({
+            id: uuidv7(),
+            workspaceId,
+            subjectType: input.subjectType,
+            subjectId: input.subjectId,
+            summary: input.summary,
+            chain: spec,
+            // A chain that resolves to nobody at all is auto-approved rather than left pending for
+            // ever. A one-person company has no manager, and their leave still has to be bookable.
+            status: usable.length ? 'pending' : 'approved',
+            currentStep: 0,
+            requestedBy: input.requestedBy,
+            decidedAt: usable.length ? null : new Date(),
+        })
+            .returning();
+        for (const [index, r] of usable.entries()) {
+            await tx.insert(approvalSteps).values({
+                id: uuidv7(),
+                workspaceId,
+                requestId: request.id,
+                stepIndex: index,
+                name: r.step.name,
+                mode: r.step.mode,
+                minApprovals: r.step.minApprovals,
+                approverIds: r.approverIds,
+                status: index === 0 ? 'pending' : 'pending',
+                dueAt: r.step.slaHours ? new Date(Date.now() + r.step.slaHours * 3600_000) : null,
+            });
+        }
+        return {
+            request: request,
+            autoApproved: usable.length === 0,
+            firstStepApprovers: usable[0]?.approverIds ?? [],
+        };
+    }
+    /**
+     * Record a decision and advance.
+     *
+     * The unique index on `(step_id, approver_id)` is what makes this idempotent: a second decision
+     * from the same person is refused by the database, not counted twice towards a quorum.
+     */
+    async decide(tx, workspaceId, requestId, approverPersonId, decision, comment, onBehalfOfId) {
+        const [request] = await tx
+            .select()
+            .from(approvalRequests)
+            .where(and(eq(approvalRequests.workspaceId, workspaceId), eq(approvalRequests.id, requestId)))
+            .limit(1);
+        if (!request)
+            throw KernError.notFound('Approval request');
+        if (request.status !== 'pending')
+            throw KernError.conflict(`This request is already ${request.status}`);
+        const [step] = await tx
+            .select()
+            .from(approvalSteps)
+            .where(and(eq(approvalSteps.requestId, requestId), eq(approvalSteps.stepIndex, request.currentStep)))
+            .limit(1);
+        if (!step)
+            throw KernError.notFound('Approval step');
+        // The person acting must be on the step — either directly, or as somebody's delegate.
+        const actingAs = onBehalfOfId ?? approverPersonId;
+        if (!step.approverIds.includes(actingAs))
+            throw KernError.forbidden('You are not an approver on this step');
+        if (onBehalfOfId && !(await this.mayActFor(tx, workspaceId, approverPersonId, onBehalfOfId)))
+            throw KernError.forbidden('You do not hold a delegation from that person');
+        await tx.insert(approvalDecisions).values({
+            id: uuidv7(),
+            workspaceId,
+            stepId: step.id,
+            approverId: actingAs,
+            onBehalfOfId: onBehalfOfId ? approverPersonId : null,
+            decision,
+            comment,
+        });
+        const decisions = await tx.select().from(approvalDecisions).where(eq(approvalDecisions.stepId, step.id));
+        const approvals = decisions.filter((d) => d.decision === 'approve').length;
+        const rejections = decisions.filter((d) => d.decision === 'reject').length;
+        // One rejection ends it. Every workflow we have wants that, and "some approvers rejected but it
+        // went through anyway" is not a sentence anybody wants to read in an audit.
+        if (rejections > 0) {
+            await tx.update(approvalSteps).set({ status: 'rejected' }).where(eq(approvalSteps.id, step.id));
+            await tx
+                .update(approvalRequests)
+                .set({ status: 'rejected', decidedAt: new Date(), version: sql `${approvalRequests.version} + 1` })
+                .where(eq(approvalRequests.id, requestId));
+            return { status: 'rejected', request };
+        }
+        const needed = step.mode === 'all' ? step.approverIds.length : step.mode === 'any' ? 1 : step.minApprovals;
+        if (approvals < needed)
+            return { status: 'pending', request };
+        await tx.update(approvalSteps).set({ status: 'approved' }).where(eq(approvalSteps.id, step.id));
+        const [next] = await tx
+            .select()
+            .from(approvalSteps)
+            .where(and(eq(approvalSteps.requestId, requestId), eq(approvalSteps.stepIndex, request.currentStep + 1)))
+            .limit(1);
+        if (next) {
+            await tx
+                .update(approvalRequests)
+                .set({ currentStep: request.currentStep + 1, version: sql `${approvalRequests.version} + 1` })
+                .where(eq(approvalRequests.id, requestId));
+            return { status: 'pending', request, advancedTo: next.stepIndex };
+        }
+        await tx
+            .update(approvalRequests)
+            .set({ status: 'approved', decidedAt: new Date(), version: sql `${approvalRequests.version} + 1` })
+            .where(eq(approvalRequests.id, requestId));
+        return { status: 'approved', request };
+    }
+    /** Does `actor` hold a live delegation from `from`? */
+    async mayActFor(tx, workspaceId, actor, from) {
+        const today = todayIso();
+        const [row] = await tx
+            .select({ id: delegations.id })
+            .from(delegations)
+            .where(and(eq(delegations.workspaceId, workspaceId), eq(delegations.toPersonId, actor), eq(delegations.fromPersonId, from), lte(delegations.startsOn, today), sql `${delegations.endsOn} >= ${today}`))
+            .limit(1);
+        return !!row;
+    }
+    /** Cancel an in-flight approval, because its subject was withdrawn. */
+    async cancel(tx, workspaceId, subjectType, subjectId) {
+        await tx
+            .update(approvalRequests)
+            .set({ status: 'cancelled', decidedAt: new Date() })
+            .where(and(eq(approvalRequests.workspaceId, workspaceId), eq(approvalRequests.subjectType, subjectType), eq(approvalRequests.subjectId, subjectId), eq(approvalRequests.status, 'pending')));
+    }
+    /** Everything waiting on this person, including what they may decide by delegation. */
+    async inboxFor(tx, workspaceId, personId, includeDecided, limit) {
+        const today = todayIso();
+        const delegated = await tx
+            .select({ fromPersonId: delegations.fromPersonId })
+            .from(delegations)
+            .where(and(eq(delegations.workspaceId, workspaceId), eq(delegations.toPersonId, personId), lte(delegations.startsOn, today), sql `${delegations.endsOn} >= ${today}`));
+        const actingFor = [personId, ...delegated.map((d) => d.fromPersonId)];
+        const steps = await tx
+            .select()
+            .from(approvalSteps)
+            .where(and(eq(approvalSteps.workspaceId, workspaceId), sql `${approvalSteps.approverIds} && ${sql.raw(`ARRAY[${actingFor.map((i) => `'${i}'`).join(',')}]::uuid[]`)}`));
+        if (!steps.length)
+            return [];
+        const requestIds = [...new Set(steps.map((s) => s.requestId))];
+        const where = [eq(approvalRequests.workspaceId, workspaceId), inArray(approvalRequests.id, requestIds)];
+        if (!includeDecided)
+            where.push(eq(approvalRequests.status, 'pending'));
+        return tx
+            .select()
+            .from(approvalRequests)
+            .where(and(...where))
+            .orderBy(desc(approvalRequests.requestedAt))
+            .limit(limit);
+    }
+}
+export { or };
+//# sourceMappingURL=approvals.js.map

package/dist/server/services/approvals.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"approvals.js","sourceRoot":"","sources":["../../../src/server/services/approvals.ts"],"names":[],"mappings":"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"}

package/dist/server/services/attendance.d.ts

@@ -0,0 +1,150 @@
+import { type Tx } from '@kernhq/kernel';
+import { inArray, sql } from 'drizzle-orm';
+import { type RoundingPolicy, type ShiftSpec } from '../../policy/working-time.js';
+/**
+ * Punches and the day sheet.
+ *
+ * The two rules this service exists to enforce:
+ *
+ * - **The server stamps the time.** A client's clock is a claim, recorded for audit and never
+ *   trusted. Client clocks are wrong by accident constantly and on purpose occasionally, and a
+ *   system that cannot tell an offline sync from an edited phone clock cannot defend any of its
+ *   numbers.
+ * - **The day sheet is derived.** Every figure on it comes from punches + schedule + calendar +
+ *   leave, and can be thrown away and rebuilt. Nothing is ever repaired by hand.
+ */
+export interface ResolvedSchedule {
+    shiftFor(date: string): ShiftSpec | null;
+    rounding: RoundingPolicy;
+    autoClockOutAfterMinutes: number | null;
+    scheduleId: string | null;
+}
+/** A schedule with no shifts: somebody with no assignment still clocks in, they just owe no hours. */
+export declare const NO_SCHEDULE: ResolvedSchedule;
+export declare class AttendanceService {
+    /** The schedule in force for a person on a date, as something the pure layer can use. */
+    scheduleFor(tx: Tx, workspaceId: string, personId: string, on: string): Promise<ResolvedSchedule>;
+    /**
+     * Record a punch.
+     *
+     * `at` is the server's clock, always. `clientReportedAt` is kept beside it with the measured skew
+     * so an offline sync can be told from a device whose clock is wrong — and a claim beyond the
+     * threshold is marked `disputed` rather than silently accepted or silently dropped.
+     */
+    record(tx: Tx, workspaceId: string, input: {
+        personId: string;
+        direction: 'in' | 'out' | 'break_start' | 'break_end';
+        timezone: string;
+        method: string;
+        clientReportedAt?: string | null;
+        officeId?: string | null;
+        geo?: Record<string, number> | null;
+        note?: string | null;
+        idempotencyKey?: string | null;
+        /** Set only by the offline sync path, where the instant genuinely is the client's claim. */
+        claimedAt?: Date | null;
+    }, schedule: ResolvedSchedule): Promise<{
+        createdAt: Date;
+        id: string;
+        timezone: string;
+        workspaceId: string;
+        personId: string;
+        officeId: string | null;
+        note: string | null;
+        at: Date;
+        direction: string;
+        businessDate: string;
+        method: string;
+        trust: string;
+        clientReportedAt: Date | null;
+        skewMs: number | null;
+        deviceId: string | null;
+        geo: Record<string, number> | null;
+        voidedByPunchId: string | null;
+        idempotencyKey: string | null;
+    }>;
+    /** Live punches for a person on a business date, oldest first. Voided rows are excluded. */
+    punchesOn(tx: Tx, workspaceId: string, personId: string, businessDate: string): Promise<{
+        id: string;
+        workspaceId: string;
+        personId: string;
+        direction: string;
+        at: Date;
+        clientReportedAt: Date | null;
+        skewMs: number | null;
+        businessDate: string;
+        timezone: string;
+        method: string;
+        officeId: string | null;
+        deviceId: string | null;
+        geo: Record<string, number> | null;
+        trust: string;
+        voidedByPunchId: string | null;
+        idempotencyKey: string | null;
+        note: string | null;
+        createdAt: Date;
+    }[]>;
+    /**
+     * Rebuild one day from its punches.
+     *
+     * Idempotent by construction, which is what makes it safe to call on every punch, from a nightly
+     * sweep, and from a support request without thinking about it. A locked day is left alone and
+     * reported, never silently skipped — a recomputation that quietly declines to touch a closed
+     * month looks identical to one that had nothing to do.
+     */
+    recomputeDay(tx: Tx, workspaceId: string, personId: string, businessDate: string, timezone: string, schedule: ResolvedSchedule): Promise<{
+        locked: boolean;
+    }>;
+    /** Which business dates a person has punches on, in a range. Drives a bulk recompute. */
+    datesWithPunches(tx: Tx, workspaceId: string, personId: string, from: string, to: string): Promise<string[]>;
+    /**
+     * Void a punch by writing a correcting row that points at it.
+     *
+     * The original stays exactly as it was. Two rows is the point: "this was recorded and then
+     * corrected" and "this was never recorded" are different facts, and only one of them is true.
+     */
+    voidPunch(tx: Tx, workspaceId: string, punchId: string, reason: string, actorPersonId: string | null): Promise<{
+        original: {
+            id: string;
+            workspaceId: string;
+            personId: string;
+            direction: string;
+            at: Date;
+            clientReportedAt: Date | null;
+            skewMs: number | null;
+            businessDate: string;
+            timezone: string;
+            method: string;
+            officeId: string | null;
+            deviceId: string | null;
+            geo: Record<string, number> | null;
+            trust: string;
+            voidedByPunchId: string | null;
+            idempotencyKey: string | null;
+            note: string | null;
+            createdAt: Date;
+        };
+        correction: {
+            createdAt: Date;
+            id: string;
+            timezone: string;
+            workspaceId: string;
+            personId: string;
+            officeId: string | null;
+            note: string | null;
+            at: Date;
+            direction: string;
+            businessDate: string;
+            method: string;
+            trust: string;
+            clientReportedAt: Date | null;
+            skewMs: number | null;
+            deviceId: string | null;
+            geo: Record<string, number> | null;
+            voidedByPunchId: string | null;
+            idempotencyKey: string | null;
+        };
+    }>;
+}
+export { inArray, sql };
+//# sourceMappingURL=attendance.d.ts.map

package/dist/server/services/attendance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attendance.d.ts","sourceRoot":"","sources":["../../../src/server/services/attendance.ts"],"names":[],"mappings":"AAAA,OAAO,EAAa,KAAK,EAAE,EAAU,MAAM,gBAAgB,CAAA;AAC3D,OAAO,EAAqB,OAAO,EAAe,GAAG,EAAE,MAAM,aAAa,CAAA;AAG1E,OAAO,EAIL,KAAK,cAAc,EACnB,KAAK,SAAS,EACf,MAAM,8BAA8B,CAAA;AAIrC;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAAA;IACxC,QAAQ,EAAE,cAAc,CAAA;IACxB,wBAAwB,EAAE,MAAM,GAAG,IAAI,CAAA;IACvC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;CAC1B;AAED,sGAAsG;AACtG,eAAO,MAAM,WAAW,EAAE,gBAKzB,CAAA;AAED,qBAAa,iBAAiB;IAC5B,yFAAyF;IACnF,WAAW,CAAC,EAAE,EAAE,EAAE,EAAE,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IA2CvG;;;;;;OAMG;IACG,MAAM,CACV,EAAE,EAAE,EAAE,EACN,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE;QACL,QAAQ,EAAE,MAAM,CAAA;QAChB,SAAS,EAAE,IAAI,GAAG,KAAK,GAAG,aAAa,GAAG,WAAW,CAAA;QACrD,QAAQ,EAAE,MAAM,CAAA;QAChB,MAAM,EAAE,MAAM,CAAA;QACd,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;QAChC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;QACxB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAA;QACnC,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;QACpB,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;QAC9B,4FAA4F;QAC5F,SAAS,CAAC,EAAE,IAAI,GAAG,IAAI,CAAA;KACxB,EACD,QAAQ,EAAE,gBAAgB;;;;;;;;;;;;;;;;;;;;IAuC5B,4FAA4F;IACtF,SAAS,CAAC,EAAE,EAAE,EAAE,EAAE,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM;;;;;;;;;;;;;;;;;;;;IAenF;;;;;;;OAOG;IACG,YAAY,CAChB,EAAE,EAAE,EAAE,EACN,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,gBAAgB,GACzB,OAAO,CAAC;QAAE,MAAM,EAAE,OAAO,CAAA;KAAE,CAAC;IA0F/B,yFAAyF;IACnF,gBAAgB,CACpB,EAAE,EAAE,EAAE,EACN,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,GACT,OAAO,CAAC,MAAM,EAAE,CAAC;IAepB;;;;;OAKG;IACG,SAAS,CACb,EAAE,EAAE,EAAE,EACN,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,aAAa,EAAE,MAAM,GAAG,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyC/B;AAYD,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,CAAA"}