sunstone-data-platform 1.0.0__py3-none-any.whl

sunstone_data/graph/dataset.py

@@ -0,0 +1,438 @@
+"""The dataset graph: canonical RDF serialization, and the `Metadata` mapping.
+
+The serializer is the only place that turns a set of triples into bytes.
+Two rules make the output byte-for-byte reproducible:
+
+- Triples are deduplicated into a set and the output lines are sorted, so
+  the byte order never depends on the order a graph was built in.
+- Nested or anonymous structure gets a deterministic fragment IRI
+  (`fragment_iri`) instead of a blank node.
+
+The second half of the module maps a `sunstone.Metadata` object plus this
+package's version and snapshot facts to and from that graph, following the
+shape in spec 180 §6. See `DatasetDescription` for what the mapping carries.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import Iterable, Sequence
+
+from sunstone.lineage import Metadata
+
+from sunstone_data.graph import terms
+
+
+@dataclass(frozen=True)
+class IRI:
+    """A named node: an RDF term identified by an IRI."""
+
+    value: str
+
+    def to_ntriples(self) -> str:
+        """Render as an N-Triples IRIREF, e.g. ``<https://example.org/x>``."""
+        return f"<{self.value}>"
+
+
+_ESCAPES = {
+    "\\": "\\\\",
+    '"': '\\"',
+    "\n": "\\n",
+    "\r": "\\r",
+    "\t": "\\t",
+}
+
+
+@dataclass(frozen=True)
+class Literal:
+    """A literal term: a plain, language-tagged, or typed value."""
+
+    value: str
+    datatype: str | None = None
+    language: str | None = None
+
+    def to_ntriples(self) -> str:
+        """Render as an N-Triples literal, with the required escaping."""
+        escaped = "".join(_ESCAPES.get(c, c) for c in self.value)
+        if self.language is not None:
+            return f'"{escaped}"@{self.language}'
+        if self.datatype is not None:
+            return f'"{escaped}"^^<{self.datatype}>'
+        return f'"{escaped}"'
+
+
+Term = IRI | Literal
+
+
+@dataclass(frozen=True)
+class Triple:
+    """One RDF triple. The subject is always an IRI: this module never emits
+    a blank-node subject."""
+
+    subject: IRI
+    predicate: IRI
+    obj: Term
+
+    def to_ntriples(self) -> str:
+        """Render as one N-Triples statement line, without the trailing newline."""
+        return f"{self.subject.to_ntriples()} {self.predicate.to_ntriples()} {self.obj.to_ntriples()} ."
+
+
+Graph = frozenset[Triple]
+
+
+def build_graph(triples: Iterable[Triple]) -> Graph:
+    """Build a graph from triples in any order.
+
+    An RDF graph is a set, so duplicates collapse; `serialize` sorts its
+    output, so insertion order never reaches the caller.
+    """
+    return frozenset(triples)
+
+
+def serialize(graph: Graph) -> bytes:
+    """Serialize a graph to canonical N-Triples (UTF-8, one sorted line per triple)."""
+    lines = sorted(t.to_ntriples() for t in graph)
+    if not lines:
+        return b""
+    return ("\n".join(lines) + "\n").encode("utf-8")
+
+
+_UNESCAPES = {"\\": "\\", '"': '"', "'": "'", "n": "\n", "r": "\r", "t": "\t", "b": "\b", "f": "\f"}
+
+_TRIPLE_RE = re.compile(
+    r"""^<(?P<subject>[^>]*)>\s+<(?P<predicate>[^>]*)>\s+(?:"""
+    r"""<(?P<iri>[^>]*)>"""
+    r"""|"(?P<literal>(?:[^"\\]|\\.)*)"(?:\^\^<(?P<datatype>[^>]*)>|@(?P<language>[A-Za-z0-9-]+))?"""
+    r""")\s*\.$"""
+)
+
+
+def _unescape(text: str) -> str:
+    """Undo N-Triples string escaping (the inverse of ``_ESCAPES``, plus ``\\uXXXX``)."""
+    out: list[str] = []
+    i = 0
+    while i < len(text):
+        if text[i] != "\\":
+            out.append(text[i])
+            i += 1
+            continue
+        code = text[i + 1]
+        if code in ("u", "U"):
+            width = 4 if code == "u" else 8
+            out.append(chr(int(text[i + 2 : i + 2 + width], 16)))
+            i += 2 + width
+        else:
+            out.append(_UNESCAPES.get(code, code))
+            i += 2
+    return "".join(out)
+
+
+def parse_ntriples(text: str) -> Graph:
+    """Parse N-Triples text into a graph — the inverse of `serialize`.
+
+    Handles the subset the RDF 1.1 N-Triples grammar allows for graphs this
+    package writes and graph-server returns: IRI subjects and predicates, an
+    IRI or (plain, typed, or language-tagged) literal object, one statement
+    per line. Blank nodes are not supported — graph-server skolemizes them
+    into IRIs before storing, so they never come back over the wire.
+
+    Raises:
+        ValueError: A non-empty, non-comment line does not match the grammar.
+    """
+    triples: list[Triple] = []
+    for raw in text.splitlines():
+        line = raw.strip()
+        if not line or line.startswith("#"):
+            continue
+        match = _TRIPLE_RE.match(line)
+        if match is None:
+            raise ValueError(f"not a supported N-Triples statement: {line!r}")
+        parts = match.groupdict()
+        if parts["iri"] is not None:
+            obj: Term = IRI(parts["iri"])
+        else:
+            obj = Literal(
+                _unescape(parts["literal"]),
+                datatype=parts["datatype"],
+                language=parts["language"],
+            )
+        triples.append(Triple(IRI(parts["subject"]), IRI(parts["predicate"]), obj))
+    return build_graph(triples)
+
+
+def fragment_iri(base_iri: str, fragment: str) -> str:
+    """Mint a deterministic child IRI under `base_iri`, e.g. ``{base}#{fragment}``.
+
+    Use this instead of a blank node for nested or anonymous structure.
+    graph-server skolemizes blank nodes from a hash of the raw request
+    bytes (`crates/graph-core/src/canon.rs`), so the same graph submitted
+    with its triples in a different order hashes differently and mints a
+    new blank-node IRI — tombstoning the old node on every publish. A
+    fragment IRI built from stable inputs (the parent IRI plus a role or
+    id) does not depend on request bytes, so it stays the same across
+    publishes.
+    """
+    return f"{base_iri}#{fragment}"
+
+
+RDF_TYPE = IRI("http://www.w3.org/1999/02/22-rdf-syntax-ns#type")
+
+_DCT_IDENTIFIER = IRI(terms.DCT + "identifier")
+_DCT_TITLE = IRI(terms.DCT + "title")
+_DCT_DESCRIPTION = IRI(terms.DCT + "description")
+_DCAT_DATASET = IRI(terms.DCAT + "Dataset")
+_DCAT_HAS_VERSION = IRI(terms.DCAT + "hasVersion")
+_DCAT_HAS_CURRENT_VERSION = IRI(terms.DCAT + "hasCurrentVersion")
+_DCAT_VERSION = IRI(terms.DCAT + "version")
+_DCAT_PREVIOUS_VERSION = IRI(terms.DCAT + "previousVersion")
+_SI_SNAPSHOT = IRI(terms.DCAT_SI + "Snapshot")
+_SI_HAS_SNAPSHOT = IRI(terms.DCAT_SI + "hasSnapshot")
+_SI_SNAPSHOT_ID = IRI(terms.DCAT_SI + "snapshotId")
+_SI_METADATA_LOCATION = IRI(terms.DCAT_SI + "metadataLocation")
+_PROV_GENERATION = IRI(terms.PROV + "Generation")
+_PROV_WAS_GENERATED_BY = IRI(terms.PROV + "wasGeneratedBy")
+_PROV_QUALIFIED_GENERATION = IRI(terms.PROV + "qualifiedGeneration")
+_PROV_ACTIVITY = IRI(terms.PROV + "activity")
+_PROV_AT_TIME = IRI(terms.PROV + "atTime")
+_XSD_DATETIME = terms.XSD + "dateTime"
+
+
+@dataclass(frozen=True)
+class DatasetVersion:
+    """One named version of a dataset and the Iceberg snapshot it pins.
+
+    `sunstone.Metadata` has no notion of versions or snapshots — those are
+    this package's own facts, taken from Iceberg table history and from an
+    `ImportMetadata` record (`activity_id`, `timestamp_end`). This carries
+    them alongside the `Metadata` object instead of inventing fields on it.
+
+    Every field but `version` is optional, so a first publish with no
+    snapshot yet still produces a valid version node.
+    """
+
+    version: str
+    """The version label, e.g. ``v1.0``. Also the node's IRI fragment."""
+
+    previous_version: str | None = None
+    """Label of the version this one revises, if any."""
+
+    snapshot_id: str | None = None
+    """Iceberg snapshot id this version pins."""
+
+    metadata_location: str | None = None
+    """Location of the Iceberg metadata file for that snapshot."""
+
+    import_activity_id: str | None = None
+    """UUID of the import that produced the snapshot. Carried only when
+    `snapshot_id` is set, because the link hangs off the snapshot node."""
+
+    generated_at: str | None = None
+    """ISO 8601 instant the snapshot was generated. Carried only when both
+    `snapshot_id` and `import_activity_id` are set."""
+
+
+@dataclass(frozen=True)
+class DatasetDescription:
+    """Everything the graph mapping carries about one dataset.
+
+    Carried from `Metadata`: `slug` (``dct:identifier``), `name`
+    (``dct:title``) and `description` (``dct:description``) — the same term
+    choices `Metadata.to_jsonld()` already makes.
+
+    Deliberately not carried: `lineage`, `field_metadata`,
+    `component_metadata`, `custom_properties` and `rdf_prefixes`. Import
+    provenance as RDF and the CSVW schema projection are separate tasks;
+    round-tripping a description leaves those fields at their defaults.
+    """
+
+    dataset_iri: str
+    """IRI of the dataset the graph is rooted at."""
+
+    metadata: Metadata = field(default_factory=Metadata)
+    """The descriptive metadata."""
+
+    versions: tuple[DatasetVersion, ...] = ()
+    """Named versions, ordered by version label."""
+
+    current_version: str | None = None
+    """Label of the version ``dcat:hasCurrentVersion`` points at."""
+
+
+def description_to_graph(description: DatasetDescription) -> Graph:
+    """Build the dataset graph for a description (spec 180 §6).
+
+    Only the DCAT versioning terms are asserted. `dcat:hasVersion` and
+    `dcat:previousVersion` are sub-properties of `prov:generalizationOf`
+    and `prov:wasRevisionOf`, so asserting the PROV forms too would store
+    an entailed triple, which ADR 0002 §1 forbids. `prov:wasGeneratedBy`
+    and the qualified `prov:Generation` node are not entailed by anything,
+    so they are asserted.
+    """
+    root = IRI(description.dataset_iri)
+    triples: list[Triple] = []
+
+    metadata = description.metadata
+    for predicate, value in (
+        (_DCT_IDENTIFIER, metadata.slug),
+        (_DCT_TITLE, metadata.name),
+        (_DCT_DESCRIPTION, metadata.description),
+    ):
+        if value is not None:
+            triples.append(Triple(root, predicate, Literal(value)))
+
+    for version in description.versions:
+        triples.extend(_version_triples(description.dataset_iri, root, version))
+
+    if description.current_version is not None:
+        current = IRI(fragment_iri(description.dataset_iri, description.current_version))
+        triples.append(Triple(root, _DCAT_HAS_CURRENT_VERSION, current))
+
+    return build_graph(triples)
+
+
+def _version_triples(dataset_iri: str, root: IRI, version: DatasetVersion) -> list[Triple]:
+    node = IRI(fragment_iri(dataset_iri, version.version))
+    triples = [
+        Triple(root, _DCAT_HAS_VERSION, node),
+        Triple(node, RDF_TYPE, _DCAT_DATASET),
+        Triple(node, _DCAT_VERSION, Literal(version.version)),
+    ]
+    if version.previous_version is not None:
+        previous = IRI(fragment_iri(dataset_iri, version.previous_version))
+        triples.append(Triple(node, _DCAT_PREVIOUS_VERSION, previous))
+    if version.snapshot_id is None:
+        return triples
+
+    # `snapshot-{id}`, never a bare `snapshot`: the catalog rewrites the bare
+    # `#snapshot` node on every table commit, so a version pin named that way
+    # would not survive the next commit (spec 180 §10).
+    snapshot = IRI(fragment_iri(dataset_iri, f"snapshot-{version.snapshot_id}"))
+    triples += [
+        Triple(node, _SI_HAS_SNAPSHOT, snapshot),
+        Triple(snapshot, RDF_TYPE, _SI_SNAPSHOT),
+        Triple(snapshot, _SI_SNAPSHOT_ID, Literal(version.snapshot_id)),
+    ]
+    if version.metadata_location is not None:
+        triples.append(Triple(snapshot, _SI_METADATA_LOCATION, Literal(version.metadata_location)))
+    if version.import_activity_id is None:
+        return triples
+
+    activity = IRI(fragment_iri(dataset_iri, f"import-{version.import_activity_id}"))
+    triples.append(Triple(snapshot, _PROV_WAS_GENERATED_BY, activity))
+    if version.generated_at is not None:
+        generation = IRI(fragment_iri(dataset_iri, f"gen-{version.snapshot_id}"))
+        triples += [
+            Triple(snapshot, _PROV_QUALIFIED_GENERATION, generation),
+            Triple(generation, RDF_TYPE, _PROV_GENERATION),
+            Triple(generation, _PROV_ACTIVITY, activity),
+            Triple(generation, _PROV_AT_TIME, Literal(version.generated_at, datatype=_XSD_DATETIME)),
+        ]
+    return triples
+
+
+def snapshot_generation_triples(
+    dataset_iri: str,
+    snapshot_id: str,
+    import_activity_id: str,
+    generated_at: str,
+    metadata_location: str | None = None,
+) -> list[Triple]:
+    """Link an Iceberg snapshot to the import activity that produced it (spec 180 §9 step 4).
+
+    Emits the ``#snapshot-{id}`` node — never the bare ``#snapshot``, which
+    the catalog rewrites on every commit (spec §10) — with its type and
+    ``dcat-si:snapshotId``, plus ``prov:wasGeneratedBy`` and a qualified
+    ``prov:Generation`` node carrying the generation instant. No
+    ``dcat:hasVersion`` wrapper: an import does not mint a named version
+    label (``sunstone data publish --version`` does that separately,
+    spec §8) — contrast with ``_version_triples``, which does add that
+    wrapper for the publish path.
+    """
+    snapshot = IRI(fragment_iri(dataset_iri, f"snapshot-{snapshot_id}"))
+    activity = IRI(fragment_iri(dataset_iri, f"import-{import_activity_id}"))
+    generation = IRI(fragment_iri(dataset_iri, f"gen-{snapshot_id}"))
+    triples = [
+        Triple(snapshot, RDF_TYPE, _SI_SNAPSHOT),
+        Triple(snapshot, _SI_SNAPSHOT_ID, Literal(snapshot_id)),
+        Triple(snapshot, _PROV_WAS_GENERATED_BY, activity),
+        Triple(snapshot, _PROV_QUALIFIED_GENERATION, generation),
+        Triple(generation, RDF_TYPE, _PROV_GENERATION),
+        Triple(generation, _PROV_ACTIVITY, activity),
+        Triple(generation, _PROV_AT_TIME, Literal(generated_at, datatype=_XSD_DATETIME)),
+    ]
+    if metadata_location is not None:
+        triples.append(Triple(snapshot, _SI_METADATA_LOCATION, Literal(metadata_location)))
+    return triples
+
+
+def snapshot_already_has_generation(graph: Graph, dataset_iri: str, snapshot_id: str) -> bool:
+    """True if ``#snapshot-{snapshot_id}`` already has a ``prov:wasGeneratedBy`` link.
+
+    A cheap idempotence check: a retried import whose Iceberg write
+    short-circuited (identical checksum) should not re-assert provenance if
+    the snapshot it points at is already linked to an activity — only when a
+    prior crash left it orphaned (spec 180 §9; DP-27).
+    """
+    snapshot = IRI(fragment_iri(dataset_iri, f"snapshot-{snapshot_id}"))
+    return any(t.subject == snapshot and t.predicate == _PROV_WAS_GENERATED_BY for t in graph)
+
+
+def graph_to_description(graph: Graph, dataset_iri: str) -> DatasetDescription:
+    """Read a dataset graph back into a `DatasetDescription`.
+
+    The inverse of `description_to_graph` for every field that mapping
+    emits. A graph is a set, so version order is not carried: versions come
+    back sorted by label. Triples the mapping does not claim are ignored.
+    """
+    root = IRI(dataset_iri)
+    metadata = Metadata(
+        slug=_literal(graph, root, _DCT_IDENTIFIER),
+        name=_literal(graph, root, _DCT_TITLE),
+        description=_literal(graph, root, _DCT_DESCRIPTION),
+    )
+    versions = tuple(
+        sorted(
+            (_read_version(graph, dataset_iri, node) for node in _iris(graph, root, _DCAT_HAS_VERSION)),
+            key=lambda v: v.version,
+        )
+    )
+    current = next(iter(_iris(graph, root, _DCAT_HAS_CURRENT_VERSION)), None)
+    return DatasetDescription(
+        dataset_iri=dataset_iri,
+        metadata=metadata,
+        versions=versions,
+        current_version=_fragment(current.value, dataset_iri) if current else None,
+    )
+
+
+def _read_version(graph: Graph, dataset_iri: str, node: IRI) -> DatasetVersion:
+    previous = next(iter(_iris(graph, node, _DCAT_PREVIOUS_VERSION)), None)
+    snapshot = next(iter(_iris(graph, node, _SI_HAS_SNAPSHOT)), None)
+    generation = next(iter(_iris(graph, snapshot, _PROV_QUALIFIED_GENERATION)), None) if snapshot else None
+    activity = next(iter(_iris(graph, snapshot, _PROV_WAS_GENERATED_BY)), None) if snapshot else None
+    return DatasetVersion(
+        version=_literal(graph, node, _DCAT_VERSION) or _fragment(node.value, dataset_iri),
+        previous_version=_fragment(previous.value, dataset_iri) if previous else None,
+        snapshot_id=_literal(graph, snapshot, _SI_SNAPSHOT_ID) if snapshot else None,
+        metadata_location=(_literal(graph, snapshot, _SI_METADATA_LOCATION) if snapshot else None),
+        import_activity_id=(_fragment(activity.value, dataset_iri).removeprefix("import-") if activity else None),
+        generated_at=_literal(graph, generation, _PROV_AT_TIME) if generation else None,
+    )
+
+
+def _matches(graph: Graph, subject: IRI, predicate: IRI) -> Iterable[Term]:
+    return (t.obj for t in graph if t.subject == subject and t.predicate == predicate)
+
+
+def _literal(graph: Graph, subject: IRI, predicate: IRI) -> str | None:
+    return next((o.value for o in _matches(graph, subject, predicate) if isinstance(o, Literal)), None)
+
+
+def _iris(graph: Graph, subject: IRI, predicate: IRI) -> Sequence[IRI]:
+    return [o for o in _matches(graph, subject, predicate) if isinstance(o, IRI)]
+
+
+def _fragment(iri: str, dataset_iri: str) -> str:
+    return iri.removeprefix(f"{dataset_iri}#")

sunstone_data/graph/terms.py

@@ -0,0 +1,34 @@
+"""Namespace IRIs for the RDF vocabularies this project uses.
+
+These constants must match `PREFIXES` in
+`crates/iceberg-catalog/src/descriptor.rs` byte for byte. Both sides read
+and write the same graph; a mismatched namespace IRI would silently break
+CURIE reflection between RDF predicates and Iceberg property keys
+(`sunstone.{prefix}.{local}`, spec §10.1) instead of failing loudly.
+"""
+
+DCAT = "http://www.w3.org/ns/dcat#"
+DCT = "http://purl.org/dc/terms/"
+FOAF = "http://xmlns.com/foaf/0.1/"
+PROV = "http://www.w3.org/ns/prov#"
+VCARD = "http://www.w3.org/2006/vcard/ns#"
+XSD = "http://www.w3.org/2001/XMLSchema#"
+DCAT_SI = "https://sunstone.institute/rdf/data#"
+ORG = "http://www.w3.org/ns/org#"
+SKOS = "http://www.w3.org/2004/02/skos/core#"
+RDFS = "http://www.w3.org/2000/01/rdf-schema#"
+CSVW = "http://www.w3.org/ns/csvw#"
+
+PREFIXES: dict[str, str] = {
+    "dcat": DCAT,
+    "dct": DCT,
+    "foaf": FOAF,
+    "prov": PROV,
+    "vcard": VCARD,
+    "xsd": XSD,
+    "dcat-si": DCAT_SI,
+    "org": ORG,
+    "skos": SKOS,
+    "rdfs": RDFS,
+    "csvw": CSVW,
+}

sunstone_data/identifiers.py

@@ -0,0 +1,155 @@
+"""Identifier validation and quoting for safe SQL construction.
+
+This module provides centralized validation and quoting for all identifiers
+(namespace, table, branch, tag names) that get interpolated into DuckDB SQL
+or used as catalog references. It prevents SQL injection by:
+
+1. Validating identifiers against a strict allowlist pattern.
+2. Quoting identifiers using DuckDB's double-quote escaping.
+3. Rejecting any input containing SQL metacharacters.
+
+Usage:
+    from sunstone_data.identifiers import validate_sql_identifier, quote_identifier
+
+    validate_sql_identifier(namespace, "namespace")
+    validate_sql_identifier(table, "table")
+    quoted = quote_identifier(branch)
+"""
+
+from __future__ import annotations
+
+import re
+
+# SQL identifiers: letters, digits, underscores. Must start with letter or underscore.
+# Max 128 characters.
+_SQL_IDENTIFIER_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]{0,127}$")
+
+# Branch and tag names may include hyphens (e.g., feature-branch, v1.0-rc1).
+# Also allows dots for version-style tags (v1.0, 1.0.0).
+_REF_NAME_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_\-.]{0,127}$")
+
+# Characters that must never appear in any identifier
+_DANGEROUS_CHARS = re.compile(r"[;'\"\\`\s/\x00]|--|/\*|\*/")
+
+
+def validate_sql_identifier(value: str, label: str) -> str:
+    """Validate a value as a safe SQL identifier (namespace or table name).
+
+    Args:
+        value: The identifier string to validate.
+        label: Human-readable label for error messages (e.g., "namespace", "table").
+
+    Returns:
+        The validated identifier string (unchanged).
+
+    Raises:
+        ValueError: If the identifier is empty, too long, or contains unsafe characters.
+    """
+    if not value:
+        raise ValueError(f"Empty {label} name is not allowed.")
+
+    if _DANGEROUS_CHARS.search(value):
+        raise ValueError(
+            f"Invalid {label} name: {value!r}. "
+            f"Contains disallowed characters (semicolons, quotes, whitespace, "
+            f"comments, or slashes are not permitted)."
+        )
+
+    if not _SQL_IDENTIFIER_RE.match(value):
+        raise ValueError(
+            f"Invalid {label} name: {value!r}. "
+            f"Must start with a letter or underscore, contain only letters, "
+            f"digits, and underscores, and be at most 128 characters."
+        )
+
+    return value
+
+
+def _reject_dangerous_chars(value: str, label: str) -> None:
+    """Raise if value is empty or contains characters unsafe for SQL interpolation."""
+    if not value:
+        raise ValueError(f"Empty {label} name is not allowed.")
+
+    if _DANGEROUS_CHARS.search(value):
+        raise ValueError(
+            f"Invalid {label} name: {value!r}. "
+            f"Contains disallowed characters (semicolons, quotes, whitespace, "
+            f"comments, or slashes are not permitted)."
+        )
+
+
+def validate_ref_name(value: str, label: str = "ref") -> str:
+    """Validate a branch or tag name.
+
+    Branch and tag names follow a slightly more permissive pattern than SQL
+    identifiers, allowing hyphens and dots (e.g., feature-branch, v1.0).
+
+    Args:
+        value: The branch or tag name to validate.
+        label: Human-readable label for error messages.
+
+    Returns:
+        The validated name (unchanged).
+
+    Raises:
+        ValueError: If the name is empty or contains unsafe characters.
+    """
+    _reject_dangerous_chars(value, label)
+
+    if not _REF_NAME_RE.match(value):
+        raise ValueError(
+            f"Invalid {label} name: {value!r}. "
+            f"Must start with a letter or underscore, contain only letters, "
+            f"digits, underscores, hyphens, and dots, and be at most 128 characters."
+        )
+
+    return value
+
+
+def validate_ref_string(value: str, label: str = "ref") -> str:
+    """Validate an arbitrary, unclassified version ref (branch, tag, snapshot id, or timestamp).
+
+    Unlike `validate_ref_name`, this does not constrain the ref's format — a
+    ref can be a snapshot id or timestamp, which legitimately starts with a
+    digit and would fail `validate_ref_name`'s branch/tag naming pattern.
+    It only rejects characters that are unsafe for SQL interpolation.
+
+    Args:
+        value: The ref string to validate.
+        label: Human-readable label for error messages.
+
+    Returns:
+        The validated ref string (unchanged).
+
+    Raises:
+        ValueError: If the ref is empty or contains unsafe characters.
+    """
+    _reject_dangerous_chars(value, label)
+    return value
+
+
+def quote_identifier(name: str) -> str:
+    """Quote a validated identifier for safe use in DuckDB SQL.
+
+    Escapes internal double quotes by doubling them and wraps the identifier
+    in double quotes. The identifier should already be validated before calling
+    this function, but this provides defense-in-depth.
+
+    Args:
+        name: The identifier to quote.
+
+    Returns:
+        Double-quoted identifier safe for SQL interpolation.
+
+    Raises:
+        ValueError: If the name is empty or contains null bytes.
+    """
+    if not name:
+        raise ValueError("Cannot quote an empty identifier.")
+
+    if "\x00" in name:
+        raise ValueError("Identifier contains null bytes.")
+
+    # Escape any internal double quotes by doubling them
+    escaped = name.replace('"', '""')
+    return f'"{escaped}"'

sunstone_data/import_/__init__.py

@@ -0,0 +1,28 @@
+"""Import pipeline for Sunstone Data Platform."""
+
+from sunstone_data.import_.fetcher import FileType, SourceInfo, fetch_source
+from sunstone_data.import_.parser import (
+    parse_and_create_tables,
+    parse_csv,
+    parse_excel,
+)
+from sunstone_data.import_.pipeline import ImportResult, run_import
+from sunstone_data.import_.storage import (
+    file_exists_by_checksum,
+    get_original,
+    store_original,
+)
+
+__all__ = [
+    "FileType",
+    "ImportResult",
+    "SourceInfo",
+    "fetch_source",
+    "file_exists_by_checksum",
+    "get_original",
+    "parse_and_create_tables",
+    "parse_csv",
+    "parse_excel",
+    "run_import",
+    "store_original",
+]