engineering-memory 0.1.0

package/runtime/dist/src/runtime/active-context-store.js

@@ -0,0 +1,356 @@
+import { join } from 'node:path';
+import { readdir } from 'node:fs/promises';
+import { ensureManagedDirectory, readJson, removeFile, writeJson } from '../utilities/files.js';
+import { sha256, stableStringify } from '../utilities/hash.js';
+import { assertSafeToPersist } from './offline-outbox.js';
+export class ActiveContextStore {
+    root;
+    queues = new Map();
+    constructor(stateRoot) {
+        this.root = join(stateRoot, 'active-contexts');
+    }
+    async load(repoFingerprint) {
+        assertFingerprint(repoFingerprint);
+        const pointer = await readJson(this.pathFor(repoFingerprint), this.root);
+        if (!pointer) {
+            return null;
+        }
+        this.validate(pointer, repoFingerprint);
+        return pointer;
+    }
+    async save(input) {
+        await this.exclusive(input.repoFingerprint, async () => {
+            const existing = await readJson(this.pathFor(input.repoFingerprint), this.root);
+            const sameTask = existing?.taskId === input.taskId && existing.sessionId === input.sessionId;
+            if (!sameTask && (existing?.verificationIntent || existing?.closeIntent)) {
+                throw new Error('Pending lifecycle intent prevents replacing the active task pointer');
+            }
+            const { verificationIntent: _verificationIntent, closeIntent: _closeIntent, ...pointerInput } = input;
+            await this.writePointer({
+                ...pointerInput,
+                ...(sameTask && existing?.verificationIntent
+                    ? { verificationIntent: existing.verificationIntent }
+                    : {}),
+                ...(sameTask && existing?.closeIntent ? { closeIntent: existing.closeIntent } : {}),
+            });
+        });
+    }
+    async updateTaskSnapshot(taskId, taskVersion, lastSequence) {
+        await ensureManagedDirectory(this.root, this.root);
+        const entries = await readdir(this.root, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.name.endsWith('.json') && (!entry.isFile() || entry.isSymbolicLink())) {
+                throw new Error(`Unsafe active context entry: ${entry.name}`);
+            }
+            if (!entry.isFile() || !entry.name.endsWith('.json')) {
+                continue;
+            }
+            const pointer = await readJson(join(this.root, entry.name), this.root);
+            if (pointer?.taskId === taskId) {
+                await this.save({
+                    ...pointer,
+                    taskVersion,
+                    lastSequence,
+                });
+            }
+        }
+    }
+    async setChangeBaseline(repoFingerprint, sessionId, manifest, leasePaths, taskSnapshot) {
+        const pointer = await this.load(repoFingerprint);
+        if (!pointer ||
+            pointer.sessionId !== sessionId ||
+            (taskSnapshot && pointer.taskId !== taskSnapshot.taskId)) {
+            throw new Error('Change baseline does not match the active repository session');
+        }
+        if (pointer.changeBaseline?.leasePaths.some((path) => !leasePaths.includes(path))) {
+            throw new Error('Change lease paths cannot be narrowed after editing has started');
+        }
+        await this.save({
+            ...pointer,
+            ...(taskSnapshot
+                ? {
+                    taskVersion: taskSnapshot.taskVersion,
+                    lastSequence: taskSnapshot.lastSequence,
+                }
+                : {}),
+            changeBaseline: pointer.changeBaseline
+                ? { ...pointer.changeBaseline, leasePaths }
+                : {
+                    diffHash: manifest.diffHash,
+                    changedPaths: manifest.changedPaths,
+                    leasePaths,
+                },
+        });
+    }
+    async setVerificationIntent(repoFingerprint, input) {
+        await this.exclusive(repoFingerprint, async () => {
+            const pointer = await this.readPointer(repoFingerprint);
+            const bodyHash = sha256(stableStringify(input.body));
+            if (!pointer ||
+                pointer.taskId !== input.body.taskId ||
+                pointer.sessionId !== input.body.sessionId ||
+                pointer.closeIntent) {
+                throw new Error('Verification intent does not match the active task');
+            }
+            if (pointer.verificationIntent) {
+                if (pointer.verificationIntent.bodyHash === bodyHash &&
+                    stableStringify(pointer.verificationIntent.taskChanges) ===
+                        stableStringify(input.taskChanges)) {
+                    return;
+                }
+                throw new Error('A different verification intent is already pending');
+            }
+            await this.writePointer({
+                ...pointer,
+                verificationIntent: {
+                    ...input,
+                    bodyHash,
+                    createdAt: new Date().toISOString(),
+                },
+            });
+        });
+    }
+    async clearVerificationIntent(repoFingerprint) {
+        await this.exclusive(repoFingerprint, async () => {
+            const pointer = await this.readPointer(repoFingerprint);
+            if (!pointer?.verificationIntent) {
+                return;
+            }
+            const { verificationIntent: _verificationIntent, ...next } = pointer;
+            await this.writePointer(next);
+        });
+    }
+    async setCloseIntent(repoFingerprint, input) {
+        await this.exclusive(repoFingerprint, async () => {
+            const pointer = await this.readPointer(repoFingerprint);
+            const bodyHash = sha256(stableStringify(input.body));
+            if (!pointer ||
+                pointer.taskId !== input.body.taskId ||
+                pointer.sessionId !== input.body.sessionId ||
+                pointer.verificationIntent) {
+                throw new Error('Close intent does not match the active task');
+            }
+            if (pointer.closeIntent) {
+                if (pointer.closeIntent.bodyHash === bodyHash &&
+                    stableStringify(pointer.closeIntent.taskChanges) === stableStringify(input.taskChanges)) {
+                    return;
+                }
+                throw new Error('A different close intent is already pending');
+            }
+            await this.writePointer({
+                ...pointer,
+                closeIntent: {
+                    ...input,
+                    bodyHash,
+                    createdAt: new Date().toISOString(),
+                },
+            });
+        });
+    }
+    async clearCloseIntent(repoFingerprint) {
+        await this.exclusive(repoFingerprint, async () => {
+            const pointer = await this.readPointer(repoFingerprint);
+            if (!pointer?.closeIntent) {
+                return;
+            }
+            const { closeIntent: _closeIntent, ...next } = pointer;
+            await this.writePointer(next);
+        });
+    }
+    async findByTaskId(taskId, projectId, requireClean = true) {
+        await ensureManagedDirectory(this.root, this.root);
+        const entries = await readdir(this.root, { withFileTypes: true });
+        const matches = [];
+        for (const entry of entries) {
+            if (entry.name.endsWith('.json') && (!entry.isFile() || entry.isSymbolicLink())) {
+                throw new Error(`Unsafe active context entry: ${entry.name}`);
+            }
+            if (!entry.isFile() || !entry.name.endsWith('.json')) {
+                continue;
+            }
+            const pointer = await readJson(join(this.root, entry.name), this.root);
+            if (pointer) {
+                this.validate(pointer, pointer.repoFingerprint);
+                if (pointer.taskId === taskId && pointer.projectId === projectId) {
+                    matches.push(pointer);
+                }
+            }
+        }
+        if (matches.length !== 1 ||
+            (requireClean &&
+                (matches[0].resumeConflicts.length > 0 ||
+                    Boolean(matches[0].verificationIntent) ||
+                    Boolean(matches[0].closeIntent)))) {
+            throw new Error('A unique clean active task pointer is required');
+        }
+        return matches[0];
+    }
+    async markTasksConflict(taskIds, conflict) {
+        if (taskIds.length === 0) {
+            return;
+        }
+        await ensureManagedDirectory(this.root, this.root);
+        const targetIds = new Set(taskIds);
+        const entries = await readdir(this.root, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.name.endsWith('.json') && (!entry.isFile() || entry.isSymbolicLink())) {
+                throw new Error(`Unsafe active context entry: ${entry.name}`);
+            }
+            if (!entry.isFile() || !entry.name.endsWith('.json')) {
+                continue;
+            }
+            const pointer = await readJson(join(this.root, entry.name), this.root);
+            if (pointer && targetIds.has(pointer.taskId)) {
+                await this.save({
+                    ...pointer,
+                    resumeConflicts: [...new Set([...pointer.resumeConflicts, conflict])],
+                });
+            }
+        }
+    }
+    async clearSessionConflict(sessionId, conflict) {
+        if (!isUuid(sessionId)) {
+            throw new Error('Context session identifier is invalid');
+        }
+        await ensureManagedDirectory(this.root, this.root);
+        const entries = await readdir(this.root, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.name.endsWith('.json') && (!entry.isFile() || entry.isSymbolicLink())) {
+                throw new Error(`Unsafe active context entry: ${entry.name}`);
+            }
+            if (!entry.isFile() || !entry.name.endsWith('.json')) {
+                continue;
+            }
+            const pointer = await readJson(join(this.root, entry.name), this.root);
+            if (pointer?.sessionId === sessionId) {
+                await this.save({
+                    ...pointer,
+                    resumeConflicts: pointer.resumeConflicts.filter((value) => value !== conflict),
+                });
+            }
+        }
+    }
+    async clear() {
+        await ensureManagedDirectory(this.root, this.root);
+        const entries = await readdir(this.root, { withFileTypes: true });
+        for (const entry of entries) {
+            if (!entry.isFile() || entry.isSymbolicLink() || !entry.name.endsWith('.json')) {
+                throw new Error(`Unsafe active context entry: ${entry.name}`);
+            }
+            await removeFile(join(this.root, entry.name), this.root);
+        }
+    }
+    pathFor(repoFingerprint) {
+        assertFingerprint(repoFingerprint);
+        return join(this.root, `${repoFingerprint}.json`);
+    }
+    async readPointer(repoFingerprint) {
+        return await readJson(this.pathFor(repoFingerprint), this.root);
+    }
+    async writePointer(input) {
+        const pointer = {
+            schemaVersion: 1,
+            ...input,
+            updatedAt: new Date().toISOString(),
+        };
+        this.validate(pointer, input.repoFingerprint);
+        assertSafeToPersist(JSON.parse(JSON.stringify(pointer)));
+        await writeJson(this.pathFor(input.repoFingerprint), pointer, this.root);
+    }
+    async exclusive(repoFingerprint, action) {
+        const previous = this.queues.get(repoFingerprint) ?? Promise.resolve();
+        let release = () => undefined;
+        const current = new Promise((resolvePromise) => {
+            release = resolvePromise;
+        });
+        const tail = previous.then(() => current);
+        this.queues.set(repoFingerprint, tail);
+        await previous;
+        try {
+            return await action();
+        }
+        finally {
+            release();
+            if (this.queues.get(repoFingerprint) === tail) {
+                this.queues.delete(repoFingerprint);
+            }
+        }
+    }
+    validate(pointer, expectedFingerprint) {
+        if (pointer.schemaVersion !== 1 ||
+            pointer.repoFingerprint !== expectedFingerprint ||
+            !isUuid(pointer.projectId) ||
+            !isUuid(pointer.taskId) ||
+            !isUuid(pointer.sessionId) ||
+            !Number.isInteger(pointer.lastSequence) ||
+            pointer.lastSequence < 0 ||
+            !Number.isInteger(pointer.taskVersion) ||
+            pointer.taskVersion < 1 ||
+            !Array.isArray(pointer.resumeConflicts)) {
+            throw new Error('Active Engineering Memory context pointer is invalid');
+        }
+        if (pointer.changeBaseline) {
+            if (!/^[0-9a-f]{64}$/.test(pointer.changeBaseline.diffHash) ||
+                !Array.isArray(pointer.changeBaseline.changedPaths) ||
+                pointer.changeBaseline.changedPaths.some((entry) => !isChangedPath(entry)) ||
+                !Array.isArray(pointer.changeBaseline.leasePaths) ||
+                pointer.changeBaseline.leasePaths.some((path) => !isRepositoryRelative(path)) ||
+                new Set(pointer.changeBaseline.leasePaths).size !== pointer.changeBaseline.leasePaths.length) {
+                throw new Error('Active Engineering Memory change baseline is invalid');
+            }
+        }
+        if ((pointer.verificationIntent && !isVerificationIntent(pointer.verificationIntent)) ||
+            (pointer.closeIntent && !isCloseIntent(pointer.closeIntent))) {
+            throw new Error('Active Engineering Memory mutation intent is invalid');
+        }
+    }
+}
+function isVerificationIntent(value) {
+    return ((value.mode === 'write' || value.mode === 'read_only' || value.mode === 'scaffold') &&
+        isDurableIntent(value) &&
+        value.body.taskId !== undefined &&
+        value.body.sessionId !== undefined);
+}
+function isCloseIntent(value) {
+    return (isDurableIntent(value) && value.body.taskId !== undefined && value.body.sessionId !== undefined);
+}
+function isDurableIntent(value) {
+    return (value.body !== null &&
+        typeof value.body === 'object' &&
+        !Array.isArray(value.body) &&
+        /^[0-9a-f]{64}$/.test(value.bodyHash) &&
+        value.bodyHash === sha256(stableStringify(value.body)) &&
+        Array.isArray(value.taskChanges) &&
+        value.taskChanges.every(isChangedPath) &&
+        typeof value.createdAt === 'string' &&
+        Number.isFinite(Date.parse(value.createdAt)));
+}
+function isChangedPath(value) {
+    return (typeof value.path === 'string' &&
+        isRepositoryRelative(value.path) &&
+        (value.originalPath === undefined || isRepositoryRelative(value.originalPath)) &&
+        typeof value.status === 'string' &&
+        value.status.length === 2 &&
+        (value.contentHash === null || /^[0-9a-f]{64}$/.test(value.contentHash)) &&
+        (value.size === null || (Number.isSafeInteger(value.size) && value.size >= 0)) &&
+        (value.mode === undefined ||
+            value.mode === null ||
+            value.mode === '100644' ||
+            value.mode === '100755'));
+}
+function isRepositoryRelative(value) {
+    const normalized = value.replace(/\\/g, '/');
+    return (normalized.length > 0 &&
+        !normalized.startsWith('/') &&
+        !/^[A-Za-z]:\//.test(normalized) &&
+        !normalized.split('/').includes('..'));
+}
+function assertFingerprint(value) {
+    if (!/^[0-9a-f]{64}$/.test(value)) {
+        throw new Error('Repository fingerprint is invalid');
+    }
+}
+function isUuid(value) {
+    return /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value);
+}
+//# sourceMappingURL=active-context-store.js.map

package/runtime/dist/src/runtime/api-client.js

@@ -0,0 +1,229 @@
+import { sha256, stableStringify } from '../utilities/hash.js';
+export class BackendUnavailableError extends Error {
+    causeValue;
+    retryable = true;
+    constructor(message, causeValue) {
+        super(message);
+        this.causeValue = causeValue;
+        this.name = 'BackendUnavailableError';
+    }
+}
+export class ApiResponseError extends Error {
+    httpStatus;
+    code;
+    retryable;
+    envelope;
+    constructor(message, httpStatus, code, retryable, envelope) {
+        super(message);
+        this.httpStatus = httpStatus;
+        this.code = code;
+        this.retryable = retryable;
+        this.envelope = envelope;
+        this.name = 'ApiResponseError';
+    }
+}
+export class ApiClient {
+    options;
+    fetchImplementation;
+    responseSources = new WeakMap();
+    refreshPromise = null;
+    constructor(options) {
+        this.options = options;
+        this.fetchImplementation = options.fetchImplementation ?? fetch;
+    }
+    async request(path, request = {}) {
+        const method = request.method ?? 'GET';
+        const cacheKey = request.cacheKey ?? this.cacheKey(method, path, request.body);
+        const cached = request.cacheKey ? await this.options.cache.get(cacheKey) : null;
+        const headers = {
+            Accept: 'application/json',
+            ...request.headers,
+        };
+        if (request.body !== undefined) {
+            headers['Content-Type'] = 'application/json';
+        }
+        if (request.idempotencyKey) {
+            headers['Idempotency-Key'] = request.idempotencyKey;
+        }
+        if (cached?.etag) {
+            headers['If-None-Match'] = cached.etag;
+        }
+        if (request.authenticated !== false) {
+            const accessToken = await this.options.credentials.get('access-token');
+            if (!accessToken) {
+                throw new ApiResponseError('Authentication is required', 401, null, false, null);
+            }
+            headers.Authorization = `Bearer ${accessToken}`;
+        }
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), this.options.timeoutMs);
+        let response;
+        try {
+            response = await this.fetchImplementation(`${this.options.baseUrl}${path}`, {
+                method,
+                headers,
+                ...(request.body === undefined ? {} : { body: JSON.stringify(request.body) }),
+                signal: controller.signal,
+            });
+        }
+        catch (error) {
+            if (request.allowStaleOnUnavailable && cached) {
+                this.responseSources.set(cached.value, 'stale_cache');
+                return cached.value;
+            }
+            throw new BackendUnavailableError(error instanceof Error ? error.message : 'Backend request failed', error);
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+        if (response.status === 304 && cached) {
+            this.responseSources.set(cached.value, 'not_modified');
+            return cached.value;
+        }
+        if (response.status === 401 &&
+            request.authenticated !== false &&
+            request.retryRefresh !== false) {
+            await this.refreshTokens();
+            return await this.request(path, { ...request, retryRefresh: false });
+        }
+        let envelope;
+        try {
+            envelope = await this.parseEnvelope(response);
+        }
+        catch (error) {
+            if (request.allowStaleOnUnavailable &&
+                cached &&
+                isBackendUnavailableStatus(response.status)) {
+                this.responseSources.set(cached.value, 'stale_cache');
+                return cached.value;
+            }
+            throw error;
+        }
+        if (!response.ok || envelope.status === 'error') {
+            if (request.allowStaleOnUnavailable &&
+                cached &&
+                isBackendUnavailableStatus(response.status)) {
+                this.responseSources.set(cached.value, 'stale_cache');
+                return cached.value;
+            }
+            throw new ApiResponseError(envelope.errorModel?.text ?? envelope.message ?? `Backend returned ${response.status}`, response.status, envelope.errorModel?.code ?? null, response.status === 408 || response.status === 429 || response.status >= 500, envelope);
+        }
+        if (request.cacheKey) {
+            await this.options.cache.set(cacheKey, response.headers.get('etag'), envelope);
+        }
+        this.responseSources.set(envelope, 'network');
+        return envelope;
+    }
+    getResponseSource(response) {
+        return this.responseSources.get(response) ?? 'network';
+    }
+    async readCached(cacheKey) {
+        return (await this.options.cache.get(cacheKey))?.value ?? null;
+    }
+    async seedCache(cacheKey, value) {
+        await this.options.cache.set(cacheKey, null, value);
+    }
+    async refreshAuthentication() {
+        await this.refreshTokens();
+    }
+    async refreshTokens() {
+        if (this.refreshPromise) {
+            return await this.refreshPromise;
+        }
+        this.refreshPromise = this.performTokenRefresh();
+        try {
+            await this.refreshPromise;
+        }
+        finally {
+            this.refreshPromise = null;
+        }
+    }
+    async performTokenRefresh() {
+        const refreshToken = await this.options.credentials.get('refresh-token');
+        if (!refreshToken) {
+            await this.options.credentials.clear();
+            throw new ApiResponseError('Authentication has expired', 401, null, false, null);
+        }
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), this.options.timeoutMs);
+        let response;
+        try {
+            response = await this.fetchImplementation(`${this.options.baseUrl}${this.options.refreshPath}`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
+                body: JSON.stringify({ refreshToken }),
+                signal: controller.signal,
+            });
+        }
+        catch (error) {
+            throw new BackendUnavailableError('Token refresh failed', error);
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+        let envelope;
+        try {
+            envelope = await this.parseEnvelope(response);
+        }
+        catch (error) {
+            if (isDefinitiveRefreshRejection(response.status)) {
+                await this.options.credentials.clear();
+            }
+            throw error;
+        }
+        if (!response.ok || envelope.status === 'error') {
+            if (isDefinitiveRefreshRejection(response.status)) {
+                await this.options.credentials.clear();
+                throw new ApiResponseError('Authentication has expired', response.status, null, false, envelope);
+            }
+            throw new ApiResponseError(envelope.errorModel?.text ?? envelope.message ?? 'Token refresh failed', response.status, envelope.errorModel?.code ?? null, response.status === 408 || response.status === 429 || response.status >= 500, envelope);
+        }
+        if (!isRefreshTokens(envelope.data)) {
+            throw new ApiResponseError('Token refresh response is missing credentials', response.status, null, false, envelope);
+        }
+        await this.options.credentials.set('access-token', envelope.data.accessToken);
+        if (envelope.data.refreshToken) {
+            await this.options.credentials.set('refresh-token', envelope.data.refreshToken);
+        }
+    }
+    async parseEnvelope(response) {
+        let value;
+        try {
+            value = await response.json();
+        }
+        catch {
+            throw new ApiResponseError(`Backend returned a non-JSON response with status ${response.status}`, response.status, null, response.status >= 500, null);
+        }
+        if (!isEnvelope(value)) {
+            throw new ApiResponseError('Backend response does not match the Engineering Memory envelope', response.status, null, false, null);
+        }
+        return value;
+    }
+    cacheKey(method, path, body) {
+        return sha256(`${method}\n${path}\n${stableStringify(body ?? null)}`);
+    }
+}
+function isDefinitiveRefreshRejection(status) {
+    return status === 400 || status === 401 || status === 403;
+}
+function isBackendUnavailableStatus(status) {
+    return status === 502 || status === 503 || status === 504;
+}
+function isEnvelope(value) {
+    if (value === null || typeof value !== 'object') {
+        return false;
+    }
+    const candidate = value;
+    return ((candidate.status === 'success' || candidate.status === 'error') &&
+        'data' in candidate &&
+        'message' in candidate &&
+        'errorModel' in candidate);
+}
+function isRefreshTokens(value) {
+    return (value !== null &&
+        !Array.isArray(value) &&
+        typeof value === 'object' &&
+        typeof value.accessToken === 'string' &&
+        (value.refreshToken === undefined || typeof value.refreshToken === 'string'));
+}
+//# sourceMappingURL=api-client.js.map