@the-cascade-protocol/sdk 1.0.0

package/dist/serializer/turtle-builder.js

@@ -0,0 +1,204 @@
+/**
+ * Fluent builder API for constructing Turtle (Terse RDF Triple Language) documents.
+ *
+ * Provides a class-based API for building well-formed Turtle output with
+ * proper prefix declarations, typed literals, URI references, blank nodes,
+ * and RDF lists.
+ *
+ * @example
+ * ```typescript
+ * import { TurtleBuilder } from '@the-cascade-protocol/sdk';
+ *
+ * const turtle = new TurtleBuilder()
+ *   .prefix('cascade', 'https://ns.cascadeprotocol.org/core/v1#')
+ *   .prefix('health', 'https://ns.cascadeprotocol.org/health/v1#')
+ *   .subject('<urn:uuid:abc>')
+ *     .type('health:MedicationRecord')
+ *     .literal('health:medicationName', 'Lisinopril')
+ *     .boolean('health:isActive', true)
+ *     .done()
+ *   .build();
+ * ```
+ *
+ * @module serializer
+ */
+// ─── String Escaping ────────────────────────────────────────────────────────
+/**
+ * Escape a string value for use in a Turtle literal.
+ *
+ * Handles backslashes, double quotes, newlines, carriage returns, and tabs.
+ * For very long strings (> 200 chars) or strings containing embedded newlines,
+ * uses triple-quoted long literals.
+ */
+export function escapeTurtleString(value) {
+    // Use triple-quoted long literal for very long strings or strings with embedded newlines
+    if (value.length > 200 || value.includes('\n')) {
+        const longEscaped = value
+            .replace(/\\/g, '\\\\')
+            .replace(/"""/g, '\\"\\"\\"');
+        return `"""${longEscaped}"""`;
+    }
+    const escaped = value
+        .replace(/\\/g, '\\\\')
+        .replace(/"/g, '\\"')
+        .replace(/\n/g, '\\n')
+        .replace(/\r/g, '\\r')
+        .replace(/\t/g, '\\t');
+    return `"${escaped}"`;
+}
+// ─── SubjectBuilder ─────────────────────────────────────────────────────────
+/**
+ * Builder for adding predicate-object pairs to a single RDF subject.
+ *
+ * Obtained via `TurtleBuilder.subject()`. Call `.done()` to return to the
+ * parent `TurtleBuilder`.
+ */
+export class SubjectBuilder {
+    _parent;
+    _subject;
+    _predicates = [];
+    /** @internal */
+    constructor(parent, subject) {
+        this._parent = parent;
+        this._subject = subject;
+    }
+    /** Add an `rdf:type` declaration. */
+    type(rdfType) {
+        this._predicates.push(`a ${rdfType}`);
+        return this;
+    }
+    /** Add a plain string literal. Optionally with a datatype IRI. */
+    literal(predicate, value, datatype) {
+        if (datatype) {
+            this._predicates.push(`${predicate} ${escapeTurtleString(value)}^^${datatype}`);
+        }
+        else {
+            this._predicates.push(`${predicate} ${escapeTurtleString(value)}`);
+        }
+        return this;
+    }
+    /** Add a URI reference (angle-bracket enclosed). */
+    uri(predicate, uriValue) {
+        // If already prefixed (e.g., cascade:ClinicalGenerated), use as-is
+        if (/^[a-zA-Z][\w-]*:[\w-]+$/.test(uriValue)) {
+            this._predicates.push(`${predicate} ${uriValue}`);
+        }
+        else {
+            this._predicates.push(`${predicate} <${uriValue}>`);
+        }
+        return this;
+    }
+    /** Add a boolean literal (unquoted `true` or `false`). */
+    boolean(predicate, value) {
+        this._predicates.push(`${predicate} ${value}`);
+        return this;
+    }
+    /** Add an integer literal with `^^xsd:integer` datatype. */
+    integer(predicate, value) {
+        this._predicates.push(`${predicate} "${value}"^^xsd:integer`);
+        return this;
+    }
+    /** Add a double/decimal literal with `^^xsd:double` datatype. */
+    double(predicate, value) {
+        this._predicates.push(`${predicate} "${value}"^^xsd:double`);
+        return this;
+    }
+    /** Add a plain numeric value (no datatype annotation, for integers). */
+    number(predicate, value) {
+        this._predicates.push(`${predicate} ${value}`);
+        return this;
+    }
+    /** Add a `^^xsd:dateTime` typed literal. */
+    dateTime(predicate, value) {
+        this._predicates.push(`${predicate} "${value}"^^xsd:dateTime`);
+        return this;
+    }
+    /** Add a `^^xsd:date` typed literal. */
+    date(predicate, value) {
+        this._predicates.push(`${predicate} "${value}"^^xsd:date`);
+        return this;
+    }
+    /** Add an RDF list (Turtle shorthand `( item1 item2 ... )`). Items are treated as string literals. */
+    list(predicate, items) {
+        const formatted = items.map((item) => escapeTurtleString(item)).join(' ');
+        this._predicates.push(`${predicate} ( ${formatted} )`);
+        return this;
+    }
+    /** Add a blank node with nested predicate-object pairs. */
+    blankNode(predicate, callback) {
+        const inner = new SubjectBuilder(this._parent, '');
+        callback(inner);
+        const innerLines = inner._predicates.map((p, i, arr) => {
+            const sep = i < arr.length - 1 ? ' ;' : '';
+            return `        ${p}${sep}`;
+        });
+        this._predicates.push(`${predicate} [\n${innerLines.join('\n')}\n    ]`);
+        return this;
+    }
+    /** Finalize this subject block and return to the parent TurtleBuilder. */
+    done() {
+        this._parent._addSubjectBlock(this._subject, this._predicates);
+        return this._parent;
+    }
+}
+// ─── TurtleBuilder ──────────────────────────────────────────────────────────
+/**
+ * Fluent builder for constructing complete Turtle documents.
+ *
+ * Usage:
+ * 1. Add prefix declarations with `.prefix()`
+ * 2. Add subject blocks with `.subject()` -> `SubjectBuilder` -> `.done()`
+ * 3. Call `.build()` to produce the final Turtle string
+ */
+export class TurtleBuilder {
+    _prefixes = new Map();
+    _blocks = [];
+    /** Declare a namespace prefix. */
+    prefix(prefixName, uri) {
+        this._prefixes.set(prefixName, uri);
+        return this;
+    }
+    /** Begin a new subject block. Returns a SubjectBuilder for adding predicates. */
+    subject(uri) {
+        return new SubjectBuilder(this, uri);
+    }
+    /**
+     * @internal
+     * Called by SubjectBuilder.done() to register a completed subject block.
+     */
+    _addSubjectBlock(subject, predicates) {
+        if (predicates.length === 0)
+            return;
+        const lines = [];
+        if (predicates.length === 1) {
+            // Single predicate: subject and predicate on the same line
+            lines.push(`${subject} ${predicates[0]} .`);
+        }
+        else {
+            // First predicate on the same line as the subject
+            lines.push(`${subject} ${predicates[0]} ;`);
+            // Remaining predicates indented
+            for (let i = 1; i < predicates.length; i++) {
+                const isLast = i === predicates.length - 1;
+                lines.push(`    ${predicates[i]}${isLast ? ' .' : ' ;'}`);
+            }
+        }
+        this._blocks.push(lines.join('\n'));
+    }
+    /** Build the complete Turtle document string. */
+    build() {
+        const parts = [];
+        // Prefix declarations
+        for (const [name, uri] of this._prefixes) {
+            parts.push(`@prefix ${name}: <${uri}> .`);
+        }
+        // Blank line between prefixes and content
+        if (this._prefixes.size > 0 && this._blocks.length > 0) {
+            parts.push('');
+        }
+        // Subject blocks
+        parts.push(...this._blocks);
+        return parts.join('\n') + '\n';
+    }
+}
+//# sourceMappingURL=turtle-builder.js.map

package/dist/serializer/turtle-builder.js.map

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

package/dist/serializer/turtle-serializer.d.ts

@@ -0,0 +1,66 @@
+/**
+ * High-level serialization functions for converting Cascade Protocol
+ * data model objects to Turtle (RDF) format.
+ *
+ * Uses the {@link TurtleBuilder} internally and produces output conforming
+ * to the Cascade Protocol conformance fixtures.
+ *
+ * @example
+ * ```typescript
+ * import { serialize, serializeMedication } from '@the-cascade-protocol/sdk';
+ *
+ * const turtle = serializeMedication(myMed);
+ * // or generically:
+ * const turtle2 = serialize(myRecord);
+ * ```
+ *
+ * @module serializer
+ */
+import type { CascadeRecord } from '../models/common.js';
+import type { Medication } from '../models/medication.js';
+import type { Condition } from '../models/condition.js';
+import type { Allergy } from '../models/allergy.js';
+import type { LabResult } from '../models/lab-result.js';
+import type { VitalSign } from '../models/vital-sign.js';
+import type { Immunization } from '../models/immunization.js';
+import type { Procedure } from '../models/procedure.js';
+import type { FamilyHistory } from '../models/family-history.js';
+import type { Coverage } from '../models/coverage.js';
+import type { PatientProfile } from '../models/patient-profile.js';
+import type { ActivitySnapshot } from '../models/activity-snapshot.js';
+import type { SleepSnapshot } from '../models/sleep-snapshot.js';
+/**
+ * Serialize any Cascade Protocol record to Turtle format.
+ *
+ * Dispatches based on the `type` field of the record. The output matches
+ * the conformance fixture expected Turtle format.
+ *
+ * @param record - Any CascadeRecord (Medication, Condition, VitalSign, etc.)
+ * @returns A complete Turtle document string
+ */
+export declare function serialize(record: CascadeRecord): string;
+/** Serialize a Medication record to Turtle. */
+export declare function serializeMedication(med: Medication): string;
+/** Serialize a Condition record to Turtle. */
+export declare function serializeCondition(cond: Condition): string;
+/** Serialize an Allergy record to Turtle. */
+export declare function serializeAllergy(allergy: Allergy): string;
+/** Serialize a LabResult record to Turtle. */
+export declare function serializeLabResult(lab: LabResult): string;
+/** Serialize a VitalSign record to Turtle. */
+export declare function serializeVitalSign(vital: VitalSign): string;
+/** Serialize an Immunization record to Turtle. */
+export declare function serializeImmunization(imm: Immunization): string;
+/** Serialize a Procedure record to Turtle. */
+export declare function serializeProcedure(proc: Procedure): string;
+/** Serialize a FamilyHistory record to Turtle. */
+export declare function serializeFamilyHistory(fam: FamilyHistory): string;
+/** Serialize a Coverage record to Turtle. */
+export declare function serializeCoverage(cov: Coverage): string;
+/** Serialize a PatientProfile record to Turtle. */
+export declare function serializePatientProfile(profile: PatientProfile): string;
+/** Serialize an ActivitySnapshot record to Turtle. */
+export declare function serializeActivitySnapshot(activity: ActivitySnapshot): string;
+/** Serialize a SleepSnapshot record to Turtle. */
+export declare function serializeSleepSnapshot(sleep: SleepSnapshot): string;
+//# sourceMappingURL=turtle-serializer.d.ts.map

package/dist/serializer/turtle-serializer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"turtle-serializer.d.ts","sourceRoot":"","sources":["../../src/serializer/turtle-serializer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAIH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAC1D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AACpD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AACzD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AACzD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAC9D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AACjE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AACnE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AACvE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAwLjE;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CAEvD;AAkLD,+CAA+C;AAC/C,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM,CAE3D;AAED,8CAA8C;AAC9C,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAE1D;AAED,6CAA6C;AAC7C,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAEzD;AAED,8CAA8C;AAC9C,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,SAAS,GAAG,MAAM,CAEzD;AAED,8CAA8C;AAC9C,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,CAE3D;AAED,kDAAkD;AAClD,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,YAAY,GAAG,MAAM,CAE/D;AAED,8CAA8C;AAC9C,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAE1D;AAED,kDAAkD;AAClD,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CAEjE;AAED,6CAA6C;AAC7C,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,QAAQ,GAAG,MAAM,CAEvD;AAED,mDAAmD;AACnD,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,cAAc,GAAG,MAAM,CAEvE;AAED,sDAAsD;AACtD,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,gBAAgB,GAAG,MAAM,CAE5E;AAED,kDAAkD;AAClD,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CAEnE"}

package/dist/serializer/turtle-serializer.js

@@ -0,0 +1,404 @@
+/**
+ * High-level serialization functions for converting Cascade Protocol
+ * data model objects to Turtle (RDF) format.
+ *
+ * Uses the {@link TurtleBuilder} internally and produces output conforming
+ * to the Cascade Protocol conformance fixtures.
+ *
+ * @example
+ * ```typescript
+ * import { serialize, serializeMedication } from '@the-cascade-protocol/sdk';
+ *
+ * const turtle = serializeMedication(myMed);
+ * // or generically:
+ * const turtle2 = serialize(myRecord);
+ * ```
+ *
+ * @module serializer
+ */
+import { TurtleBuilder } from './turtle-builder.js';
+import { NAMESPACES, PROPERTY_PREDICATES, TYPE_MAPPING, TYPE_TO_MAPPING_KEY } from '../vocabularies/namespaces.js';
+// ─── Internal Helpers ───────────────────────────────────────────────────────
+/**
+ * Type-specific predicate overrides.
+ *
+ * When a JSON field name maps to different RDF predicates depending on the
+ * record type, these overrides take precedence over PROPERTY_PREDICATES.
+ *
+ * For example, `snomedCode` maps to `health:snomedCode` for Conditions
+ * but `clinical:snomedCode` for VitalSigns.
+ */
+const TYPE_PREDICATE_OVERRIDES = {
+    VitalSign: {
+        snomedCode: 'clinical:snomedCode',
+        interpretation: 'clinical:interpretation',
+    },
+};
+/**
+ * Get the predicate for a given field and record type, respecting overrides.
+ */
+function getPredicateForField(key, recordType) {
+    const overrides = TYPE_PREDICATE_OVERRIDES[recordType];
+    if (overrides && key in overrides) {
+        return overrides[key];
+    }
+    return PROPERTY_PREDICATES[key];
+}
+/**
+ * Fields whose values should be serialized as URI references (angle-bracket enclosed)
+ * rather than string literals, when the value looks like a full URI.
+ */
+const URI_FIELDS = new Set([
+    'rxNormCode',
+    'icd10Code',
+    'snomedCode',
+    'loincCode',
+    'testCode',
+]);
+/**
+ * Fields whose values are arrays of URIs or strings and should be serialized
+ * as repeated predicate triples (one per value).
+ */
+const ARRAY_FIELDS = new Set([
+    'drugCodes',
+    'affectsVitalSigns',
+    'monitoredVitalSigns',
+]);
+/**
+ * Explicit set of fields that are dateTime-typed even though their names
+ * don't contain "date" or "time" as a substring.
+ */
+const EXPLICIT_DATETIME_FIELDS = new Set([
+    'effectivePeriodStart',
+    'effectivePeriodEnd',
+    'effectiveStart',
+    'effectiveEnd',
+]);
+/**
+ * Fields whose values contain date/time and get ^^xsd:dateTime typing.
+ * We check the key name and a set of explicit fields.
+ */
+function isDateTimeField(key) {
+    if (EXPLICIT_DATETIME_FIELDS.has(key))
+        return true;
+    const lower = key.toLowerCase();
+    // Specific date-only field
+    if (key === 'dateOfBirth' || key === 'date')
+        return false;
+    return lower.includes('date') || lower.includes('time');
+}
+/**
+ * Fields whose values are date-only (no time component) and get ^^xsd:date typing.
+ */
+function isDateOnlyField(key) {
+    return key === 'dateOfBirth';
+}
+/**
+ * Fields that represent integers with ^^xsd:integer typing in the expected output.
+ */
+const INTEGER_FIELDS = new Set([
+    'computedAge',
+    'refillsAllowed',
+    'supplyDurationDays',
+    'onsetAge',
+]);
+/**
+ * Fields that are boolean and should be serialized unquoted.
+ */
+function isBooleanField(_key, value) {
+    return typeof value === 'boolean';
+}
+/**
+ * Determine which prefixes are needed for a given record.
+ */
+function collectPrefixes(record) {
+    const prefixes = new Map();
+    // Always include cascade and xsd
+    prefixes.set('cascade', NAMESPACES.cascade);
+    prefixes.set('xsd', NAMESPACES.xsd);
+    // Get the rdfType to determine base vocabulary
+    const mappingKey = TYPE_TO_MAPPING_KEY[record.type];
+    if (mappingKey) {
+        const mapping = TYPE_MAPPING[mappingKey];
+        if (mapping) {
+            const rdfType = mapping.rdfType;
+            const nsPrefix = rdfType.split(':')[0];
+            if (nsPrefix && nsPrefix in NAMESPACES) {
+                prefixes.set(nsPrefix, NAMESPACES[nsPrefix]);
+            }
+        }
+    }
+    // Scan all fields and add namespaces for predicates and URI values
+    for (const [key, value] of Object.entries(record)) {
+        if (key === 'id' || key === 'type' || value === undefined || value === null)
+            continue;
+        const pred = getPredicateForField(key, record.type);
+        if (pred) {
+            const nsPrefix = pred.split(':')[0];
+            if (nsPrefix && nsPrefix in NAMESPACES) {
+                prefixes.set(nsPrefix, NAMESPACES[nsPrefix]);
+            }
+        }
+        // Check URI values for namespace references
+        if (typeof value === 'string' && URI_FIELDS.has(key)) {
+            addPrefixForUri(value, prefixes);
+        }
+        if (Array.isArray(value) && ARRAY_FIELDS.has(key)) {
+            for (const item of value) {
+                if (typeof item === 'string' && item.startsWith('http')) {
+                    addPrefixForUri(item, prefixes);
+                }
+            }
+        }
+    }
+    return prefixes;
+}
+function addPrefixForUri(uri, prefixes) {
+    for (const [prefix, ns] of Object.entries(NAMESPACES)) {
+        if (uri.startsWith(ns) || uri.startsWith(ns.replace(/#$/, '/'))) {
+            prefixes.set(prefix, ns);
+            break;
+        }
+    }
+}
+/**
+ * Determine the stable order for prefix declarations.
+ * The order follows: cascade, health, clinical, coverage, then
+ * external namespaces (rxnorm, sct, loinc, icd10, foaf), then xsd.
+ */
+function sortedPrefixes(prefixes) {
+    const order = [
+        'cascade', 'health', 'clinical', 'coverage', 'checkup', 'pots',
+        'fhir', 'rxnorm', 'sct', 'loinc', 'icd10', 'ucum',
+        'prov', 'foaf', 'ldp', 'dcterms', 'xsd',
+    ];
+    const entries = Array.from(prefixes.entries());
+    entries.sort((a, b) => {
+        const ai = order.indexOf(a[0]);
+        const bi = order.indexOf(b[0]);
+        const aIdx = ai >= 0 ? ai : order.length;
+        const bIdx = bi >= 0 ? bi : order.length;
+        return aIdx - bIdx;
+    });
+    return entries;
+}
+// ─── Generic Serializer ─────────────────────────────────────────────────────
+/**
+ * Serialize any Cascade Protocol record to Turtle format.
+ *
+ * Dispatches based on the `type` field of the record. The output matches
+ * the conformance fixture expected Turtle format.
+ *
+ * @param record - Any CascadeRecord (Medication, Condition, VitalSign, etc.)
+ * @returns A complete Turtle document string
+ */
+export function serialize(record) {
+    return serializeRecord(record);
+}
+/**
+ * Internal workhorse that serializes any record.
+ */
+function serializeRecord(record) {
+    const mappingKey = TYPE_TO_MAPPING_KEY[record.type];
+    const mapping = mappingKey ? TYPE_MAPPING[mappingKey] : undefined;
+    if (!mapping) {
+        throw new Error(`Unknown record type: ${record.type}. No TYPE_MAPPING found.`);
+    }
+    const prefixes = collectPrefixes(record);
+    const builder = new TurtleBuilder();
+    // Add prefixes in stable order
+    for (const [name, uri] of sortedPrefixes(prefixes)) {
+        builder.prefix(name, uri);
+    }
+    // Build the subject
+    const subjectUri = record.id.startsWith('urn:') || record.id.startsWith('http')
+        ? `<${record.id}>`
+        : `<${record.id}>`;
+    const sub = builder.subject(subjectUri);
+    sub.type(mapping.rdfType);
+    // Serialize fields in a deterministic order:
+    // 1. The "name" field (primary identifier)
+    // 2. Required CascadeRecord fields (dataProvenance, schemaVersion)
+    //    are placed after the type-specific required fields
+    // 3. All other fields in their natural object order
+    const rec = { ...record };
+    // Collect field entries, preserving the order they appear in the record,
+    // but ensuring a deterministic output that matches the conformance fixtures.
+    const fieldOrder = Object.keys(rec);
+    // Track fields we've already emitted
+    const emitted = new Set();
+    // Helper to emit a single field
+    const emitField = (key) => {
+        if (emitted.has(key))
+            return;
+        emitted.add(key);
+        const value = rec[key];
+        if (value === undefined || value === null)
+            return;
+        if (key === 'id' || key === 'type')
+            return;
+        const pred = getPredicateForField(key, record.type);
+        if (!pred)
+            return;
+        // dataProvenance is special: value is a prefixed name
+        if (key === 'dataProvenance') {
+            sub.uri(pred, `cascade:${String(value)}`);
+            return;
+        }
+        // Boolean fields
+        if (isBooleanField(key, value)) {
+            sub.boolean(pred, value);
+            return;
+        }
+        // Integer fields
+        if (INTEGER_FIELDS.has(key) && typeof value === 'number') {
+            sub.integer(pred, value);
+            return;
+        }
+        // Number fields (plain, untyped integers like clinical:value, referenceRangeLow, etc.)
+        if (typeof value === 'number') {
+            if (Number.isInteger(value)) {
+                sub.number(pred, value);
+            }
+            else {
+                sub.double(pred, value);
+            }
+            return;
+        }
+        // URI fields
+        if (URI_FIELDS.has(key) && typeof value === 'string') {
+            sub.uri(pred, value);
+            return;
+        }
+        // Array fields (repeated predicates for URI lists, RDF list for string lists)
+        if (Array.isArray(value) && ARRAY_FIELDS.has(key)) {
+            if (value.length === 0)
+                return;
+            // Check if items look like URIs
+            const isUriList = value.every((item) => typeof item === 'string' && item.startsWith('http'));
+            if (isUriList) {
+                for (const item of value) {
+                    sub.uri(pred, item);
+                }
+            }
+            else {
+                sub.list(pred, value.map(String));
+            }
+            return;
+        }
+        // Date-only fields
+        if (isDateOnlyField(key) && typeof value === 'string') {
+            sub.date(pred, value);
+            return;
+        }
+        // DateTime fields
+        if (isDateTimeField(key) && typeof value === 'string') {
+            sub.dateTime(pred, value);
+            return;
+        }
+        // Nested objects (blank nodes) for PatientProfile
+        if (typeof value === 'object' && !Array.isArray(value)) {
+            serializeBlankNode(sub, pred, key, value);
+            return;
+        }
+        // Default: string literal
+        if (typeof value === 'string') {
+            sub.literal(pred, value);
+            return;
+        }
+    };
+    // Emit all fields in the order they appear in the object
+    for (const key of fieldOrder) {
+        emitField(key);
+    }
+    sub.done();
+    return builder.build();
+}
+/**
+ * Serialize a nested object as a Turtle blank node.
+ */
+function serializeBlankNode(sub, predicate, key, obj) {
+    // Determine the blank node type based on the key
+    let bnodeType;
+    if (key === 'emergencyContact')
+        bnodeType = 'cascade:EmergencyContact';
+    else if (key === 'address')
+        bnodeType = 'cascade:Address';
+    else if (key === 'preferredPharmacy')
+        bnodeType = 'cascade:PharmacyInfo';
+    sub.blankNode(predicate, (b) => {
+        if (bnodeType) {
+            b.type(bnodeType);
+        }
+        for (const [k, v] of Object.entries(obj)) {
+            if (v === undefined || v === null)
+                continue;
+            // Look up predicate for nested field - try with 'cascade:' prefix for profile nested types
+            const nestedPred = `cascade:${k}`;
+            if (typeof v === 'string') {
+                b.literal(nestedPred, v);
+            }
+            else if (typeof v === 'boolean') {
+                b.boolean(nestedPred, v);
+            }
+            else if (typeof v === 'number') {
+                if (Number.isInteger(v)) {
+                    b.number(nestedPred, v);
+                }
+                else {
+                    b.double(nestedPred, v);
+                }
+            }
+        }
+    });
+}
+// ─── Type-Specific Serializers ──────────────────────────────────────────────
+/** Serialize a Medication record to Turtle. */
+export function serializeMedication(med) {
+    return serialize(med);
+}
+/** Serialize a Condition record to Turtle. */
+export function serializeCondition(cond) {
+    return serialize(cond);
+}
+/** Serialize an Allergy record to Turtle. */
+export function serializeAllergy(allergy) {
+    return serialize(allergy);
+}
+/** Serialize a LabResult record to Turtle. */
+export function serializeLabResult(lab) {
+    return serialize(lab);
+}
+/** Serialize a VitalSign record to Turtle. */
+export function serializeVitalSign(vital) {
+    return serialize(vital);
+}
+/** Serialize an Immunization record to Turtle. */
+export function serializeImmunization(imm) {
+    return serialize(imm);
+}
+/** Serialize a Procedure record to Turtle. */
+export function serializeProcedure(proc) {
+    return serialize(proc);
+}
+/** Serialize a FamilyHistory record to Turtle. */
+export function serializeFamilyHistory(fam) {
+    return serialize(fam);
+}
+/** Serialize a Coverage record to Turtle. */
+export function serializeCoverage(cov) {
+    return serialize(cov);
+}
+/** Serialize a PatientProfile record to Turtle. */
+export function serializePatientProfile(profile) {
+    return serialize(profile);
+}
+/** Serialize an ActivitySnapshot record to Turtle. */
+export function serializeActivitySnapshot(activity) {
+    return serialize(activity);
+}
+/** Serialize a SleepSnapshot record to Turtle. */
+export function serializeSleepSnapshot(sleep) {
+    return serialize(sleep);
+}
+//# sourceMappingURL=turtle-serializer.js.map