@tequila99/githuman 0.11.2 → 0.13.0

package/dist/server/services/artifact-lifecycle.service.js

@@ -0,0 +1,431 @@
+import { errorMessage } from "../../shared/utils/error-message.js";
+import { randomUUID } from 'node:crypto';
+import { Value } from '@sinclair/typebox/value';
+import { ArtifactChangeSetProposeBody, ArtifactAuthorizationRequestBody, ArtifactLifecycleCommitBody } from "../../shared/artifacts/schemas.js";
+import { canonicalJson } from "../../shared/utils/canonical-json.js";
+import { sha256Hex } from "../utils/hash.js";
+import { HEARTBEAT_STALE_MS } from "../../shared/artifact-transitions/constants.js";
+import { hasErrorCode } from "../utils/system-error.js";
+import { ArtifactConflictError, ArtifactInputError } from "../errors/artifacts.js";
+import { canonicalChangeSet, graphIssuesMessage, previewArtifactChangeSet } from "./artifact-graph-validation.js";
+import { ArtifactValidationRepository } from "../repositories/artifact-validation.repo.js";
+import { ArtifactAuthorizationService, artifactActionDigest } from "./artifact-authorization.service.js";
+import { ArtifactValidationJobsService } from "./artifact-validation-jobs.service.js";
+import { ArtifactTransitionRepository } from "../repositories/artifact-transition.repo.js";
+import { ArtifactTransitionService } from "./artifact-transition.service.js";
+// Manifest changes invalidate all earlier semantic conclusions.
+const VALIDATION_RULES_VERSION = 3;
+// The server is the author of a proposal version that only follows the grown set (ADR 0121).
+const REBASE_ACTOR = { kind: 'system', id: 'validation-rebase' };
+// Preview errors that a rebase can fix: they only name versions of the set context.
+const REBASE_CODES = new Set(['missing_expected_version', 'stale_version']);
+// The reason in the request list is cut to this length; the full text stays in the proposal.
+const ACTION_REASON_CHARS = 300;
+export function artifactSessionId(actor) {
+    return actor.kind === 'user' ? `user:${actor.id}` : actor.id;
+}
+/**
+ * The digest covers the affected set, not the store epoch. A store change outside
+ * the set does not make a running validation stale (ADR 0119).
+ */
+function setDigest(manifest) {
+    const { validationEpoch: _epoch, ...content } = manifest;
+    return artifactActionDigest(content);
+}
+export class ArtifactLifecycleService {
+    repository;
+    authorization;
+    jobs;
+    transitions;
+    registry;
+    storage;
+    now;
+    constructor(storage, db, now = Date.now) {
+        this.storage = storage;
+        this.now = now;
+        this.repository = new ArtifactValidationRepository(db, storage.storeId);
+        this.authorization = new ArtifactAuthorizationService(this.repository, now, action => this.checkAction(action), id => id.startsWith('user:') ||
+            Boolean(this.registry?.get(id) && this.registry.get(id).status !== 'closed'), () => this.registry?.notifyArtifactActionsChanged?.());
+        this.jobs = new ArtifactValidationJobsService(this, now);
+        this.transitions = new ArtifactTransitionService(this, new ArtifactTransitionRepository(db, storage.storeId), now);
+    }
+    /**
+     * True when the process of `owner` exists and its heartbeat is fresh. A
+     * missing heartbeat counts as alive, so old data keeps its behavior. The own
+     * instance is always alive (ADR 0108).
+     */
+    ownerAlive(owner, pid) {
+        if (owner === this.jobs.ownerId) {
+            return true;
+        }
+        try {
+            process.kill(pid, 0);
+        }
+        catch (error) {
+            if (hasErrorCode(error, 'ESRCH')) {
+                return false;
+            }
+        }
+        const beat = this.repository.heartbeat(owner);
+        return beat === undefined || this.now() - beat <= HEARTBEAT_STALE_MS;
+    }
+    attachSessions(registry) {
+        this.registry = registry;
+        this.jobs.attachSessions(registry);
+    }
+    propose(input, actor) {
+        if (!Value.Check(ArtifactChangeSetProposeBody, input) ||
+            !input.changeSet.reason.trim()) {
+            throw new ArtifactInputError('Invalid change set proposal.');
+        }
+        if (Buffer.byteLength(JSON.stringify(input.changeSet)) > 48 * 1024) {
+            throw new ArtifactInputError('Change set exceeds the bounded proposal size.');
+        }
+        return this.storage.catalog.transaction(() => this.proposeInTransaction(input, actor));
+    }
+    /** Proposes inside a transaction owned by the caller. */
+    proposeInTransaction(input, actor) {
+        const changeDigest = artifactActionDigest(canonicalChangeSet(input.changeSet));
+        const requestDigest = artifactActionDigest({
+            id: input.id ?? null,
+            expectedVersion: input.expectedVersion ?? null,
+            changeDigest,
+            actor
+        });
+        const replay = this.repository.proposalRequest(input.requestId);
+        if (replay) {
+            if (replay.requestDigest !== requestDigest ||
+                canonicalJson(replay.actor) !== canonicalJson(actor) ||
+                (input.id && replay.id !== input.id)) {
+                throw new ArtifactConflictError('Proposal request ID was reused.');
+            }
+            return replay;
+        }
+        const preview = this.preview(input.changeSet);
+        if (preview.errors.length) {
+            throw new ArtifactInputError(graphIssuesMessage(preview.errors, preview.expectedVersions));
+        }
+        const previous = input.id ? this.repository.proposal(input.id) : undefined;
+        if ((previous && previous.version !== input.expectedVersion) ||
+            (!previous && input.expectedVersion)) {
+            throw new ArtifactConflictError('Change set version changed.');
+        }
+        const proposal = {
+            id: previous?.id ?? randomUUID(),
+            version: (previous?.version ?? 0) + 1,
+            requestId: input.requestId,
+            requestDigest,
+            actor,
+            changeSet: preview.canonical,
+            changeDigest: preview.changeDigest
+        };
+        this.repository.appendProposal(proposal);
+        return proposal;
+    }
+    inspectValidation(id) {
+        return this.storage.catalog.readSnapshot(() => {
+            const validation = this.jobs.get(id);
+            const proposal = this.repository.proposalVersion(validation.changeSetId, validation.version);
+            const preview = this.preview(proposal.changeSet);
+            let ready = false;
+            let problem = null;
+            try {
+                this.checkAction({
+                    kind: 'lifecycle',
+                    changeSetId: proposal.id,
+                    version: proposal.version,
+                    validationId: id
+                });
+                ready = true;
+            }
+            catch (error) {
+                problem = errorMessage(error);
+            }
+            return {
+                storeId: this.storage.storeId,
+                validation,
+                proposal,
+                preview,
+                ready,
+                problem
+            };
+        });
+    }
+    /** The pending requests, each with a short summary so the user can tell them apart. */
+    listActions() {
+        return this.storage.catalog.readSnapshot(() => this.authorization.list().map(pending => {
+            try {
+                const { changeSet } = this.repository.proposalVersion(pending.action.changeSetId, pending.action.version);
+                return {
+                    ...pending,
+                    summary: {
+                        command: changeSet.command,
+                        reason: changeSet.reason.slice(0, ACTION_REASON_CHARS),
+                        documentCount: changeSet.targetStatuses.length
+                    }
+                };
+            }
+            catch {
+                // A proposal that cannot be read must not hide the request itself.
+                return { ...pending, summary: null };
+            }
+        }));
+    }
+    inspectAction(id, actor) {
+        return this.storage.catalog.readSnapshot(() => {
+            const value = this.authorization.describe(id);
+            const action = value.pending.action;
+            const proposal = this.repository.proposalVersion(action.changeSetId, action.version);
+            const validation = this.jobs.get(action.validationId);
+            const preview = this.preview(proposal.changeSet);
+            let ready = false;
+            let problem = null;
+            if (value.phase !== 'consumed') {
+                try {
+                    const binding = this.checkAction(action);
+                    if (binding.actionDigest !== value.pending.actionDigest ||
+                        binding.manifestDigest !== value.pending.manifestDigest) {
+                        throw new ArtifactConflictError('Action scope changed.');
+                    }
+                    ready = true;
+                }
+                catch (error) {
+                    problem = errorMessage(error);
+                }
+            }
+            const canExecute = value.pending.sessionId === artifactSessionId(actor);
+            // Project only the original request fields; grants also hold private audit bindings.
+            const { id: pendingId, sessionId, action: pendingAction, actionDigest, manifestDigest, expiresAt } = value.pending;
+            return {
+                storeId: this.storage.storeId,
+                pending: {
+                    id: pendingId,
+                    sessionId,
+                    action: pendingAction,
+                    actionDigest,
+                    manifestDigest,
+                    expiresAt
+                },
+                phase: value.phase,
+                canExecute,
+                ready,
+                problem,
+                proposal,
+                validation,
+                preview,
+                authorizationId: canExecute ? value.authorizationId : null
+            };
+        });
+    }
+    get(id) {
+        return this.repository.proposal(id);
+    }
+    preview(changeSet) {
+        return previewArtifactChangeSet(this.storage.catalog.all(), changeSet, this.storage.catalog.supersededArtifactIds());
+    }
+    prepare(changeSetId, version) {
+        return this.storage.catalog.transaction(() => this.prepareInTransaction(changeSetId, version));
+    }
+    /** Prepares inside a transaction owned by the caller. */
+    prepareInTransaction(changeSetId, version) {
+        const proposal = this.repository.proposal(changeSetId);
+        if (proposal.version !== version) {
+            throw new ArtifactConflictError('Change set version changed.');
+        }
+        const manifest = this.manifest(proposal);
+        const value = {
+            id: randomUUID(),
+            changeSetId,
+            version,
+            manifest,
+            manifestDigest: setDigest(manifest),
+            state: 'prepared',
+            validatorSessionId: null,
+            owner: null,
+            expiresAt: null
+        };
+        this.repository.appendValidation(value);
+        return value;
+    }
+    manifest(proposal) {
+        const preview = this.preview(proposal.changeSet);
+        if (preview.errors.length) {
+            throw new ArtifactConflictError(graphIssuesMessage(preview.errors, preview.expectedVersions));
+        }
+        const artifacts = preview.affectedIds.map(id => this.storage.readVerifiedFile(id).artifact);
+        return {
+            rulesVersion: VALIDATION_RULES_VERSION,
+            validationEpoch: this.storage.catalog.validationEpoch(),
+            changeDigest: proposal.changeDigest,
+            changeSet: proposal.changeSet,
+            artifacts,
+            requiredContentIds: artifacts.map(item => item.id)
+        };
+    }
+    /**
+     * Gives the next proposal version and manifest of a running validation when only
+     * the context of its set changed (ADR 0121). The caller owns the transaction.
+     * Returns undefined when the change needs a decision of the proposal author.
+     */
+    rebaseInTransaction(validation) {
+        const proposal = this.repository.proposal(validation.changeSetId);
+        if (proposal.version !== validation.version ||
+            validation.manifest.rulesVersion !== VALIDATION_RULES_VERSION) {
+            return undefined;
+        }
+        const subjects = new Set(proposal.changeSet.subjectIds);
+        const preview = this.preview(proposal.changeSet);
+        const decided = proposal.changeSet.supplementDispositions
+            .map(item => item.artifactId)
+            .sort();
+        if (!preview.errors.every(issue => REBASE_CODES.has(issue.code) &&
+            issue.artifactIds.every(id => !subjects.has(id))) ||
+            canonicalJson(preview.requiredSupplementDispositions) !==
+                canonicalJson(decided)) {
+            return undefined;
+        }
+        const command = proposal.changeSet.command;
+        // A historical command has no current proposal form; its validation stays stale.
+        if (command === 'submit_review') {
+            return undefined;
+        }
+        let next = proposal;
+        if (preview.errors.length) {
+            next = this.proposeInTransaction({
+                requestId: `validation-rebase:${validation.id}:${proposal.version}`,
+                id: proposal.id,
+                expectedVersion: proposal.version,
+                changeSet: {
+                    ...proposal.changeSet,
+                    command,
+                    expectedVersions: preview.expectedVersions
+                }
+            }, REBASE_ACTOR);
+        }
+        const manifest = this.manifest(next);
+        return { proposal: next, manifest, digest: setDigest(manifest) };
+    }
+    assertFresh(validation) {
+        const proposal = this.repository.proposal(validation.changeSetId);
+        let digest;
+        try {
+            digest = setDigest(this.manifest(proposal));
+        }
+        catch (error) {
+            // A store change can make the change set invalid, for example a new accepted
+            // artifact without tasks. That is staleness too, so the caller sees one error.
+            if (!(error instanceof ArtifactConflictError)) {
+                throw error;
+            }
+            throw new ArtifactConflictError(`VALIDATION_STALE: manifest changed (${error.message}); prepare a new validation.`);
+        }
+        if (validation.manifest.rulesVersion !== VALIDATION_RULES_VERSION ||
+            proposal.version !== validation.version ||
+            digest !== validation.manifestDigest) {
+            throw new ArtifactConflictError('VALIDATION_STALE: manifest changed; prepare a new validation.');
+        }
+        return proposal;
+    }
+    checkAction(action) {
+        if (!Value.Check(ArtifactAuthorizationRequestBody, action)) {
+            throw new ArtifactInputError('Invalid authorization action.');
+        }
+        const validation = this.repository.validation(action.validationId);
+        const proposal = this.assertFresh(validation);
+        if (validation.state !== 'pass' ||
+            proposal.id !== action.changeSetId ||
+            proposal.version !== action.version) {
+            throw new ArtifactConflictError('A fresh matching validation pass is required.');
+        }
+        return {
+            actionDigest: proposal.changeDigest,
+            manifestDigest: validation.manifestDigest
+        };
+    }
+    commit(id, input, actor) {
+        if (!Value.Check(ArtifactLifecycleCommitBody, input)) {
+            throw new ArtifactInputError('Invalid commit request.');
+        }
+        const payloadHash = sha256Hex(canonicalJson({ id, input, actor }));
+        const result = this.storage.catalog.transaction(() => {
+            const replay = this.repository.commitRequest(input.requestId);
+            if (replay) {
+                if (replay.payloadHash !== payloadHash) {
+                    throw new ArtifactConflictError('Commit request ID was reused.');
+                }
+                return replay.result;
+            }
+            const action = {
+                kind: 'lifecycle',
+                changeSetId: id,
+                version: input.version,
+                validationId: input.validationId
+            };
+            this.authorization.assert(input.authorizationId, artifactSessionId(actor), action);
+            const value = this.applyChangeSet(id, input.version, input.requestId, payloadHash, actor);
+            this.authorization.consume(input.authorizationId);
+            return value;
+        });
+        this.storage.pollChanges();
+        return result;
+    }
+    /**
+     * Commits a proposal on the strength of a stored prior consent instead of a
+     * session grant. The caller checks the consent; `inTransaction` writes the
+     * consumption and the operation result atomically with the status changes.
+     */
+    commitConfirmed(input, actor, inTransaction) {
+        const payloadHash = sha256Hex(canonicalJson({ input, actor }));
+        const result = this.storage.catalog.transaction(() => {
+            const replay = this.repository.commitRequest(input.requestId);
+            if (replay) {
+                if (replay.payloadHash !== payloadHash) {
+                    throw new ArtifactConflictError('Commit request ID was reused.');
+                }
+                return replay.result;
+            }
+            this.checkAction({
+                kind: 'lifecycle',
+                changeSetId: input.changeSetId,
+                version: input.version,
+                validationId: input.validationId
+            });
+            const value = this.applyChangeSet(input.changeSetId, input.version, input.requestId, payloadHash, actor);
+            inTransaction();
+            return value;
+        });
+        this.storage.pollChanges();
+        return result;
+    }
+    applyChangeSet(id, version, requestId, payloadHash, actor) {
+        const proposal = this.repository.proposal(id);
+        const preview = this.preview(proposal.changeSet);
+        if (preview.errors.length) {
+            throw new ArtifactConflictError('Change set post-state is invalid.');
+        }
+        const updated = [];
+        for (const node of preview.postState) {
+            const previous = this.storage.get(node.id);
+            if (canonicalJson(node) === canonicalJson(previous))
+                continue;
+            const next = {
+                ...node,
+                metadataVersion: previous.metadataVersion + 1,
+                metadataUpdatedAt: new Date(this.now()).toISOString()
+            };
+            this.storage.catalog.appendMetadata(next, `lifecycle:${sha256Hex(canonicalJson([requestId, node.id]))}`, actor, 'metadata_updated');
+            updated.push({ id: next.id, metadataVersion: next.metadataVersion });
+        }
+        const value = {
+            storeId: this.storage.storeId,
+            changeSetId: id,
+            version,
+            affectedIds: updated.map(item => item.id),
+            metadataVersions: updated,
+            includedIn: preview.includedIn,
+            storeEpoch: this.storage.catalog.epoch()
+        };
+        const eventSeq = this.repository.appendCommit(requestId, payloadHash, value);
+        return { ...value, eventSeq };
+    }
+}

package/dist/server/services/artifact-maintenance.service.js

@@ -0,0 +1,55 @@
+import { errorMessage } from "../../shared/utils/error-message.js";
+// Detect other writers and retry expired operation leases without device settings.
+const MAINTENANCE_INTERVAL_MS = 2000;
+export class ArtifactMaintenanceService {
+    options;
+    timer;
+    running = false;
+    // Last reported message per phase; a repeating failure is reported once.
+    reported = new Map();
+    constructor(options) {
+        this.options = options;
+    }
+    start() {
+        if (this.running)
+            return;
+        this.running = true;
+        // Reads verify every file, so a failed first pass must not block the server.
+        this.run(true);
+        if (!this.running)
+            return;
+        this.timer = setInterval(() => this.check(), MAINTENANCE_INTERVAL_MS);
+        this.timer.unref();
+    }
+    stop() {
+        this.running = false;
+        clearInterval(this.timer);
+        this.timer = undefined;
+    }
+    check() {
+        if (!this.running)
+            return;
+        this.run(false);
+    }
+    run(cleanupCommitted) {
+        this.attempt('recovery', () => this.options.storage.recover(cleanupCommitted));
+        // The error handler may stop the service.
+        if (!this.running)
+            return;
+        // A failed recovery must not hide changes committed by another process.
+        this.attempt('poll', () => this.options.storage.pollChanges());
+    }
+    attempt(phase, run) {
+        try {
+            run();
+            this.reported.delete(phase);
+        }
+        catch (error) {
+            const message = errorMessage(error);
+            if (this.reported.get(phase) === message)
+                return;
+            this.reported.set(phase, message);
+            this.options.onError(error, phase);
+        }
+    }
+}