Open-source Grok Bot alternative for named AI teammates. Local-first desktop, web, and mobile clients with per-bot tools, instructions, and memory. Independent fork of T3 Code.
import * as Predicate from "effect/Predicate";
import * as NodeCrypto from "node:crypto";
import { AkeruMemoryEntityId, AkeruMemoryRevision, AkeruMemoryRootId } from "@akeru/contracts";
import * as Effect from "effect/Effect";
import { toPersistenceSqlError } from "../../persistence/Errors.ts";
import {
AkeruMemoryAccessDenied,
resolveAuthorizedMemoryPartitions,
type AuthorizedMemoryPartition,
} from "../EntityMemoryAccess.ts";
import {
type EntityMemoryRepositoryShape,
EntityMemoryImportError,
} from "../Services/EntityMemoryRepository.ts";
import { encodeMemoryArchiveJson } from "../MemoryArchiveJson.ts";
import { EntityMemoryDbRow, selectColumns, encodeJson, decodeRow } from "./EntityMemoryRows.ts";
import type { EntityMemoryStorageServices } from "./EntityMemoryStorage.ts";
import type { EntityMemoryQueriesServices } from "./EntityMemoryQueries.ts";
export const entityMemoryImport = (dependencies: {
sql: EntityMemoryStorageServices["sql"];
writeLock: EntityMemoryStorageServices["writeLock"];
insertRow: EntityMemoryStorageServices["insertRow"];
expectedEntity: EntityMemoryStorageServices["expectedEntity"];
invalidateDerivedCopies: EntityMemoryStorageServices["invalidateDerivedCopies"];
isRevisionAuthorized: EntityMemoryQueriesServices["isRevisionAuthorized"];
}) =>
Effect.sync(() => {
const {
sql,
writeLock,
insertRow,
expectedEntity,
invalidateDerivedCopies,
isRevisionAuthorized,
} = dependencies;
const fingerprint = (revision: AkeruMemoryRevision, prefix = false) => {
const value = prefix ? { ...revision, updatedAt: null, supersededById: null } : revision;
return NodeCrypto.createHash("sha256").update(encodeMemoryArchiveJson(value)).digest("hex");
};
const normalizeImport = Effect.fn("EntityMemoryRepository.normalizeImport")(function* (input: {
readonly access: Parameters<typeof resolveAuthorizedMemoryPartitions>[0];
readonly partitions: ReadonlyArray<AuthorizedMemoryPartition>;
readonly revisions: ReadonlyArray<AkeruMemoryRevision>;
}) {
const authorized = yield* resolveAuthorizedMemoryPartitions(input.access);
const isAuthorized = (candidate: AuthorizedMemoryPartition) =>
authorized.some(
(allowed) =>
allowed.tenantId === candidate.tenantId &&
allowed.scope === candidate.scope &&
allowed.partitionId === candidate.partitionId &&
allowed.visibility === candidate.visibility,
);
if (
input.partitions.length === 0 ||
input.partitions.some((candidate) => !isAuthorized(candidate))
) {
return yield* new AkeruMemoryAccessDenied({
reason: "The import target is not authorized for this thread.",
});
}
const botPartition = input.partitions.find((candidate) => candidate.scope === "bot");
const botUserPartition = input.partitions.find((candidate) => candidate.scope === "bot-user");
const isBotAuthorityPair =
input.partitions.length === 2 &&
botPartition !== undefined &&
botUserPartition !== undefined &&
botPartition.visibility === "private" &&
botUserPartition.visibility === "private";
if (input.partitions.length !== 1 && !isBotAuthorityPair) {
return yield* new AkeruMemoryAccessDenied({
reason: "Import one thread, bot, project, or workspace authority domain at a time.",
});
}
const authorBotId = input.access.respondingBotId ?? input.access.botId;
const normalized: AkeruMemoryRevision[] = [];
for (const revision of input.revisions) {
const selected =
input.partitions.length === 1
? input.partitions[0]
: revision.entityKind === "user"
? botUserPartition
: botPartition;
if (!selected) {
return yield* new AkeruMemoryAccessDenied({
reason: "An imported memory scope is not valid for the selected target.",
});
}
const matchesRevision = (partition: AuthorizedMemoryPartition) =>
partition.scope === revision.partition.scope &&
partition.partitionId === revision.partition.partitionId &&
partition.tenantId === revision.partition.tenantId &&
partition.visibility === revision.visibility;
// Superseded revisions may predate a scope move, so they are checked against the
// authorized partition they were written in and then rehomed with the fact.
const sourcePartition =
input.partitions.find(matchesRevision) ??
(revision.supersededById === null ? undefined : authorized.find(matchesRevision));
const owner =
sourcePartition === undefined || input.partitions.includes(sourcePartition)
? selected
: sourcePartition;
const expectedEntityId =
owner.scope === "project"
? input.access.projectId
: owner.scope === "workspace"
? owner.partitionId
: owner.scope === "bot"
? input.access.botId
: owner.scope === "user"
? input.access.userId
: owner.scope === "bot-user"
? input.access.userId
: owner.scope === "thread" && input.access.groupId !== null
? input.access.groupId
: owner.scope === "thread" && input.access.botId !== null
? input.access.botId
: input.access.projectId;
const expectedAffected =
owner.visibility === "shared"
? new Set([
...input.access.groupMemberBotIds,
...(authorBotId === null ? [] : [authorBotId]),
])
: new Set(authorBotId === null ? [] : [authorBotId]);
const isProjectOwner = owner.scope === "project" && owner.visibility === "shared";
if (
!sourcePartition ||
String(revision.entityId) !== String(expectedEntityId) ||
revision.entityKind !==
expectedEntity(input.access, { ...revision, partition: owner })?.kind ||
(!isProjectOwner &&
(revision.initiatingUserId !== input.access.userId ||
(revision.authorBotId !== null &&
authorBotId !== null &&
revision.authorBotId !== authorBotId) ||
revision.affectedBotIds.some((botId) => !expectedAffected.has(botId)) ||
revision.affectedBotIds.length !== expectedAffected.size))
) {
return yield* new AkeruMemoryAccessDenied({
reason: "The archive record belongs to a different memory owner.",
});
}
// A revision written before a scope move keeps the validated scope it was written in.
if (owner !== selected) {
normalized.push(
isProjectOwner
? revision
: { ...revision, authorBotId, initiatingUserId: input.access.userId },
);
continue;
}
const sharedBotIds = [
...new Set([
...input.access.groupMemberBotIds,
...(authorBotId === null ? [] : [authorBotId]),
]),
];
const affectedBotIds =
selected.visibility === "shared"
? sharedBotIds
: authorBotId === null
? []
: [authorBotId];
const entity =
selected.scope === "project"
? {
entityKind: "project" as const,
entityId: AkeruMemoryEntityId.make(input.access.projectId),
}
: selected.scope === "workspace"
? {
entityKind: "workspace" as const,
entityId: AkeruMemoryEntityId.make(selected.partitionId),
}
: selected.scope === "bot-user" || selected.scope === "user"
? {
entityKind: "user" as const,
entityId: AkeruMemoryEntityId.make(input.access.userId),
}
: selected.scope === "bot"
? {
entityKind: "bot" as const,
entityId: AkeruMemoryEntityId.make(input.access.botId!),
}
: selected.scope === "thread" && input.access.groupId !== null
? {
entityKind: "group" as const,
entityId: AkeruMemoryEntityId.make(input.access.groupId),
}
: selected.scope === "thread" && input.access.botId !== null
? {
entityKind: "bot" as const,
entityId: AkeruMemoryEntityId.make(input.access.botId),
}
: {
entityKind: "project" as const,
entityId: AkeruMemoryEntityId.make(input.access.projectId),
};
normalized.push({
...revision,
partition: {
tenantId: input.access.tenantId,
scope: selected.scope,
partitionId: selected.partitionId,
},
...entity,
// Chat facts belong to the importing chat; wider facts keep the chat they came from.
sourceThreadId:
selected.scope === "thread" ? input.access.threadId : revision.sourceThreadId,
authorBotId: isProjectOwner ? revision.authorBotId : authorBotId,
initiatingUserId: isProjectOwner ? revision.initiatingUserId : input.access.userId,
visibility: selected.visibility,
affectedBotIds: isProjectOwner ? revision.affectedBotIds : affectedBotIds,
});
}
const roots = new Map<string, AkeruMemoryRevision[]>();
for (const revision of normalized) {
const history = roots.get(revision.rootId) ?? [];
history.push(revision);
roots.set(revision.rootId, history);
}
return [...roots.values()].flatMap((history) => {
const ordered = history.sort((left, right) => left.revision - right.revision);
const first = ordered[0]!;
if (
input.partitions.length !== 1 ||
input.partitions[0]?.scope !== "project" ||
first.revision === 1 ||
first.supersedesId === null ||
ordered.some(
(revision) =>
revision.partition.scope !== "project" || revision.id === first.supersedesId,
)
) {
return ordered;
}
return ordered.map((revision, index) => ({
...revision,
revision: revision.revision - first.revision + 1,
supersedesId: index === 0 ? null : revision.supersedesId,
}));
});
});
const invalidArchiveChainReason = "The archive revision chain is invalid.";
const buildImportPreview = Effect.fn("EntityMemoryRepository.buildImportPreview")(
function* (input: {
readonly access: Parameters<typeof resolveAuthorizedMemoryPartitions>[0];
readonly partitions: ReadonlyArray<AuthorizedMemoryPartition>;
readonly revisions: ReadonlyArray<AkeruMemoryRevision>;
}) {
const revisions = yield* normalizeImport(input);
const roots = new Map<string, Array<AkeruMemoryRevision>>();
for (const revision of revisions) {
const group = roots.get(revision.rootId) ?? [];
group.push(revision);
roots.set(revision.rootId, group);
}
const rootIds = [...roots.keys()];
const localRows =
rootIds.length === 0
? []
: yield* sql
.unsafe<EntityMemoryDbRow>(
`SELECT ${selectColumns} FROM akeru_memory_revisions
WHERE tenant_id = ? AND root_id IN (${rootIds.map(() => "?").join(", ")})
ORDER BY root_id ASC, revision ASC`,
[input.access.tenantId, ...rootIds],
)
.pipe(
Effect.mapError(
toPersistenceSqlError("EntityMemoryRepository.buildImportPreview:local"),
),
);
const local = yield* Effect.forEach(localRows, decodeRow);
const items = [...roots.entries()]
.sort(([left], [right]) => left.localeCompare(right))
.map(([rootId, unsorted]) => {
const incoming = [...unsorted].sort((left, right) => left.revision - right.revision);
const brandedRootId = incoming[0]?.rootId ?? AkeruMemoryRootId.make(rootId);
const current = local
.filter((revision) => revision.rootId === rootId)
.sort((left, right) => left.revision - right.revision);
const validChain = incoming.every(
(revision, index) =>
revision.revision === index + 1 &&
revision.supersedesId === (index === 0 ? null : incoming[index - 1]!.id) &&
revision.supersededById ===
(index === incoming.length - 1 ? null : incoming[index + 1]!.id),
);
if (!validChain) {
return {
rootId: brandedRootId,
classification: "conflicting" as const,
reason: invalidArchiveChainReason,
};
}
if (current.length === 0) {
return {
rootId: brandedRootId,
classification: "new" as const,
reason: "This memory does not exist locally.",
};
}
const exact =
current.length === incoming.length &&
current.every(
(revision, index) => fingerprint(revision) === fingerprint(incoming[index]!),
);
if (exact) {
return {
rootId: brandedRootId,
classification: "skipped" as const,
reason: "The local history is identical.",
};
}
const prefix =
current.length < incoming.length &&
current.every(
(revision, index) =>
fingerprint(revision, true) === fingerprint(incoming[index]!, true),
);
return prefix
? {
rootId: brandedRootId,
classification: "changed" as const,
reason: "The archive extends the local history.",
}
: {
rootId: brandedRootId,
classification: "conflicting" as const,
reason: "The local and archive histories diverge.",
};
});
const previewHash = NodeCrypto.createHash("sha256")
.update(
encodeJson({
items,
incoming: revisions.map((revision) => fingerprint(revision)),
local: local.map((revision) => fingerprint(revision)),
}),
)
.digest("hex");
return { previewHash, items, revisions, local };
},
);
const previewImport: EntityMemoryRepositoryShape["previewImport"] = (input) =>
buildImportPreview(input).pipe(
Effect.map(({ previewHash, items }) => ({ previewHash, items })),
);
const applyImport: EntityMemoryRepositoryShape["applyImport"] = (input) =>
writeLock.withPermit(
sql
.withTransaction(
Effect.gen(function* () {
const preview = yield* buildImportPreview(input);
if (preview.previewHash !== input.previewHash) {
return yield* new EntityMemoryImportError({
detail: "The memory import preview is stale. Preview the archive again.",
});
}
const requestedResolutions = input.resolutions ?? [];
const resolutions = new Map(
requestedResolutions.map((resolution) => [
String(resolution.rootId),
resolution.decision,
]),
);
if (resolutions.size !== requestedResolutions.length) {
return yield* new EntityMemoryImportError({
detail: "Each memory conflict may be resolved only once.",
});
}
const conflicts = preview.items.filter(
(item) => item.classification === "conflicting",
);
for (const conflict of conflicts) {
if (!resolutions.has(String(conflict.rootId))) {
return yield* new EntityMemoryImportError({
detail: `Choose keep-local or use-archive for ${conflict.rootId}.`,
});
}
}
for (const resolution of resolutions.keys()) {
if (
!preview.items.some(
(item) =>
String(item.rootId) === resolution && item.classification === "conflicting",
)
) {
return yield* new EntityMemoryImportError({
detail: `Resolution targets a non-conflicting memory: ${resolution}.`,
});
}
}
const authorized = yield* resolveAuthorizedMemoryPartitions(input.access);
for (const item of preview.items) {
if (item.classification === "skipped") continue;
const incoming = preview.revisions
.filter((revision) => revision.rootId === item.rootId)
.sort((left, right) => left.revision - right.revision);
const local = preview.local
.filter((revision) => revision.rootId === item.rootId)
.sort((left, right) => left.revision - right.revision);
const decision = resolutions.get(String(item.rootId));
if (item.classification === "conflicting" && decision === "keep-local") continue;
if (item.reason === invalidArchiveChainReason) {
return yield* new EntityMemoryImportError({
detail: `The archive history for ${item.rootId} is invalid and cannot replace local memory.`,
});
}
const additions =
item.classification === "conflicting" ? incoming : incoming.slice(local.length);
if (additions.length > 0) {
yield* invalidateDerivedCopies(input.access.tenantId, item.rootId);
}
if (item.classification === "conflicting" && decision === "use-archive") {
// Replacing a root deletes its whole local history, so every local revision
// must be authorized the same way permanent deletion requires.
if (!local.every(isRevisionAuthorized(authorized))) {
return yield* new AkeruMemoryAccessDenied({
reason: "Every historical revision must be authorized before it is replaced.",
});
}
yield* sql`
DELETE FROM akeru_memory_revisions
WHERE tenant_id = ${input.access.tenantId} AND root_id = ${item.rootId}
`;
}
if (item.classification !== "conflicting" && local.length > 0 && additions[0]) {
const updated = yield* sql<{ readonly id: string }>`
UPDATE akeru_memory_revisions
SET superseded_by_id = ${additions[0].id}, updated_at = ${additions[0].updatedAt}
WHERE memory_id = ${local.at(-1)!.id}
AND tenant_id = ${input.access.tenantId}
AND root_id = ${item.rootId}
AND revision = ${local.at(-1)!.revision}
AND superseded_by_id IS NULL
RETURNING memory_id AS id
`;
if (updated.length !== 1) {
return yield* new EntityMemoryImportError({
detail: "The local memory changed while the archive was applied.",
});
}
}
yield* Effect.forEach(additions, insertRow, { concurrency: 1 });
}
return {
imported: preview.items.filter((item) => item.classification === "new").length,
changed: preview.items.filter((item) => item.classification === "changed").length,
skipped: preview.items.filter((item) => item.classification === "skipped").length,
};
}),
)
.pipe(
Effect.mapError((cause) =>
Predicate.isTagged(cause, "EntityMemoryImportError") ||
Predicate.isTagged(cause, "AkeruMemoryAccessDenied")
? cause
: toPersistenceSqlError("EntityMemoryRepository.applyImport:query")(cause),
),
),
);
return { previewImport, applyImport };
});