semantifold 0.8.0 → 0.10.0

package/build/src/publication.d.ts

@@ -0,0 +1,218 @@
+import path from "node:path";
+/**
+ * Queues one internal caller-owned currentness guard for the publisher's next transaction.
+ * The guard runs after every validator closes and immediately before the active-pointer commit.
+ * This helper is intentionally not part of the package root API.
+ * @param {GeneratedArtifactPublisher} publisher - Publisher instance.
+ * @param {() => Promise<void> | void} guard - Exact pre-commit guard.
+ * @returns {void}
+ */
+export declare function guardNextPublicationCommit(publisher: GeneratedArtifactPublisher, guard: () => Promise<void> | void): void;
+/**
+ * Installs one internal, one-shot deterministic failure used by real-filesystem interruption specs.
+ * This helper is intentionally not part of the package root API.
+ * @param {GeneratedArtifactPublisher} publisher - Publisher instance.
+ * @param {"after-stage" | "before-pointer-replace" | "after-pointer-replace" | "before-cleanup" | "before-journal-remove"} boundary - Exact lifecycle boundary.
+ * @param {Error} error - Injected failure.
+ * @returns {void}
+ */
+export declare function injectPublicationFailure(publisher: GeneratedArtifactPublisher, boundary: "after-stage" | "before-pointer-replace" | "after-pointer-replace" | "before-cleanup" | "before-journal-remove", error: Error): void;
+/**
+ * Installs an internal deterministic filesystem-operation observer for durability specs.
+ * This helper is intentionally not part of the package root API.
+ * @param {GeneratedArtifactPublisher} publisher - Publisher instance.
+ * @param {(operation: string) => void} observer - Synchronous operation observer.
+ * @returns {void}
+ */
+export declare function observePublicationFilesystem(publisher: GeneratedArtifactPublisher, observer: (operation: string) => void): void;
+/**
+ * Owns transactional publication in one dedicated directory beneath a canonical project root.
+ */
+export declare class GeneratedArtifactPublisher {
+    #private;
+    /**
+     * Creates a project-scoped publisher without touching the filesystem.
+     * @param {object} options - Publisher identity and owned paths.
+     * @param {string} options.projectId - Stable lowercase project identity.
+     * @param {string} options.projectRoot - Canonical absolute project root.
+     * @param {string} options.publicationRoot - Canonical absolute publisher-owned directory beneath the project root.
+     * @param {readonly string[]} [options.sourceRoots] - Canonical absolute project source directories kept disjoint from publication.
+     * @param {readonly string[]} [options.sourceFiles] - Canonical absolute project source files kept disjoint from publication.
+     */
+    constructor(options: {
+        projectId: string;
+        projectRoot: string;
+        publicationRoot: string;
+        sourceRoots?: readonly string[];
+        sourceFiles?: readonly string[];
+    });
+    /**
+     * Stages, validates, and publishes one complete immutable project generation.
+     * Calls on one publisher instance are serialized in invocation order.
+     * @param {import("./semantic/types.js").PublicationRequest} request - Complete publication request.
+     * @param {import("./semantic/types.js").PublicationOptions} [options] - Transaction lifecycle controls.
+     * @returns {Promise<import("./semantic/types.js").PublishedGeneration>} Committed immutable snapshot.
+     */
+    publish(request: import("./semantic/types.js").PublicationRequest, options?: import("./semantic/types.js").PublicationOptions): Promise<import("./semantic/types.js").PublishedGeneration>;
+    /**
+     * Resolves the active pointer exactly once and verifies the referenced immutable generation.
+     * @returns {Promise<import("./semantic/types.js").PublishedGeneration>} Verified pointer-once snapshot.
+     */
+    resolveActive(): Promise<import("./semantic/types.js").PublishedGeneration>;
+}
+/**
+ * Checks one absolute path using the supplied host path semantics.
+ * This helper is intentionally not part of the package root API.
+ * @param {unknown} value - Path candidate.
+ * @param {typeof path.posix | typeof path.win32} hostPath - Host-native path implementation.
+ * @returns {value is string} Whether the path is canonical for that host.
+ */
+export declare function isCanonicalAbsolutePathForPath(value: unknown, hostPath: typeof path.posix | typeof path.win32): value is string;
+export type ValidatedPublicationTarget = {
+    /**
+     * - Target identity.
+     */
+    id: string;
+    /**
+     * - Detached artifact set.
+     */
+    artifactSet: import("./semantic/types.js").GeneratedArtifactSet;
+    /**
+     * - Source projection.
+     */
+    sourceProjection: string;
+    /**
+     * - Build projection.
+     */
+    buildProjection: string;
+    /**
+     * - Language-neutral target role.
+     */
+    role: import("./semantic/types.js").PublicationTargetRole;
+    /**
+     * - Ordered validators.
+     */
+    validators: readonly import("./semantic/types.js").PublicationValidator[];
+};
+export type ValidatedPublicationRequest = {
+    /**
+     * - Snapshotted generation identity.
+     */
+    generationId: string;
+    /**
+     * - Snapshotted ordered targets.
+     */
+    targets: readonly ValidatedPublicationTarget[];
+};
+export type ActivePointer = {
+    /**
+     * - Schema discriminator.
+     */
+    schema: "SemantifoldActiveGeneration";
+    /**
+     * - Schema version.
+     */
+    version: 1;
+    /**
+     * - Project identity.
+     */
+    projectId: string;
+    /**
+     * - Generation identity.
+     */
+    generationId: string;
+    /**
+     * - SHA-256 generation-manifest hash.
+     */
+    manifestHash: string;
+};
+export type CandidatePublicationJournal = {
+    /**
+     * - Schema discriminator.
+     */
+    schema: "SemantifoldPublicationJournal";
+    /**
+     * - Schema version.
+     */
+    version: 1;
+    /**
+     * - Project identity.
+     */
+    projectId: string;
+    /**
+     * - Candidate generation identity.
+     */
+    generationId: string;
+    /**
+     * - Owned sibling temporary-pointer filename.
+     */
+    tempPointer: string;
+};
+export type ReactivationPublicationJournal = {
+    /**
+     * - Schema discriminator.
+     */
+    schema: "SemantifoldPublicationJournal";
+    /**
+     * - Schema version.
+     */
+    version: 2;
+    /**
+     * - Retained-generation activation without candidate ownership.
+     */
+    operation: "reactivate";
+    /**
+     * - Project identity.
+     */
+    projectId: string;
+    /**
+     * - Retained generation identity.
+     */
+    generationId: string;
+    /**
+     * - Owned sibling temporary-pointer filename.
+     */
+    tempPointer: string;
+};
+export type PublicationJournal = CandidatePublicationJournal | ReactivationPublicationJournal;
+/**
+ * @typedef ValidatedPublicationTarget
+ * @property {string} id - Target identity.
+ * @property {import("./semantic/types.js").GeneratedArtifactSet} artifactSet - Detached artifact set.
+ * @property {string} sourceProjection - Source projection.
+ * @property {string} buildProjection - Build projection.
+ * @property {import("./semantic/types.js").PublicationTargetRole} role - Language-neutral target role.
+ * @property {readonly import("./semantic/types.js").PublicationValidator[]} validators - Ordered validators.
+ */
+/**
+ * @typedef ValidatedPublicationRequest
+ * @property {string} generationId - Snapshotted generation identity.
+ * @property {readonly ValidatedPublicationTarget[]} targets - Snapshotted ordered targets.
+ */
+/**
+ * @typedef ActivePointer
+ * @property {"SemantifoldActiveGeneration"} schema - Schema discriminator.
+ * @property {1} version - Schema version.
+ * @property {string} projectId - Project identity.
+ * @property {string} generationId - Generation identity.
+ * @property {string} manifestHash - SHA-256 generation-manifest hash.
+ */
+/**
+ * @typedef CandidatePublicationJournal
+ * @property {"SemantifoldPublicationJournal"} schema - Schema discriminator.
+ * @property {1} version - Schema version.
+ * @property {string} projectId - Project identity.
+ * @property {string} generationId - Candidate generation identity.
+ * @property {string} tempPointer - Owned sibling temporary-pointer filename.
+ */
+/**
+ * @typedef ReactivationPublicationJournal
+ * @property {"SemantifoldPublicationJournal"} schema - Schema discriminator.
+ * @property {2} version - Schema version.
+ * @property {"reactivate"} operation - Retained-generation activation without candidate ownership.
+ * @property {string} projectId - Project identity.
+ * @property {string} generationId - Retained generation identity.
+ * @property {string} tempPointer - Owned sibling temporary-pointer filename.
+ */
+/** @typedef {CandidatePublicationJournal | ReactivationPublicationJournal} PublicationJournal */
+//# sourceMappingURL=publication.d.ts.map

package/build/src/publication.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"publication.d.ts","sourceRoot":"","sources":["../../src/publication.js"],"names":[],"mappings":"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"}