jinaga-server 3.5.1 → 3.5.3

package/src/http/stream.ts

@@ -3,30 +3,122 @@ export class Stream<T> {
     private handlers: ((data: T) => void)[] = [];
     private doneHandlers: (() => void)[] = [];
     private closed = false;
+    private readonly streamId: string;
+    private feedCount = 0;
+
+    constructor() {
+        this.streamId = Math.random().toString(36).substring(2, 10);
+        console.log(`[Stream:${this.streamId}] Created new stream`);
+    }
 
     next(handler: (data: T) => void): Stream<T> {
+        if (this.closed) {
+            console.warn(`[Stream:${this.streamId}] Attempted to add handler to closed stream`);
+            return this;
+        }
+        
         this.handlers.push(handler);
-        this.queue.forEach(data => handler(data));
+        const queueLength = this.queue.length;
+        console.log(`[Stream:${this.streamId}] Added handler - Total handlers: ${this.handlers.length}, Queued items: ${queueLength}`);
+        
+        // Replay queued data to new handler
+        this.queue.forEach((data, index) => {
+            try {
+                handler(data);
+                console.log(`[Stream:${this.streamId}] Replayed queued item ${index + 1}/${queueLength} to new handler`);
+            } catch (error) {
+                console.error(`[Stream:${this.streamId}] Error replaying queued item ${index + 1}: ${error}`);
+            }
+        });
+        
         return this;
     }
 
     done(handler: () => void): Stream<T> {
+        if (this.closed) {
+            console.warn(`[Stream:${this.streamId}] Attempted to add done handler to closed stream - executing immediately`);
+            try {
+                handler();
+            } catch (error) {
+                console.error(`[Stream:${this.streamId}] Error in immediate done handler: ${error}`);
+            }
+            return this;
+        }
+        
         this.doneHandlers.push(handler);
+        console.log(`[Stream:${this.streamId}] Added done handler - Total done handlers: ${this.doneHandlers.length}`);
         return this;
     }
 
     close(): void {
+        if (this.closed) {
+            console.warn(`[Stream:${this.streamId}] Attempted to close already closed stream`);
+            return;
+        }
+        
+        console.log(`[Stream:${this.streamId}] CLOSING stream - Handlers: ${this.handlers.length}, Done handlers: ${this.doneHandlers.length}, Queue: ${this.queue.length}, Feed count: ${this.feedCount}`);
+        
         this.closed = true;
-        this.doneHandlers.forEach(handler => handler());
+        
+        // Execute done handlers
+        const doneHandlerCount = this.doneHandlers.length;
+        this.doneHandlers.forEach((handler, index) => {
+            try {
+                handler();
+                console.log(`[Stream:${this.streamId}] Executed done handler ${index + 1}/${doneHandlerCount}`);
+            } catch (error) {
+                console.error(`[Stream:${this.streamId}] Error in done handler ${index + 1}: ${error}`);
+            }
+        });
+        
+        // Clear all references
         this.queue = [];
         this.handlers = [];
         this.doneHandlers = [];
+        
+        console.log(`[Stream:${this.streamId}] Stream closed and cleaned up`);
     }
 
     feed(data: any): void {
-        if (!this.closed) {
-            this.queue.push(data);
-            this.handlers.forEach(handler => handler(data));
+        const feedStart = Date.now();
+        
+        if (this.closed) {
+            console.warn(`[Stream:${this.streamId}] Attempted to feed data to closed stream - Data type: ${typeof data}`);
+            return;
+        }
+        
+        this.feedCount++;
+        const handlerCount = this.handlers.length;
+        
+        console.log(`[Stream:${this.streamId}] FEEDING data - Feed #${this.feedCount}, Handlers: ${handlerCount}, Queue size before: ${this.queue.length}`);
+        
+        this.queue.push(data);
+        
+        // Notify all handlers
+        let successCount = 0;
+        let errorCount = 0;
+        
+        this.handlers.forEach((handler, index) => {
+            try {
+                const handlerStart = Date.now();
+                handler(data);
+                const handlerDuration = Date.now() - handlerStart;
+                successCount++;
+                
+                if (handlerDuration > 50) {
+                    console.warn(`[Stream:${this.streamId}] SLOW handler - Handler ${index + 1}/${handlerCount}, Duration: ${handlerDuration}ms`);
+                }
+            } catch (error) {
+                errorCount++;
+                console.error(`[Stream:${this.streamId}] ERROR in handler ${index + 1}/${handlerCount}: ${error}`);
+            }
+        });
+        
+        const totalDuration = Date.now() - feedStart;
+        console.log(`[Stream:${this.streamId}] Feed complete - Success: ${successCount}, Errors: ${errorCount}, Queue size after: ${this.queue.length}, Duration: ${totalDuration}ms`);
+        
+        if (totalDuration > 100) {
+            console.warn(`[Stream:${this.streamId}] SLOW feed operation - Duration: ${totalDuration}ms`);
         }
     }
 }

package/src/postgres/postgres-store.ts

@@ -46,6 +46,10 @@ import { ResultSetFact, ResultSetRow, ResultSetTree, resultSqlFromSpecification,
 import { sqlFromFeed } from "./specification-sql";
 import { purgeDescendantsSql, purgeSqlFromSpecification } from "./purge-sql";
 
+interface PostgresFactRecord extends FactRecord {
+    timestamp: Date;  // Maps to date_learned column
+}
+
 interface FactTypeResult {
     rows: {
         fact_type_id: number;
@@ -91,6 +95,7 @@ interface AncestorResult {
         data: string;
         public_key: string;
         signature: string;
+        date_learned: Date;
     }[];
 }
 
@@ -353,15 +358,15 @@ export class PostgresStore implements Storage {
         const factParameters = flatten(references, (f) =>
             [f.hash, factTypes.get(f.type)]);
         const sql =
-            'SELECT f.fact_type_id, f.name, f.hash, f.data, s.public_key, s.signature ' +
-            'FROM (SELECT f.fact_id, f.fact_type_id, t.name, f.hash, f.data ' +
+            'SELECT f.fact_type_id, f.name, f.hash, f.data, f.date_learned, s.public_key, s.signature ' +
+            'FROM (SELECT f.fact_id, f.fact_type_id, t.name, f.hash, f.data, f.date_learned ' +
                 `FROM ${this.schema}.fact f ` +
                 `JOIN ${this.schema}.fact_type t ` +
                 '  ON f.fact_type_id = t.fact_type_id ' +
                 'JOIN (VALUES ' + factValues.join(', ') + ') AS v (hash, fact_type_id) ' +
                 '  ON v.fact_type_id = f.fact_type_id AND v.hash = f.hash ' +
                 'UNION ' +
-                'SELECT f2.fact_id, f2.fact_type_id, t.name, f2.hash, f2.data ' +
+                'SELECT f2.fact_id, f2.fact_type_id, t.name, f2.hash, f2.data, f2.date_learned ' +
                 `FROM ${this.schema}.fact f1 ` +
                 'JOIN (VALUES ' + factValues.join(', ') + ') AS v (hash, fact_type_id) ' +
                 '  ON v.fact_type_id = f1.fact_type_id AND v.hash = f1.hash ' +
@@ -387,11 +392,12 @@ export class PostgresStore implements Storage {
         this.factTypeMap = mergeFactTypes(this.factTypeMap, resultFactTypes);
         const records = result.rows.map((r) => {
             const { fields, predecessors }: { fields: {}, predecessors: PredecessorCollection } = r.data as any;
-            const fact: FactRecord = {
+            const fact: PostgresFactRecord = {
                 type: r.name,
                 hash: r.hash,
                 fields,
-                predecessors
+                predecessors,
+                timestamp: r.date_learned
             };
             const signature: FactSignature = {
                 publicKey: r.public_key,
@@ -523,7 +529,8 @@ async function executeQueryTree(sqlQueryTree: SqlQueryTree, connection: PoolClie
             const fact: ResultSetFact = {
                 hash: dataRow[`hash${label.index}`],
                 factId: dataRow[`id${label.index}`],
-                data: dataRow[`data${label.index}`]
+                data: dataRow[`data${label.index}`],
+                timestamp: dataRow[`timestamp${label.index}`],
             };
             return {
                 ...acc,

package/src/postgres/purge-sql.ts

@@ -47,9 +47,25 @@ export function purgeSqlFromSpecification(specification: Specification, factType
 
     let queryDescription = QueryDescription.unsatisfiable;
     let knownFacts: FactByLabel = {};
-    const given = specification.given;
-    const start: FactReference[] = specification.given.map(g => ({ type: g.type, hash: 'xxxxx' }));
+    const given = specification.given.map(g => g.label);
+    const start: FactReference[] = specification.given.map(g => ({ type: g.label.type, hash: 'xxxxx' }));
+    
+    // Process main matches
     ({ queryDescription, knownFacts } = queryDescriptionBuilder.addEdges(queryDescription, given, start, knownFacts, [], specification.matches));
+    
+    // Process conditions from given
+    for (const givenItem of specification.given) {
+        if (givenItem.conditions && givenItem.conditions.length > 0) {
+            for (const condition of givenItem.conditions) {
+                const { query: queryDescriptionWithExistential, path: conditionalPath } = queryDescription.withExistentialCondition(condition.exists, []);
+                const { queryDescription: queryDescriptionConditional } = queryDescriptionBuilder.addEdges(queryDescriptionWithExistential, given, start, knownFacts, conditionalPath, condition.matches);
+                
+                if (queryDescriptionConditional.isSatisfiable()) {
+                    queryDescription = queryDescriptionConditional;
+                }
+            }
+        }
+    }
 
     if (!queryDescription.isSatisfiable()) {
         return null;

package/src/postgres/specification-result-sql.ts

@@ -6,7 +6,6 @@ import {
     FieldProjection,
     HashProjection,
     hydrateFromTree,
-    Label,
     Match,
     PredecessorCollection,
     ProjectedResult,
@@ -14,7 +13,9 @@ import {
     ReferencesByName,
     SingularProjection,
     Specification,
+    SpecificationGiven,
     SpecificationProjection,
+    TimeProjection,
     validateGiven
 } from "jinaga";
 
@@ -24,7 +25,7 @@ import { EdgeDescription, ExistentialConditionDescription, FactByLabel, QueryDes
 function generateResultSqlQuery(queryDescription: QueryDescription, schema: string): SpecificationSqlQuery {
     const allLabels = [ ...queryDescription.inputs, ...queryDescription.outputs ];
     const columns = allLabels
-        .map(label => `f${label.factIndex}.hash as hash${label.factIndex}, f${label.factIndex}.fact_id as id${label.factIndex}, f${label.factIndex}.data as data${label.factIndex}`)
+        .map(label => `f${label.factIndex}.hash as hash${label.factIndex}, f${label.factIndex}.fact_id as id${label.factIndex}, f${label.factIndex}.data as data${label.factIndex}, f${label.factIndex}.date_learned as timestamp${label.factIndex}`)
         .join(", ");
     const firstEdge = queryDescription.edges[0];
     const predecessorFact = queryDescription.inputs.find(i => i.factIndex === firstEdge.predecessorFactIndex);
@@ -32,6 +33,8 @@ function generateResultSqlQuery(queryDescription: QueryDescription, schema: stri
     const firstFactIndex = predecessorFact ? predecessorFact.factIndex : successorFact!.factIndex;
     const writtenFactIndexes = new Set<number>().add(firstFactIndex);
     const joins: string[] = generateJoins(queryDescription.edges, writtenFactIndexes, schema);
+    // Add all input fact indexes to writtenFactIndexes since they're available in the FROM clause
+    queryDescription.inputs.forEach(input => writtenFactIndexes.add(input.factIndex));
     const inputWhereClauses = queryDescription.inputs
         .map(input => `f${input.factIndex}.fact_type_id = $${input.factTypeParameter} AND f${input.factIndex}.hash = $${input.factHashParameter}`)
         .join(" AND ");
@@ -197,6 +200,7 @@ export interface ResultSetFact {
     hash: string;
     factId: number;
     data: ResultSetData;
+    timestamp: Date;
 }
 
 export interface ResultSetRow {
@@ -411,6 +415,9 @@ export class ResultComposer {
         else if (this.resultProjection.type === "fact") {
             return this.factValue(this.resultProjection, row, factRecords);
         }
+        else if (this.resultProjection.type === "time") {
+            return this.timeValue(this.resultProjection, row);
+        }
         else {
             const _exhaustiveCheck: never = this.resultProjection;
             throw new Error(`Unknown projection type ${(this.resultProjection as any).type}`);
@@ -439,6 +446,9 @@ export class ResultComposer {
             // This should have already been taken care of
             return null;
         }
+        else if (projection.type === "time") {
+            return this.timeValue(projection, row);
+        }
         else {
             const _exhaustiveCheck: never = projection;
             throw new Error(`Unknown projection type ${(projection as any).type}`);
@@ -465,6 +475,11 @@ export class ResultComposer {
         return fact;
     }
 
+    private timeValue(projection: TimeProjection, row: ResultSetRow): any {
+        const label = this.getLabel(projection.label);
+        return row[label.index].timestamp;
+    }
+
     private getLabel(name: string) {
         const label = this.sqlQuery.labels.find(label => label.name === name);
         if (!label) {
@@ -487,15 +502,62 @@ class ResultDescriptionBuilder {
     buildDescription(start: FactReference[], specification: Specification): ResultDescription {
         validateGiven(start, specification);
 
-        return this.createResultDescription(QueryDescription.unsatisfiable, specification.given, start, specification.matches, specification.projection, {}, []);
+        const labels = specification.given.map(g => g.label);
+        let queryDescription = QueryDescription.unsatisfiable;
+        let knownFacts: FactByLabel = {};
+        
+        // First process main matches to build the result description
+        const resultDescription = this.createResultDescription(queryDescription, specification.given, start, specification.matches, specification.projection, knownFacts, []);
+        
+        // Then process conditions from given if we have a satisfiable query
+        if (resultDescription.queryDescription.isSatisfiable()) {
+            queryDescription = resultDescription.queryDescription;
+            knownFacts = resultDescription.queryDescription.outputs.reduce((acc, output) => ({
+                ...acc,
+                [output.label]: { factIndex: output.factIndex, type: output.type }
+            }), {} as FactByLabel);
+            
+            // Also include inputs in knownFacts
+            for (const input of resultDescription.queryDescription.inputs) {
+                if (!knownFacts[input.label]) {
+                    knownFacts[input.label] = { factIndex: input.factIndex, type: input.type };
+                }
+            }
+            
+            // Process conditions from each given
+            for (const givenItem of specification.given) {
+                if (givenItem.conditions && givenItem.conditions.length > 0) {
+                    for (const condition of givenItem.conditions) {
+                        const { query: queryDescriptionWithExistential, path: conditionalPath } = queryDescription.withExistentialCondition(condition.exists, []);
+                        const { queryDescription: queryDescriptionConditional } = this.queryDescriptionBuilder.addEdges(queryDescriptionWithExistential, labels, start, knownFacts, conditionalPath, condition.matches);
+                        
+                        if (queryDescriptionConditional.isSatisfiable()) {
+                            queryDescription = queryDescriptionConditional;
+                        }
+                    }
+                }
+            }
+            
+            // Return updated result description with conditions applied
+            return {
+                ...resultDescription,
+                queryDescription
+            };
+        }
+        
+        return resultDescription;
     }
 
-    private createResultDescription(queryDescription: QueryDescription, given: Label[], start: FactReference[], matches: Match[], projection: Projection, knownFacts: FactByLabel, path: number[]): ResultDescription {
-        const givenTuple = given.reduce((acc, label, index) => ({
+    private createResultDescription(queryDescription: QueryDescription, given: SpecificationGiven[], start: FactReference[], matches: Match[], projection: Projection, knownFacts: FactByLabel, path: number[]): ResultDescription {
+        const givenTuple = given.reduce((acc, givenItem, index) => ({
             ...acc,
-            [label.name]: start[index]
+            [givenItem.label.name]: start[index]
         }), {} as ReferencesByName);
-        ({ queryDescription, knownFacts } = this.queryDescriptionBuilder.addEdges(queryDescription, given, start, knownFacts, path, matches));
+        
+        // Process main matches
+        const labels = given.map(g => g.label);
+        ({ queryDescription, knownFacts } = this.queryDescriptionBuilder.addEdges(queryDescription, labels, start, knownFacts, path, matches));
+        
         if (!queryDescription.isSatisfiable()) {
             // Abort the branch if the query is not satisfiable
             return {
@@ -513,7 +575,7 @@ class ResultDescriptionBuilder {
             const specificationProjections = projection.components
                 .filter(projection => projection.type === "specification") as ({ name: string } & SpecificationProjection)[];
             const singularProjections = projection.components
-                .filter(projection => projection.type === "field" || projection.type === "hash" || projection.type === "fact") as ({ name: string } & SingularProjection)[];
+                .filter(projection => projection.type === "field" || projection.type === "hash" || projection.type === "fact" || projection.type === "time") as ({ name: string } & SingularProjection)[];
             for (const child of specificationProjections) {
                 const childResultDescription = this.createResultDescription(queryDescription, given, start, child.matches, child.projection, knownFacts, []);
                 childResultDescriptions.push({

package/src/postgres/specification-sql.ts

@@ -40,9 +40,13 @@ function generateSqlQuery(queryDescription: QueryDescription, schema: string, bo
         .filter(c => c.exists === false))
         .map(notExistsWhereClause => ` AND NOT EXISTS (${generateNotExistsWhereClause(schema, notExistsWhereClause, writtenFactIndexes)})`)
         .join("");
+    const existsWhereClauses = (queryDescription.existentialConditions
+        .filter(c => c.exists === true))
+        .map(existsWhereClause => ` AND EXISTS (${generateNotExistsWhereClause(schema, existsWhereClause, writtenFactIndexes)})`)
+        .join("");
     const bookmarkParameter = queryDescription.parameters.length + 1;
     const limitParameter = bookmarkParameter + 1;
-    const sql = `SELECT ${hashes}, sort(array[${factIds}], 'desc') as bookmark FROM ${schema}.fact f${firstFactIndex}${joins.join("")} WHERE ${inputWhereClauses}${notExistsWhereClauses} AND sort(array[${factIds}], 'desc') > $${bookmarkParameter} ORDER BY bookmark ASC LIMIT $${limitParameter}`;
+    const sql = `SELECT ${hashes}, sort(array[${factIds}], 'desc') as bookmark FROM ${schema}.fact f${firstFactIndex}${joins.join("")} WHERE ${inputWhereClauses}${notExistsWhereClauses}${existsWhereClauses} AND sort(array[${factIds}], 'desc') > $${bookmarkParameter} ORDER BY bookmark ASC LIMIT $${limitParameter}`;
     const bookmarkValue: number[] = parseBookmark(bookmark);
     return {
         sql,
@@ -165,7 +169,7 @@ export function sqlFromSpecification(start: FactReference[], schema: string, boo
     validateGiven(start, specification);
 
     const labeledStart = start.map((s, index) => ({
-        name: specification.given[index].name,
+        name: specification.given[index].label.name,
         reference: s
     })).reduce((map, s) => {
         map.set(s.name, s.reference);
@@ -179,9 +183,9 @@ export function sqlFromSpecification(start: FactReference[], schema: string, boo
         bookmark: bookmarks[index]
     }));
     const queryDescriptionsAndBookmarks = feedAndBookmark.map(fb => {
-        const feedStart = fb.feed.given.map(s => labeledStart.get(s.name)!);
+        const feedStart = fb.feed.given.map(s => labeledStart.get(s.label.name)!);
         return {
-            queryDescription: buildQueryDescription(queryDescriptionBuilder, fb.feed, feedStart),
+            queryDescription: buildQueryDescription(queryDescriptionBuilder, fb.feed, feedStart, specification.given),
             bookmark: fb.bookmark
         };
     });
@@ -202,11 +206,35 @@ export function sqlFromFeed(feed: Specification, start: FactReference[], schema:
     return sql;
 }
 
-function buildQueryDescription(queryDescriptionBuilder: QueryDescriptionBuilder, specification: Specification, start: FactReference[]): QueryDescription {
-    const { queryDescription } = queryDescriptionBuilder.addEdges(
+function buildQueryDescription(queryDescriptionBuilder: QueryDescriptionBuilder, specification: Specification, start: FactReference[], originalGiven?: any[]): QueryDescription {
+    const labels = specification.given.map(g => g.label);
+    let knownFacts = {};
+    
+    // Process main matches
+    let { queryDescription, knownFacts: updatedKnownFacts } = queryDescriptionBuilder.addEdges(
         QueryDescription.unsatisfiable,
-        specification.given,
-        start, {}, [],
+        labels,
+        start,
+        knownFacts,
+        [],
         specification.matches);
+    knownFacts = updatedKnownFacts;
+    
+    // Process conditions from given (use originalGiven if provided, otherwise use specification.given)
+    const givenToProcess = originalGiven || specification.given;
+    for (const givenItem of givenToProcess) {
+        if (givenItem.conditions && givenItem.conditions.length > 0) {
+            for (const condition of givenItem.conditions) {
+                const { query: queryDescriptionWithExistential, path: conditionalPath } = queryDescription.withExistentialCondition(condition.exists, []);
+                const { queryDescription: queryDescriptionConditional, knownFacts: updatedKnownFacts } = queryDescriptionBuilder.addEdges(queryDescriptionWithExistential, labels, start, knownFacts, conditionalPath, condition.matches);
+                
+                if (queryDescriptionConditional.isSatisfiable()) {
+                    queryDescription = queryDescriptionConditional;
+                    knownFacts = updatedKnownFacts;
+                }
+            }
+        }
+    }
+    
     return queryDescription;
 }

package/test/http/csv-validatorSpec.ts

@@ -0,0 +1,205 @@
+import { validateSpecificationForCsv, extractValueByLabel, formatValueForCsv } from '../../src/http/csv-validator';
+import { Specification, SpecificationParser, CompositeProjection } from 'jinaga';
+
+describe('CSV Validator', () => {
+    describe('validateSpecificationForCsv', () => {
+        // Helper function to create a specification from declarative syntax
+        function GivenSpecificationFromInput(input: string): Specification {
+            const parser = new SpecificationParser(input);
+            return parser.parseSpecification();
+        }
+
+        it('should accept flat field projections', () => {
+            const input = `(root: Root) {
+                successor: Successor [
+                    successor->root: Root = root
+                ]
+            } => {
+                name = successor.name
+                count = successor.count
+            }`;
+            const specification = GivenSpecificationFromInput(input);
+
+            const metadata = validateSpecificationForCsv(specification);
+            
+            expect(metadata.isValid).toBe(true);
+            expect(metadata.headers).toEqual(['name', 'count']);
+            expect(metadata.errors).toEqual([]);
+        });
+
+        // Acceptance tests for future hash/timestamp support
+        it('should accept hash projections', () => {
+            const input = `(root: Root) {
+                successor: Successor [
+                    successor->root: Root = root
+                ]
+            } => {
+                hash = #successor
+            }`;
+            const specification = GivenSpecificationFromInput(input);
+
+            const metadata = validateSpecificationForCsv(specification);
+            
+            expect(metadata.errors).toEqual([]);
+            expect(metadata.isValid).toBe(true);
+            expect(metadata.headers).toEqual(['hash']);
+        });
+
+        it('should accept timestamp projections', () => {
+            const input = `(root: Root) {
+                successor: Successor [
+                    successor->root: Root = root
+                ]
+            } => {
+                timestamp = @successor
+            }`;
+            const specification = GivenSpecificationFromInput(input);
+
+            const metadata = validateSpecificationForCsv(specification);
+            
+            expect(metadata.isValid).toBe(true);
+            expect(metadata.headers).toEqual(['timestamp']);
+        });
+
+        it('should reject nested projections', () => {
+            const specification = GivenSpecificationFromInput(`(root: Root) {
+                successor: Successor [
+                    successor->root: Root = root
+                ]
+            } => {
+                nested = {
+                    grandchild: Grandchild [
+                        grandchild->successor: Successor = successor
+                    ]
+                } => {
+                    name = grandchild.name
+                }
+            }`);
+
+            const metadata = validateSpecificationForCsv(specification);
+            
+            expect(metadata.isValid).toBe(false);
+            expect(metadata.errors.length).toBeGreaterThan(0);
+            expect(metadata.errors).toEqual([`Unsupported projection type of field 'nested' for CSV export. Only flat field projections are allowed.`]);
+        });
+
+        it('should reject fact projections', () => {
+            const specification = GivenSpecificationFromInput(`(root: Root) {
+                successor: Successor [
+                    successor->root: Root = root
+                ]
+            } => {
+                successor = successor
+            }`);
+
+            const metadata = validateSpecificationForCsv(specification);
+            
+            expect(metadata.isValid).toBe(false);
+            expect(metadata.errors.length).toBeGreaterThan(0);
+            expect(metadata.errors).toEqual([`Unsupported projection type of field 'successor' for CSV export. Only flat field projections are allowed.`]);
+        });
+
+        it('should reject non-composite top-level projections', () => {
+            const specification = GivenSpecificationFromInput(`(root: Root) {
+                successor: Successor [
+                    successor->root: Root = root
+                ]
+            } => successor.name`);
+
+            const metadata = validateSpecificationForCsv(specification);
+            
+            expect(metadata.isValid).toBe(false);
+            expect(metadata.errors).toContain('Specification projection must be composite for CSV export');
+        });
+
+        it('should reject specification without projection', () => {
+            const specification = GivenSpecificationFromInput(`(root: Root) {
+                successor: Successor [
+                    successor->root: Root = root
+                ]
+            }`);
+
+            const metadata = validateSpecificationForCsv(specification);
+            
+            expect(metadata.isValid).toBe(false);
+            expect(metadata.errors).toEqual(['Specification must have a projection for CSV export']);
+        });
+
+        it('should handle mixed valid and invalid projections', () => {
+            const specification = GivenSpecificationFromInput(`(root: Root) {
+                successor: Successor [
+                    successor->root: Root = root
+                ]
+            } => {
+                name = successor.name
+                nested = {
+                    grandchild: Grandchild [
+                        grandchild->successor: Successor = successor
+                    ]
+                } => {
+                    name = grandchild.name
+                }
+                count = successor.count
+                successor = successor
+            }`);
+
+            const metadata = validateSpecificationForCsv(specification);
+            
+            expect(metadata.isValid).toBe(false);
+            expect(metadata.headers).toEqual(['name', 'count']); // Only valid field projections
+            expect(metadata.errors).toEqual([
+                `Unsupported projection type of field 'nested' for CSV export. Only flat field projections are allowed.`,
+                `Unsupported projection type of field 'successor' for CSV export. Only flat field projections are allowed.`
+            ]);
+        });
+    });
+
+    describe('extractValueByLabel', () => {
+        it('should extract direct property', () => {
+            const result = { name: 'Alice', age: 30 };
+            
+            expect(extractValueByLabel(result, 'name')).toBe('Alice');
+            expect(extractValueByLabel(result, 'age')).toBe(30);
+        });
+
+        it('should return null for missing properties', () => {
+            const result = { name: 'Alice' };
+            
+            expect(extractValueByLabel(result, 'age')).toBeNull();
+        });
+
+        it('should return null for null result', () => {
+            expect(extractValueByLabel(null, 'name')).toBeNull();
+        });
+
+        it('should return null for undefined result', () => {
+            expect(extractValueByLabel(undefined, 'name')).toBeNull();
+        });
+    });
+
+    describe('formatValueForCsv', () => {
+        it('should return empty string for null', () => {
+            expect(formatValueForCsv(null)).toBe('');
+        });
+
+        it('should return empty string for undefined', () => {
+            expect(formatValueForCsv(undefined)).toBe('');
+        });
+
+        it('should format Date as ISO string', () => {
+            const date = new Date('2024-01-15T10:30:00.000Z');
+            expect(formatValueForCsv(date)).toBe('2024-01-15T10:30:00.000Z');
+        });
+
+        it('should format boolean as string', () => {
+            expect(formatValueForCsv(true)).toBe('true');
+            expect(formatValueForCsv(false)).toBe('false');
+        });
+
+        it('should convert primitives to string', () => {
+            expect(formatValueForCsv('hello')).toBe('hello');
+            expect(formatValueForCsv(42)).toBe('42');
+            expect(formatValueForCsv(3.14)).toBe('3.14');
+        });
+    });
+});