@samirosamsam/aim 0.1.0

package/src/engine.js

@@ -0,0 +1,685 @@
+const PROVIDER_ALIASES = {
+  notion: ["notion"],
+  github: ["github", "git hub"],
+  slack: ["slack"],
+  linear: ["linear"],
+  drive: ["google drive", "gdrive", "drive"],
+  gmail: ["gmail", "mail", "email"],
+};
+
+const ACTION_ALIASES = {
+  read: ["read", "lire", "voir", "consulter", "search", "chercher", "list", "lister"],
+  write: ["write", "ecrire", "edit", "modifier", "update", "create", "creer", "publish", "publier"],
+  delete: ["delete", "remove", "supprimer", "effacer"],
+};
+
+export function createStore(seed = {}) {
+  return {
+    users: clone(seed.users ?? []),
+    agents: clone(seed.agents ?? []),
+    connections: clone(seed.connections ?? []),
+    grants: clone(seed.grants ?? []),
+    decisions: clone(seed.decisions ?? []),
+  };
+}
+
+export function createPolicy(seed = {}) {
+  return {
+    version: seed.version ?? 1,
+    grants: clone(seed.grants ?? []),
+    decisions: clone(seed.decisions ?? []),
+  };
+}
+
+export function registerAgent(store, { ownerUserId, name, type = "custom" }) {
+  const owner = store.users.find((user) => user.id === ownerUserId);
+  if (!owner) throw new Error(`Unknown owner: ${ownerUserId}`);
+  const uid = `spiffe://local/agent/${slug(owner.email.split("@")[0])}/${slug(name)}`;
+  const agent = {
+    uid,
+    ownerUserId,
+    displayName: name,
+    agentType: type,
+    status: "active",
+    createdAt: now(),
+    lastSeenAt: null,
+  };
+  store.agents.push(agent);
+  return agent;
+}
+
+export function connectProvider(store, { userId, provider, scopes = [], upstreamMcpUrl = "" }) {
+  const connection = {
+    id: `conn_${slug(provider)}_${store.connections.length + 1}`,
+    userId,
+    provider: slug(provider),
+    upstreamMcpUrl,
+    vaultRef: `vault://${slug(provider)}/${store.connections.length + 1}`,
+    scopesGranted: scopes,
+    createdAt: now(),
+  };
+  store.connections.push(connection);
+  return connection;
+}
+
+export function compileGrantPrompt(prompt, context = {}) {
+  const normalized = normalize(prompt);
+  const providers = detectProviders(normalized);
+  const actions = detectActions(normalized);
+  const effect = detectEffect(normalized);
+  const resourcePattern = detectResource(prompt, normalized);
+  const toolPattern = detectToolPattern(normalized, actions, providers, resourcePattern);
+  const questions = [];
+
+  if (providers.includes("*")) questions.push("Choose which SaaS connection this rule applies to.");
+  if (resourcePattern === "*") questions.push("Specify the exact resource pattern before enforcing.");
+
+  const drafts = providers.flatMap((provider) => {
+    const matchingConnections = provider === "*"
+      ? context.connections ?? []
+      : (context.connections ?? []).filter((connection) => connection.provider === provider);
+    const connectionIds = matchingConnections.length > 0 ? matchingConnections.map((c) => c.id) : [`${provider}:*`];
+
+    return connectionIds.flatMap((connectionId) =>
+      actions.map((access) => ({
+        id: `draft_${hash(`${prompt}:${connectionId}:${access}`)}`,
+        agentUid: context.agentUid ?? "",
+        connectionId,
+        provider,
+        toolPattern,
+        resourcePattern,
+        access: access === "delete" ? "write" : access,
+        effect,
+        expiresAt: null,
+        reason: reasonFor(effect, access, resourcePattern),
+        sourcePrompt: prompt,
+        confidence: confidenceFor(provider, resourcePattern),
+      })),
+    );
+  });
+
+  return { drafts, questions };
+}
+
+export function commitGrantDraft(store, draft, { agentUid, grantedBy }) {
+  const grant = materializeGrantDraft(draft, { agentUid, grantedBy });
+  store.grants = store.grants.filter((existing) => existing.id !== grant.id);
+  store.grants.push(grant);
+  return grant;
+}
+
+export function addGrantDraft(policy, draft, { agentUid, grantedBy = "codex", connectionId } = {}) {
+  const grant = materializeGrantDraft(draft, { agentUid, grantedBy, connectionId });
+  policy.grants = (policy.grants ?? []).filter((existing) => existing.id !== grant.id);
+  policy.grants.push(grant);
+  return grant;
+}
+
+export function deriveMcpCall({ agentUid = "", connectionId = "", provider = "", tool, args = {}, access, resource }) {
+  const normalizedProvider = slug(provider || providerFromConnectionId(connectionId));
+  const normalizedTool = normalizeToolName(tool);
+  const inferred = inferMcpCall(normalizedProvider, normalizedTool, args);
+  return {
+    agentUid,
+    connectionId: connectionId || `${normalizedProvider}:*`,
+    provider: normalizedProvider,
+    tool: normalizedTool,
+    resource: resource ?? inferred.resource,
+    access: access ?? inferred.access,
+    params: args,
+  };
+}
+
+export function draftGrantFromCall(call, { effect = "allow", strictTool = false, reason } = {}) {
+  const access = call.access === "delete" ? "write" : call.access;
+  const resourcePattern = call.resource ?? "*";
+  return {
+    id: `draft_${hash(`${call.agentUid}:${call.connectionId}:${call.tool}:${resourcePattern}:${access}:${effect}`)}`,
+    agentUid: call.agentUid,
+    connectionId: call.connectionId,
+    provider: call.provider,
+    toolPattern: strictTool ? call.tool : "*",
+    resourcePattern,
+    access,
+    effect,
+    expiresAt: null,
+    reason: reason ?? reasonFor(effect, access, resourcePattern),
+    sourcePrompt: `mcp:${call.provider}:${call.tool}`,
+    confidence: confidenceFor(call.provider, resourcePattern),
+  };
+}
+
+export function compileCodexRulePrompt(prompt, context = {}) {
+  const normalized = normalize(prompt);
+  const requestedEffect = detectEffect(normalized);
+  const effect = requestedEffect === "allow" ? "deny" : requestedEffect;
+  const agentUid = context.agentUid ?? "codex";
+  const drafts = [];
+  const questions = [];
+
+  for (const command of detectCommands(prompt, normalized)) {
+    drafts.push({
+      id: `draft_${hash(`${agentUid}:codex:local:Bash:bash/${command}:write:${effect}`)}`,
+      agentUid,
+      connectionId: "codex:local",
+      provider: "codex",
+      toolPattern: "Bash",
+      resourcePattern: `bash/${command}`,
+      access: inferAccess(command),
+      effect,
+      expiresAt: null,
+      reason: reasonFor(effect, inferAccess(command), `bash/${command}`),
+      sourcePrompt: prompt,
+      confidence: 0.9,
+    });
+  }
+
+  for (const file of detectFiles(prompt, normalized)) {
+    for (const [toolPattern, resourcePattern] of [
+      ["apply_patch", `file/${file}`],
+      ["Bash", `bash/*${file}*`],
+    ]) {
+      drafts.push({
+        id: `draft_${hash(`${agentUid}:codex:local:${toolPattern}:${resourcePattern}:write:${effect}`)}`,
+        agentUid,
+        connectionId: "codex:local",
+        provider: "codex",
+        toolPattern,
+        resourcePattern,
+        access: "write",
+        effect,
+        expiresAt: null,
+        reason: reasonFor(effect, "write", resourcePattern),
+        sourcePrompt: prompt,
+        confidence: 0.85,
+      });
+    }
+  }
+
+  if (normalized.includes("github") && normalized.includes("collaborator")) {
+    drafts.push({
+      id: `draft_${hash(`${agentUid}:github:*:*collaborator*:repo/*/collaborators/*:write:${effect}`)}`,
+      agentUid,
+      connectionId: "github:*",
+      provider: "github",
+      toolPattern: "*collaborator*",
+      resourcePattern: "repo/*/collaborators/*",
+      access: "write",
+      effect,
+      expiresAt: null,
+      reason: reasonFor(effect, "write", "repo/*/collaborators/*"),
+      sourcePrompt: prompt,
+      confidence: 0.8,
+    });
+  }
+
+  if (drafts.length === 0) {
+    questions.push("Specify a Bash command, file path, or MCP provider/tool/resource to block.");
+  }
+
+  return { drafts: uniqueDrafts(drafts), questions };
+}
+
+export function deriveCodexHookCalls(event, { agentUid = "codex" } = {}) {
+  const toolName = event.tool_name ?? event.toolName ?? "";
+  const input = event.tool_input ?? event.toolInput ?? {};
+
+  if (toolName === "Bash") {
+    const command = cleanCommand(input.command ?? "");
+    return [{
+      agentUid,
+      connectionId: "codex:local",
+      provider: "codex",
+      tool: "Bash",
+      resource: `bash/${command}`,
+      access: inferAccess(command),
+      params: input,
+    }];
+  }
+
+  if (toolName === "apply_patch") {
+    return touchedFiles(input.command ?? input.patch ?? "").map((file) => ({
+      agentUid,
+      connectionId: "codex:local",
+      provider: "codex",
+      tool: "apply_patch",
+      resource: `file/${file.path}`,
+      access: file.deleted ? "delete" : "write",
+      params: input,
+    }));
+  }
+
+  if (toolName.startsWith("mcp__")) {
+    const provider = providerFromMcpTool(toolName);
+    return [deriveMcpCall({
+      agentUid,
+      connectionId: `${provider}:codex`,
+      provider,
+      tool: toolName,
+      args: input,
+    })];
+  }
+
+  return [{
+    agentUid,
+    connectionId: "codex:local",
+    provider: "codex",
+    tool: toolName,
+    resource: `tool/${normalizeToolName(toolName)}`,
+    access: inferAccess(toolName),
+    params: input,
+  }];
+}
+
+export function evaluateCodexHook(policy, event, options = {}) {
+  const calls = deriveCodexHookCalls(event, options);
+  for (const call of calls) {
+    const decision = evaluateGuardCall(policy, call);
+    if (decision.decision !== "allow") return { ...decision, call };
+  }
+  return { decision: "allow", reason: "no-matching-block", calls };
+}
+
+export function evaluateGuardCall(policy, call) {
+  const started = Date.now();
+  const matches = activeGrants(policy.grants ?? []).filter((grant) => grantMatches(grant, call));
+  const deny = matches.find((grant) => grant.effect === "deny");
+  const approval = matches.find((grant) => grant.effect === "approval");
+  const match = deny ?? approval;
+
+  if (!match) {
+    return {
+      decision: "allow",
+      reason: "no-matching-block",
+      matchedGrantId: null,
+      latencyMs: Date.now() - started,
+    };
+  }
+
+  return {
+    decision: "deny",
+    reason: match.effect === "approval" ? `Approval required: ${match.reason}` : match.reason,
+    matchedGrantId: match.id,
+    latencyMs: Date.now() - started,
+  };
+}
+
+export function evaluateToolCall(store, call) {
+  const started = Date.now();
+  const agent = store.agents.find((candidate) => candidate.uid === call.agentUid);
+  const connection = store.connections.find((candidate) => candidate.id === call.connectionId);
+  let decision = "deny";
+  let reason = "default-deny";
+  let matchedGrantId = null;
+
+  if (!agent) {
+    reason = "unknown-agent";
+  } else if (agent.status !== "active") {
+    reason = `agent-${agent.status}`;
+  } else if (!connection) {
+    reason = "unknown-connection";
+  } else {
+    agent.lastSeenAt = now();
+    const matches = activeGrants(store.grants).filter((grant) => grantMatches(grant, call));
+    const deny = matches.find((grant) => grant.effect === "deny");
+    const approval = matches.find((grant) => grant.effect === "approval");
+    const allow = matches.find((grant) => grant.effect === "allow");
+
+    if (deny) {
+      matchedGrantId = deny.id;
+      reason = deny.reason;
+    } else if (approval) {
+      decision = "approval_required";
+      matchedGrantId = approval.id;
+      reason = approval.reason;
+    } else if (allow) {
+      decision = "allow";
+      matchedGrantId = allow.id;
+      reason = allow.reason;
+    }
+  }
+
+  const row = {
+    id: `decision_${store.decisions.length + 1}`,
+    ts: now(),
+    agentUid: call.agentUid,
+    ownerUserId: agent?.ownerUserId ?? null,
+    connectionId: call.connectionId,
+    toolCalled: call.tool,
+    resource: call.resource,
+    access: call.access,
+    paramsDigest: hash(JSON.stringify(call.params ?? {})),
+    decision,
+    reason,
+    matchedGrantId,
+    latencyMs: Date.now() - started,
+  };
+  store.decisions.unshift(row);
+  return row;
+}
+
+export function evaluatePolicyCall(policy, call) {
+  const started = Date.now();
+  let decision = "deny";
+  let reason = "default-deny";
+  let matchedGrantId = null;
+  const matches = activeGrants(policy.grants ?? []).filter((grant) => grantMatches(grant, call));
+  const deny = matches.find((grant) => grant.effect === "deny");
+  const approval = matches.find((grant) => grant.effect === "approval");
+  const allow = matches.find((grant) => grant.effect === "allow");
+
+  if (deny) {
+    matchedGrantId = deny.id;
+    reason = deny.reason;
+  } else if (approval) {
+    decision = "approval_required";
+    matchedGrantId = approval.id;
+    reason = approval.reason;
+  } else if (allow) {
+    decision = "allow";
+    matchedGrantId = allow.id;
+    reason = allow.reason;
+  }
+
+  const row = {
+    id: `decision_${(policy.decisions ?? []).length + 1}`,
+    ts: now(),
+    agentUid: call.agentUid,
+    ownerUserId: null,
+    connectionId: call.connectionId,
+    toolCalled: call.tool,
+    resource: call.resource,
+    access: call.access,
+    paramsDigest: hash(JSON.stringify(call.params ?? {})),
+    decision,
+    reason,
+    matchedGrantId,
+    latencyMs: Date.now() - started,
+  };
+  policy.decisions ??= [];
+  policy.decisions.unshift(row);
+  return row;
+}
+
+export function summarizeAgentAccess(store, agentUid) {
+  return store.grants
+    .filter((grant) => grant.agentUid === agentUid)
+    .map((grant) => {
+      const connection = store.connections.find((candidate) => candidate.id === grant.connectionId);
+      return {
+        ...grant,
+        provider: connection?.provider ?? "unknown",
+      };
+    });
+}
+
+function activeGrants(grants) {
+  const current = Date.now();
+  return grants.filter((grant) => !grant.expiresAt || Date.parse(grant.expiresAt) > current);
+}
+
+function grantMatches(grant, call) {
+  return (
+    grant.agentUid === call.agentUid &&
+    wildcard(grant.connectionId, call.connectionId) &&
+    wildcard(grant.toolPattern, call.tool) &&
+    wildcard(grant.resourcePattern, call.resource) &&
+    (grant.access === call.access || grant.access === "write" && call.access === "delete")
+  );
+}
+
+function materializeGrantDraft(draft, { agentUid, grantedBy, connectionId }) {
+  const resolvedAgentUid = agentUid ?? draft.agentUid;
+  const resolvedConnectionId = connectionId ?? draft.connectionId;
+  if (!resolvedAgentUid) throw new Error("Grant requires an agent UID.");
+  if (!resolvedConnectionId) throw new Error("Grant requires a connection ID or pattern.");
+  return {
+    id: `grant_${hash(`${resolvedAgentUid}:${resolvedConnectionId}:${draft.toolPattern}:${draft.resourcePattern}:${draft.access}:${draft.effect}`)}`,
+    agentUid: resolvedAgentUid,
+    connectionId: resolvedConnectionId,
+    provider: draft.provider ?? providerFromConnectionId(resolvedConnectionId),
+    toolPattern: draft.toolPattern,
+    resourcePattern: draft.resourcePattern,
+    access: draft.access,
+    effect: draft.effect,
+    grantedBy,
+    expiresAt: draft.expiresAt,
+    reason: draft.reason,
+    sourcePrompt: draft.sourcePrompt,
+    createdAt: now(),
+  };
+}
+
+function detectProviders(normalized) {
+  const found = Object.entries(PROVIDER_ALIASES)
+    .filter(([, aliases]) => aliases.some((alias) => normalized.includes(alias)))
+    .map(([provider]) => provider);
+  return found.length > 0 ? found : ["*"];
+}
+
+function detectActions(normalized) {
+  const found = Object.entries(ACTION_ALIASES)
+    .filter(([, aliases]) => aliases.some((alias) => normalized.includes(alias)))
+    .map(([action]) => action);
+  if (found.includes("delete")) return ["delete"];
+  return found.length > 0 ? found : ["read"];
+}
+
+function detectEffect(normalized) {
+  if (/\b(approval|approve|validation|validate|valider|escalate|escalade|ask|demande)\b/.test(normalized)) {
+    return "approval";
+  }
+  if (/\b(block|bloque|bloquer|deny|interdit|interdire|jamais|never|pas acces|pas accès|no access|empeche|empecher|empêche|empêcher|prevent)\b/.test(normalized)) {
+    return "deny";
+  }
+  return "allow";
+}
+
+function detectToolPattern(normalized, actions, providers, resourcePattern) {
+  if (normalized.includes("issue")) return "issues.*";
+  if (normalized.includes("page") || providers.includes("notion") && resourcePattern.startsWith("workspace/")) return "pages.*";
+  if (normalized.includes("channel") || resourcePattern.startsWith("channel/")) return "channels.*";
+  if (normalized.includes("search") || normalized.includes("chercher")) return "search";
+  if (actions.includes("delete")) return "*.delete";
+  return "*";
+}
+
+function detectResource(original, normalized) {
+  const quoted = original.match(/["'`](.+?)["'`]/);
+  if (quoted?.[1]) return quoted[1].trim();
+  const channel = original.match(/#([\w-]+)/);
+  if (channel?.[1]) return `channel/${channel[1]}`;
+  const repo = normalized.match(/\b([\w.-]+\/[\w.-]+)\b/);
+  if (repo?.[1]) return `repo/${repo[1]}`;
+  for (const marker of ["legal", "finance", "financial", "hr", "rh", "private", "prive", "privé"]) {
+    if (normalized.includes(marker)) return `sensitive/${marker}`;
+  }
+  return "*";
+}
+
+function inferMcpCall(provider, tool, args) {
+  if (provider === "github") return inferGithubCall(tool, args);
+  if (provider === "notion") return inferNotionCall(tool, args);
+  if (provider === "slack") return inferSlackCall(tool, args);
+  if (provider === "linear") return inferLinearCall(tool, args);
+  return {
+    access: inferAccess(tool),
+    resource: inferGenericResource(provider, tool, args),
+  };
+}
+
+function inferGithubCall(tool, args) {
+  if (tool.includes("collaborator")) return { access: inferAccess(tool), resource: githubRepo(args, "/collaborators/*") };
+  if (tool.includes("pull_request") || tool.includes("pull_requests")) {
+    const pull = cleanPart(args.pullNumber ?? args.pull_number);
+    return { access: inferAccess(tool), resource: githubRepo(args, `/pull_requests/${pull || "*"}`) };
+  }
+  if (tool.includes("branch")) {
+    const branch = cleanPart(args.branch ?? args.from_branch);
+    const suffix = branch ? `/branches/${branch}` : "/branches/*";
+    return { access: inferAccess(tool), resource: githubRepo(args, suffix) };
+  }
+  if (tool.includes("issue")) {
+    const issue = cleanPart(args.issue_number ?? args.issueNumber);
+    return { access: inferAccess(tool), resource: githubRepo(args, `/issues/${issue || "*"}`) };
+  }
+  if (tool === "push_files" || tool === "create_or_update_file" || tool === "delete_file") {
+    const file = cleanPath(args.path);
+    return { access: tool === "delete_file" ? "delete" : "write", resource: githubRepo(args, `/files/${file || "*"}`) };
+  }
+  return { access: inferAccess(tool), resource: githubRepo(args) };
+}
+
+function inferNotionCall(tool, args) {
+  const page = cleanPart(args.page_id ?? args.pageId ?? args.id);
+  const database = cleanPart(args.database_id ?? args.databaseId);
+  if (page) return { access: inferAccess(tool), resource: `notion/pages/${page}` };
+  if (database) return { access: inferAccess(tool), resource: `notion/databases/${database}` };
+  return { access: inferAccess(tool), resource: args.resource ? cleanPath(args.resource) : "notion/*" };
+}
+
+function inferSlackCall(tool, args) {
+  const channel = cleanPart(args.channel ?? args.channel_id ?? args.channelId);
+  return { access: inferAccess(tool), resource: channel ? `slack/channels/${channel}` : "slack/*" };
+}
+
+function inferLinearCall(tool, args) {
+  const issue = cleanPart(args.issue_id ?? args.issueId ?? args.id);
+  const team = cleanPart(args.team_id ?? args.teamId);
+  if (issue) return { access: inferAccess(tool), resource: `linear/issues/${issue}` };
+  if (team) return { access: inferAccess(tool), resource: `linear/teams/${team}` };
+  return { access: inferAccess(tool), resource: "linear/*" };
+}
+
+function inferGenericResource(provider, tool, args) {
+  if (args.resource) return cleanPath(args.resource);
+  if (args.owner && args.repo) return githubRepo(args);
+  if (args.channel) return `channel/${cleanPart(args.channel)}`;
+  return `${provider}/${tool}`;
+}
+
+function inferAccess(tool) {
+  if (/delete|remove|trash|archive/.test(tool)) return "delete";
+  if (/add|create|update|edit|write|push|merge|send|post|publish|invite|modify|modifier|touch|mv|cp|rm|>|tee/.test(tool)) return "write";
+  return "read";
+}
+
+function githubRepo(args, suffix = "") {
+  const owner = cleanPart(args.owner ?? args.repository_owner);
+  const repo = cleanPart(args.repo ?? args.repository);
+  return owner && repo ? `repo/${owner}/${repo}${suffix}` : "*";
+}
+
+function reasonFor(effect, access, resourcePattern) {
+  if (effect === "deny") return `Block ${access} on ${resourcePattern}.`;
+  if (effect === "approval") return `Require human approval for ${access} on ${resourcePattern}.`;
+  return `Allow ${access} on ${resourcePattern}.`;
+}
+
+function confidenceFor(provider, resourcePattern) {
+  let score = 0.55;
+  if (provider !== "*") score += 0.2;
+  if (resourcePattern !== "*") score += 0.2;
+  return Math.min(score, 0.95);
+}
+
+function wildcard(pattern, value) {
+  if (pattern === "*") return true;
+  const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*");
+  return new RegExp(`^${escaped}$`, "i").test(value);
+}
+
+function providerFromConnectionId(connectionId) {
+  return String(connectionId).split(/[:_]/)[0] || "unknown";
+}
+
+function providerFromMcpTool(toolName) {
+  return cleanPart(String(toolName).split("__")[1] ?? providerFromConnectionId(toolName));
+}
+
+function normalizeToolName(tool) {
+  return normalize(tool)
+    .replace(/^mcp__[^_]+__/, "")
+    .replace(/^mcp__[^.]+\./, "")
+    .replace(/[^a-z0-9_.-]+/g, "_");
+}
+
+function detectCommands(original, normalized) {
+  const commands = [];
+  if (normalized.includes("git push")) commands.push("git push*");
+  for (const match of original.matchAll(/[`'"]([^`'"]+)[`'"]/g)) {
+    const command = cleanCommand(match[1]);
+    if (/^(git|rm|mv|cp|npm|pnpm|bun|yarn|curl|ssh)\b/.test(command)) commands.push(`${command}*`);
+  }
+  return [...new Set(commands)];
+}
+
+function detectFiles(original, normalized) {
+  const files = [];
+  for (const match of original.matchAll(/(?:^|\s)([.\w/-]+\.[a-z0-9]+)(?=\s|$|[.,;:!?])/gi)) {
+    files.push(cleanPath(match[1]));
+  }
+  if (normalized.includes("package.json")) files.push("package.json");
+  if (normalized.includes(".env")) files.push(".env");
+  return [...new Set(files.filter(Boolean))];
+}
+
+function touchedFiles(patch) {
+  const files = [];
+  for (const match of String(patch).matchAll(/^\*\*\* (Update|Add|Delete) File: (.+)$/gm)) {
+    files.push({ path: cleanPath(match[2]), deleted: match[1] === "Delete" });
+  }
+  return files;
+}
+
+function cleanCommand(command) {
+  return normalize(command).replace(/\s+/g, " ");
+}
+
+function uniqueDrafts(drafts) {
+  const seen = new Set();
+  return drafts.filter((draft) => {
+    const key = `${draft.connectionId}:${draft.toolPattern}:${draft.resourcePattern}:${draft.access}:${draft.effect}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+function cleanPart(value) {
+  if (value === undefined || value === null || value === "") return "";
+  return normalize(value).replace(/[^a-z0-9_.-]+/g, "-").replace(/(^-|-$)/g, "");
+}
+
+function cleanPath(value) {
+  return String(value ?? "")
+    .split("/")
+    .map(cleanPart)
+    .filter(Boolean)
+    .join("/");
+}
+
+function slug(value) {
+  return normalize(value).replace(/[^a-z0-9]+/g, "-").replace(/(^-|-$)/g, "") || "unknown";
+}
+
+function normalize(value) {
+  return String(value).normalize("NFD").replace(/[\u0300-\u036f]/g, "").toLowerCase().trim();
+}
+
+function hash(value) {
+  let h = 2166136261;
+  for (const char of String(value)) {
+    h ^= char.charCodeAt(0);
+    h = Math.imul(h, 16777619);
+  }
+  return (h >>> 0).toString(16);
+}
+
+function now() {
+  return new Date().toISOString();
+}
+
+function clone(value) {
+  return JSON.parse(JSON.stringify(value));
+}