forge-openclaw-plugin 0.2.19 → 0.2.21

package/dist/server/repositories/tasks.js

@@ -3,12 +3,14 @@ import { getDatabase } from "../db.js";
 import { runInTransaction } from "../db.js";
 import { HttpError } from "../errors.js";
 import { recordActivityEvent } from "./activity-events.js";
+import { decorateOwnedEntity, inferFirstOwnedUserId, setEntityOwner } from "./entity-ownership.js";
 import { filterDeletedEntities, filterDeletedIds, isEntityDeleted } from "./deleted-entities.js";
 import { getGoalById } from "./goals.js";
 import { createLinkedNotes } from "./notes.js";
 import { ensureDefaultProjectForGoal, getProjectById } from "./projects.js";
 import { pruneLinkedEntityReferences } from "./psyche.js";
 import { awardTaskCompletionReward, reverseLatestTaskCompletionReward } from "./rewards.js";
+import { findUserByLabel, getDefaultUser, getUserById, resolveUserForMutation } from "./users.js";
 import { assertTaskRelations } from "../services/relations.js";
 import { computeWorkTime, emptyTaskTimeSummary } from "../services/work-time.js";
 import { calendarSchedulingRulesSchema, taskSchema } from "../types.js";
@@ -19,7 +21,7 @@ function readTaskTagIds(taskId) {
     return filterDeletedIds("tag", rows.map((row) => row.tag_id));
 }
 function mapTask(row, time = emptyTaskTimeSummary()) {
-    return taskSchema.parse({
+    return taskSchema.parse(decorateOwnedEntity("task", {
         id: row.id,
         title: row.title,
         description: row.description,
@@ -42,7 +44,7 @@ function mapTask(row, time = emptyTaskTimeSummary()) {
         updatedAt: row.updated_at,
         tagIds: readTaskTagIds(row.id),
         time
-    });
+    }));
 }
 function replaceTaskTags(taskId, tagIds) {
     const database = getDatabase();
@@ -64,21 +66,76 @@ function normalizeCompletedAt(status, existingCompletedAt) {
     }
     return null;
 }
+function resolveTaskAssignment(input) {
+    if (input.userId !== undefined) {
+        const user = resolveUserForMutation(input.userId, input.owner ?? undefined);
+        return {
+            userId: user.id,
+            ownerLabel: input.owner?.trim() || user.displayName
+        };
+    }
+    if (input.owner && input.owner.trim().length > 0) {
+        const matchedUser = findUserByLabel(input.owner);
+        return {
+            userId: matchedUser?.id ??
+                input.currentUserId ??
+                input.inheritedUserId ??
+                getDefaultUser().id,
+            ownerLabel: matchedUser?.displayName ?? input.owner.trim()
+        };
+    }
+    if (input.currentUserId) {
+        const currentUser = getUserById(input.currentUserId);
+        if (currentUser) {
+            return {
+                userId: currentUser.id,
+                ownerLabel: currentUser.displayName
+            };
+        }
+    }
+    if (input.inheritedUserId) {
+        const inheritedUser = getUserById(input.inheritedUserId);
+        if (inheritedUser) {
+            return {
+                userId: inheritedUser.id,
+                ownerLabel: inheritedUser.displayName
+            };
+        }
+    }
+    const fallbackUser = getDefaultUser();
+    return {
+        userId: fallbackUser.id,
+        ownerLabel: fallbackUser.displayName
+    };
+}
 function resolveProjectAndGoalIds(input, current) {
     const currentGoalId = current?.goalId && getGoalById(current.goalId) ? current.goalId : null;
-    const currentProject = current?.projectId ? getProjectById(current.projectId) ?? null : null;
-    const currentProjectGoalId = currentProject?.goalId && getGoalById(currentProject.goalId) ? currentProject.goalId : null;
+    const currentProject = current?.projectId
+        ? (getProjectById(current.projectId) ?? null)
+        : null;
+    const currentProjectGoalId = currentProject?.goalId && getGoalById(currentProject.goalId)
+        ? currentProject.goalId
+        : null;
     const currentProjectId = currentProject?.id ?? null;
     const requestedGoalId = input.goalId === undefined ? currentGoalId : input.goalId;
-    const goalChangedWithoutProjectOverride = current !== undefined && input.goalId !== undefined && input.goalId !== current.goalId && input.projectId === undefined;
-    const requestedProjectId = input.projectId === undefined ? (goalChangedWithoutProjectOverride ? null : currentProjectId) : input.projectId;
+    const goalChangedWithoutProjectOverride = current !== undefined &&
+        input.goalId !== undefined &&
+        input.goalId !== current.goalId &&
+        input.projectId === undefined;
+    const requestedProjectId = input.projectId === undefined
+        ? goalChangedWithoutProjectOverride
+            ? null
+            : currentProjectId
+        : input.projectId;
     if (requestedProjectId) {
         const project = getProjectById(requestedProjectId);
         if (!project) {
             throw new HttpError(404, "project_not_found", `Project ${requestedProjectId} does not exist`);
         }
         const projectGoalId = getGoalById(project.goalId) ? project.goalId : null;
-        if (requestedGoalId && projectGoalId && project.goalId !== requestedGoalId) {
+        if (requestedGoalId &&
+            projectGoalId &&
+            project.goalId !== requestedGoalId) {
             throw new HttpError(409, "project_goal_mismatch", `Project ${requestedProjectId} does not belong to goal ${requestedGoalId}`);
         }
         return {
@@ -117,17 +174,25 @@ function inferReopenStatus(taskId) {
         return "focus";
     }
     const metadata = JSON.parse(row.metadata_json);
-    return metadata.previousStatus && metadata.previousStatus !== "done" ? metadata.previousStatus : "focus";
+    return metadata.previousStatus && metadata.previousStatus !== "done"
+        ? metadata.previousStatus
+        : "focus";
 }
 function updateTaskRecord(current, input, activity) {
     const relationState = resolveProjectAndGoalIds(input, current);
     const nextGoalId = relationState.goalId;
     const nextProjectId = relationState.projectId;
     const nextTagIds = input.tagIds ?? current.tagIds;
+    const assignment = resolveTaskAssignment({
+        userId: input.userId,
+        owner: input.owner,
+        currentUserId: current.userId
+    });
     assertTaskRelations({ goalId: nextGoalId, tagIds: nextTagIds });
     const nextStatus = input.status ?? current.status;
     const movedColumns = nextStatus !== current.status;
-    const nextSort = input.sortOrder ?? (movedColumns ? nextSortOrder(nextStatus) : current.sortOrder);
+    const nextSort = input.sortOrder ??
+        (movedColumns ? nextSortOrder(nextStatus) : current.sortOrder);
     const completedAt = normalizeCompletedAt(nextStatus, current.completedAt);
     const updatedAt = new Date().toISOString();
     getDatabase()
@@ -135,7 +200,7 @@ function updateTaskRecord(current, input, activity) {
        SET title = ?, description = ?, status = ?, priority = ?, owner = ?, goal_id = ?, due_date = ?, effort = ?,
            energy = ?, points = ?, planned_duration_seconds = ?, scheduling_rules_json = ?, sort_order = ?, completed_at = ?, updated_at = ?, project_id = ?
        WHERE id = ?`)
-        .run(input.title ?? current.title, input.description ?? current.description, nextStatus, input.priority ?? current.priority, input.owner ?? current.owner, nextGoalId, input.dueDate === undefined ? current.dueDate : input.dueDate, input.effort ?? current.effort, input.energy ?? current.energy, input.points ?? current.points, input.plannedDurationSeconds === undefined
+        .run(input.title ?? current.title, input.description ?? current.description, nextStatus, input.priority ?? current.priority, assignment.ownerLabel, nextGoalId, input.dueDate === undefined ? current.dueDate : input.dueDate, input.effort ?? current.effort, input.energy ?? current.energy, input.points ?? current.points, input.plannedDurationSeconds === undefined
         ? current.plannedDurationSeconds
         : input.plannedDurationSeconds, input.schedulingRules === undefined
         ? current.schedulingRules === null
@@ -145,6 +210,7 @@ function updateTaskRecord(current, input, activity) {
             ? null
             : JSON.stringify(input.schedulingRules), nextSort, completedAt, updatedAt, nextProjectId, current.id);
     replaceTaskTags(current.id, nextTagIds);
+    setEntityOwner("task", current.id, assignment.userId);
     const updated = getTaskById(current.id);
     if (updated && activity) {
         const statusChanged = current.status !== updated.status;
@@ -236,6 +302,15 @@ function fingerprintTaskCreate(input) {
 }
 function insertTaskRecord(input, activity) {
     const relationState = resolveProjectAndGoalIds(input);
+    const inheritedUserId = inferFirstOwnedUserId([
+        { entityType: "project", entityId: relationState.projectId },
+        { entityType: "goal", entityId: relationState.goalId }
+    ]);
+    const assignment = resolveTaskAssignment({
+        userId: input.userId,
+        owner: input.owner,
+        inheritedUserId
+    });
     assertTaskRelations({ goalId: relationState.goalId, tagIds: input.tagIds });
     if (!relationState.projectId) {
         throw new HttpError(400, "project_required", "Tasks must belong to a project");
@@ -250,7 +325,10 @@ function insertTaskRecord(input, activity) {
         planned_duration_seconds, scheduling_rules_json, sort_order, completed_at, created_at, updated_at
       )
       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
-        .run(id, input.title, input.description, input.status, input.priority, input.owner, relationState.goalId, relationState.projectId, input.dueDate, input.effort, input.energy, input.points, input.plannedDurationSeconds, input.schedulingRules === null ? null : JSON.stringify(input.schedulingRules), sortOrder, completedAt, now, now);
+        .run(id, input.title, input.description, input.status, input.priority, assignment.ownerLabel, relationState.goalId, relationState.projectId, input.dueDate, input.effort, input.energy, input.points, input.plannedDurationSeconds, input.schedulingRules === null
+        ? null
+        : JSON.stringify(input.schedulingRules), sortOrder, completedAt, now, now);
+    setEntityOwner("task", id, assignment.userId);
     replaceTaskTags(id, input.tagIds);
     const task = getTaskById(id);
     if (activity) {
@@ -259,7 +337,9 @@ function insertTaskRecord(input, activity) {
             entityId: task.id,
             eventType: "task_created",
             title: `Task created: ${task.title}`,
-            description: task.goalId ? `Linked to ${task.goalId} and assigned to ${task.owner}.` : `Assigned to ${task.owner}.`,
+            description: task.goalId
+                ? `Linked to ${task.goalId} and assigned to ${task.owner}.`
+                : `Assigned to ${task.owner}.`,
             actor: activity.actor ?? null,
             source: activity.source,
             metadata: {
@@ -281,7 +361,9 @@ export function listTasks(filters = {}) {
     const whereClauses = [];
     const params = [];
     const todayIso = new Date().toISOString().slice(0, 10);
-    const weekIso = new Date(Date.now() + 7 * 24 * 60 * 60 * 1000).toISOString().slice(0, 10);
+    const weekIso = new Date(Date.now() + 7 * 24 * 60 * 60 * 1000)
+        .toISOString()
+        .slice(0, 10);
     if (filters.status) {
         whereClauses.push("status = ?");
         params.push(filters.status);
@@ -352,7 +434,9 @@ export function getTaskById(taskId) {
        WHERE id = ?`)
         .get(taskId);
     const workTime = computeWorkTime();
-    return row ? mapTask(row, workTime.taskSummaries.get(row.id) ?? emptyTaskTimeSummary()) : undefined;
+    return row
+        ? mapTask(row, workTime.taskSummaries.get(row.id) ?? emptyTaskTimeSummary())
+        : undefined;
 }
 export function createTask(input, activity) {
     return runInTransaction(() => insertTaskRecord(input, activity));
@@ -414,9 +498,7 @@ export function deleteTask(taskId, activity) {
     }
     return runInTransaction(() => {
         pruneLinkedEntityReferences("task", taskId);
-        getDatabase()
-            .prepare(`DELETE FROM tasks WHERE id = ?`)
-            .run(taskId);
+        getDatabase().prepare(`DELETE FROM tasks WHERE id = ?`).run(taskId);
         if (activity) {
             recordActivityEvent({
                 entityType: "task",

package/dist/server/repositories/users.js

@@ -0,0 +1,417 @@
+import { randomUUID } from "node:crypto";
+import { getDatabase } from "../db.js";
+import { createUserSchema, updateUserSchema, userAccessGrantSchema, userAccessRightsSchema, userOwnershipSummarySchema, userXpSummarySchema, updateUserAccessGrantSchema, userSummarySchema } from "../types.js";
+function startOfWeek(date) {
+    const clone = new Date(date);
+    const day = clone.getDay();
+    const delta = day === 0 ? -6 : 1 - day;
+    clone.setDate(clone.getDate() + delta);
+    clone.setHours(0, 0, 0, 0);
+    return clone;
+}
+function normalizeHandle(value) {
+    return value
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "_")
+        .replace(/^_+|_+$/g, "")
+        .slice(0, 48);
+}
+function buildDefaultRights(self = false) {
+    return userAccessRightsSchema.parse({
+        discoverable: true,
+        canListUsers: true,
+        canReadProfile: true,
+        canReadEntities: true,
+        canSearchEntities: true,
+        canLinkEntities: true,
+        canCoordinate: true,
+        canAffectEntities: true,
+        canManageStrategies: true,
+        canCreateOnBehalf: true,
+        canViewMetrics: true,
+        canViewActivity: true,
+        ...(self ? { discoverable: true } : {})
+    });
+}
+function buildGrantConfig(self = false) {
+    return {
+        self,
+        mutable: self,
+        linkedEntities: true,
+        rights: buildDefaultRights(self)
+    };
+}
+function normalizeGrantConfig(value, options = {}) {
+    const current = value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : {};
+    const defaultConfig = buildGrantConfig(options.self ?? false);
+    return {
+        self: typeof current.self === "boolean" ? current.self : defaultConfig.self,
+        mutable: typeof current.mutable === "boolean"
+            ? current.mutable
+            : defaultConfig.mutable,
+        linkedEntities: typeof current.linkedEntities === "boolean"
+            ? current.linkedEntities
+            : defaultConfig.linkedEntities,
+        rights: userAccessRightsSchema.parse({
+            ...defaultConfig.rights,
+            ...(current.rights &&
+                typeof current.rights === "object" &&
+                !Array.isArray(current.rights)
+                ? current.rights
+                : current)
+        })
+    };
+}
+function deriveAccessLevel(config) {
+    return config.self ||
+        config.mutable ||
+        config.rights.canAffectEntities ||
+        config.rights.canCreateOnBehalf ||
+        config.rights.canManageStrategies
+        ? "manage"
+        : "view";
+}
+function upsertRelationshipGrant(subjectUserId, targetUserId, now) {
+    const database = getDatabase();
+    const self = subjectUserId === targetUserId;
+    const config = buildGrantConfig(self);
+    const accessLevel = deriveAccessLevel(config);
+    const existing = database
+        .prepare(`SELECT id
+       FROM user_access_grants
+       WHERE subject_user_id = ?
+         AND target_user_id = ?
+       ORDER BY CASE access_level WHEN 'manage' THEN 0 ELSE 1 END, created_at ASC
+       LIMIT 1`)
+        .get(subjectUserId, targetUserId);
+    if (existing) {
+        database
+            .prepare(`UPDATE user_access_grants
+         SET access_level = ?, config_json = ?, updated_at = ?
+         WHERE id = ?`)
+            .run(accessLevel, JSON.stringify(config), now, existing.id);
+        database
+            .prepare(`DELETE FROM user_access_grants
+         WHERE subject_user_id = ?
+           AND target_user_id = ?
+           AND id != ?`)
+            .run(subjectUserId, targetUserId, existing.id);
+        return;
+    }
+    database
+        .prepare(`INSERT INTO user_access_grants (
+         id,
+         subject_user_id,
+         target_user_id,
+         access_level,
+         config_json,
+         created_at,
+         updated_at
+       )
+       VALUES (?, ?, ?, ?, ?, ?, ?)`)
+        .run(`grant_${randomUUID().replaceAll("-", "").slice(0, 16)}`, subjectUserId, targetUserId, accessLevel, JSON.stringify(config), now, now);
+}
+export function ensureSystemUsers() {
+    const database = getDatabase();
+    const settingsRow = database
+        .prepare(`SELECT operator_name
+       FROM app_settings
+       WHERE id = 1`)
+        .get();
+    const operatorDisplayName = settingsRow?.operator_name?.trim() || "Operator";
+    const operatorHandle = normalizeHandle(operatorDisplayName) || "operator";
+    const now = new Date().toISOString();
+    database
+        .prepare(`INSERT OR IGNORE INTO users (id, kind, handle, display_name, description, accent_color, created_at, updated_at)
+       VALUES (?, 'human', ?, ?, 'Primary human Forge operator.', '#f4b97a', ?, ?)`)
+        .run("user_operator", operatorHandle, operatorDisplayName, now, now);
+    database
+        .prepare(`UPDATE users
+       SET handle = ?, display_name = ?, updated_at = ?
+       WHERE id = ?`)
+        .run(operatorHandle, operatorDisplayName, now, "user_operator");
+    database
+        .prepare(`INSERT OR IGNORE INTO users (id, kind, handle, display_name, description, accent_color, created_at, updated_at)
+       VALUES (
+         'user_forge_bot',
+         'bot',
+         'forge_bot',
+         'Forge Bot',
+         'Autonomous or semi-autonomous execution partner inside Forge.',
+         '#7dd3fc',
+         ?,
+         ?
+       )`)
+        .run(now, now);
+    const users = listUsers();
+    for (const subjectUser of users) {
+        for (const targetUser of users) {
+            upsertRelationshipGrant(subjectUser.id, targetUser.id, now);
+        }
+    }
+}
+function ensurePermissiveGrantsForUser(userId, now) {
+    const existingUsers = listUsers();
+    for (const otherUser of existingUsers) {
+        upsertRelationshipGrant(userId, otherUser.id, now);
+        if (otherUser.id !== userId) {
+            upsertRelationshipGrant(otherUser.id, userId, now);
+        }
+    }
+}
+function mapUser(row) {
+    return userSummarySchema.parse({
+        id: row.id,
+        kind: row.kind,
+        handle: row.handle,
+        displayName: row.display_name,
+        description: row.description,
+        accentColor: row.accent_color,
+        createdAt: row.created_at,
+        updatedAt: row.updated_at
+    });
+}
+function readUserRows(whereSql = "", params = []) {
+    return getDatabase()
+        .prepare(`SELECT id, kind, handle, display_name, description, accent_color, created_at, updated_at
+       FROM users
+       ${whereSql}
+       ORDER BY CASE kind WHEN 'human' THEN 0 ELSE 1 END, display_name ASC`)
+        .all(...params);
+}
+export function listUsers(filters = {}) {
+    const whereClauses = [];
+    const params = [];
+    if (filters.kind) {
+        whereClauses.push("kind = ?");
+        params.push(filters.kind);
+    }
+    const whereSql = whereClauses.length > 0 ? `WHERE ${whereClauses.join(" AND ")}` : "";
+    return readUserRows(whereSql, params).map(mapUser);
+}
+export function listUsersByIds(userIds) {
+    if (userIds.length === 0) {
+        return [];
+    }
+    const placeholders = userIds.map(() => "?").join(", ");
+    return readUserRows(`WHERE id IN (${placeholders})`, [...userIds]).map(mapUser);
+}
+export function getUserById(userId) {
+    const row = getDatabase()
+        .prepare(`SELECT id, kind, handle, display_name, description, accent_color, created_at, updated_at
+       FROM users
+       WHERE id = ?`)
+        .get(userId);
+    return row ? mapUser(row) : undefined;
+}
+export function listUserAccessGrants(filters = {}) {
+    const whereClauses = [];
+    const params = [];
+    if (filters.subjectUserId) {
+        whereClauses.push("subject_user_id = ?");
+        params.push(filters.subjectUserId);
+    }
+    if (filters.targetUserId) {
+        whereClauses.push("target_user_id = ?");
+        params.push(filters.targetUserId);
+    }
+    const whereSql = whereClauses.length > 0 ? `WHERE ${whereClauses.join(" AND ")}` : "";
+    const rows = getDatabase()
+        .prepare(`SELECT id, subject_user_id, target_user_id, access_level, config_json, created_at, updated_at
+       FROM user_access_grants
+       ${whereSql}
+       ORDER BY subject_user_id ASC, target_user_id ASC`)
+        .all(...params);
+    const usersById = new Map(listUsers().map((user) => [user.id, user]));
+    return rows.map((row) => userAccessGrantSchema.parse({
+        id: row.id,
+        subjectUserId: row.subject_user_id,
+        targetUserId: row.target_user_id,
+        accessLevel: row.access_level,
+        config: normalizeGrantConfig(JSON.parse(row.config_json), {
+            self: row.subject_user_id === row.target_user_id
+        }),
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+        subjectUser: usersById.get(row.subject_user_id) ?? null,
+        targetUser: usersById.get(row.target_user_id) ?? null
+    }));
+}
+export function listUserOwnershipSummaries() {
+    const rows = getDatabase()
+        .prepare(`SELECT user_id, entity_type, COUNT(*) AS count
+       FROM entity_owners
+       GROUP BY user_id, entity_type
+       ORDER BY user_id ASC, entity_type ASC`)
+        .all();
+    const countsByUserId = new Map();
+    for (const row of rows) {
+        const current = countsByUserId.get(row.user_id) ?? {};
+        current[row.entity_type] = row.count;
+        countsByUserId.set(row.user_id, current);
+    }
+    return listUsers().map((user) => {
+        const entityCounts = countsByUserId.get(user.id) ?? {};
+        const totalOwnedEntities = Object.values(entityCounts).reduce((sum, count) => sum + count, 0);
+        return userOwnershipSummarySchema.parse({
+            userId: user.id,
+            totalOwnedEntities,
+            entityCounts
+        });
+    });
+}
+export function listUserXpSummaries() {
+    const users = listUsers();
+    const summaries = new Map(users.map((user) => [
+        user.id,
+        {
+            userId: user.id,
+            totalXp: 0,
+            weeklyXp: 0,
+            rewardEventCount: 0,
+            lastRewardAt: null
+        }
+    ]));
+    const ownerRows = getDatabase()
+        .prepare(`SELECT entity_type, entity_id, user_id
+       FROM entity_owners`)
+        .all();
+    const ownerByEntityKey = new Map(ownerRows.map((row) => [`${row.entity_type}:${row.entity_id}`, row.user_id]));
+    const usersByLabel = new Map();
+    for (const user of users) {
+        usersByLabel.set(user.displayName.trim().toLowerCase(), user.id);
+        usersByLabel.set(user.handle.trim().toLowerCase(), user.id);
+    }
+    const weekStartIso = startOfWeek(new Date()).toISOString();
+    const rewardRows = getDatabase()
+        .prepare(`SELECT entity_type, entity_id, actor, delta_xp, created_at
+       FROM reward_ledger
+       ORDER BY created_at ASC`)
+        .all();
+    for (const row of rewardRows) {
+        const ownedUserId = row.entity_type === "system"
+            ? row.actor
+                ? (usersByLabel.get(row.actor.trim().toLowerCase()) ?? null)
+                : null
+            : (ownerByEntityKey.get(`${row.entity_type}:${row.entity_id}`) ?? null);
+        if (!ownedUserId) {
+            continue;
+        }
+        const summary = summaries.get(ownedUserId);
+        if (!summary) {
+            continue;
+        }
+        summary.totalXp += row.delta_xp;
+        if (row.created_at >= weekStartIso) {
+            summary.weeklyXp += row.delta_xp;
+        }
+        summary.rewardEventCount += 1;
+        summary.lastRewardAt = row.created_at;
+    }
+    return users.map((user) => userXpSummarySchema.parse(summaries.get(user.id) ?? {
+        userId: user.id,
+        totalXp: 0,
+        weeklyXp: 0,
+        rewardEventCount: 0,
+        lastRewardAt: null
+    }));
+}
+export function findUserByLabel(label) {
+    const normalizedLabel = label.trim().toLowerCase();
+    if (!normalizedLabel) {
+        return undefined;
+    }
+    const row = getDatabase()
+        .prepare(`SELECT id, kind, handle, display_name, description, accent_color, created_at, updated_at
+       FROM users
+       WHERE lower(display_name) = ?
+          OR lower(handle) = ?
+       ORDER BY CASE kind WHEN 'human' THEN 0 ELSE 1 END, created_at ASC
+       LIMIT 1`)
+        .get(normalizedLabel, normalizeHandle(normalizedLabel));
+    return row ? mapUser(row) : undefined;
+}
+export function getDefaultUser() {
+    return (getUserById("user_operator") ??
+        listUsers({ kind: "human" })[0] ??
+        listUsers()[0] ??
+        (() => {
+            throw new Error("Forge has no configured users");
+        })());
+}
+export function resolveUserForMutation(userId, fallbackLabel) {
+    if (userId) {
+        const user = getUserById(userId);
+        if (!user) {
+            throw new Error(`User ${userId} does not exist`);
+        }
+        return user;
+    }
+    if (fallbackLabel) {
+        const matched = findUserByLabel(fallbackLabel);
+        if (matched) {
+            return matched;
+        }
+    }
+    return getDefaultUser();
+}
+export function createUser(input) {
+    const parsed = createUserSchema.parse({
+        ...input,
+        handle: normalizeHandle(input.handle || input.displayName)
+    });
+    const now = new Date().toISOString();
+    const id = `user_${randomUUID().replaceAll("-", "").slice(0, 10)}`;
+    getDatabase()
+        .prepare(`INSERT INTO users (id, kind, handle, display_name, description, accent_color, created_at, updated_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?)`)
+        .run(id, parsed.kind, parsed.handle, parsed.displayName, parsed.description, parsed.accentColor, now, now);
+    ensurePermissiveGrantsForUser(id, now);
+    return getUserById(id);
+}
+export function updateUser(userId, patch) {
+    const current = getUserById(userId);
+    if (!current) {
+        return undefined;
+    }
+    const parsed = updateUserSchema.parse(patch);
+    const next = {
+        kind: parsed.kind ?? current.kind,
+        handle: normalizeHandle(parsed.handle ?? current.handle),
+        displayName: parsed.displayName ?? current.displayName,
+        description: parsed.description ?? current.description,
+        accentColor: parsed.accentColor ?? current.accentColor,
+        updatedAt: new Date().toISOString()
+    };
+    getDatabase()
+        .prepare(`UPDATE users
+       SET kind = ?, handle = ?, display_name = ?, description = ?, accent_color = ?, updated_at = ?
+       WHERE id = ?`)
+        .run(next.kind, next.handle, next.displayName, next.description, next.accentColor, next.updatedAt, userId);
+    return getUserById(userId);
+}
+export function updateUserAccessGrant(grantId, patch) {
+    const current = listUserAccessGrants().find((grant) => grant.id === grantId);
+    if (!current) {
+        return undefined;
+    }
+    const parsed = updateUserAccessGrantSchema.parse(patch);
+    const nextConfig = normalizeGrantConfig({
+        ...current.config,
+        rights: {
+            ...current.config.rights,
+            ...(parsed.rights ?? {})
+        }
+    }, { self: current.subjectUserId === current.targetUserId });
+    const nextAccessLevel = parsed.accessLevel ?? deriveAccessLevel(nextConfig);
+    const now = new Date().toISOString();
+    getDatabase()
+        .prepare(`UPDATE user_access_grants
+       SET access_level = ?, config_json = ?, updated_at = ?
+       WHERE id = ?`)
+        .run(nextAccessLevel, JSON.stringify(nextConfig), now, grantId);
+    return listUserAccessGrants().find((grant) => grant.id === grantId);
+}