         (throw (Exception. (str "Incompatible header detected (expected: " CompatVersion " got: " compat ")")))))
     (throw (Exception. (str "Failed to read archive header")))))
 
+;;--------------------------------------------------------------------------------------
+;; import-archive - imports an Archive object from the input stream
+;;--------------------------------------------------------------------------------------
 (defn import-archive [is]
   (read-archive is)) ;; FIXME - check digitial signature
 
+;;--------------------------------------------------------------------------------------
+;; import-entry - validates an entry object
+;;
+;; returns the proper input-stream-factory when sucessful, or throws an exception otherwise
+;;--------------------------------------------------------------------------------------
 (defn import-entry [compression entry]
   (let [type (:description compression)
         factory #(make-input-stream type entry)]

            [pandect.algo.sha1 :refer :all])
  (:refer-clojure :exclude [read]))

(defn read-protobuf [t is] (->> is (fl/protobuf-seq t) first))

(defn read-header [is] (read-protobuf Header is))
(defn read-archive [is] (read-protobuf Archive is))

(defn make-input-stream [type entry]
  (let [is (->> entry :data .newInput)]
    (codecs/decompressor type is)))

(defn import-header [is]
  (if-let [header (read-header is)]
    (let [compat (select-keys header [:magic :version])]

    ;; and inject our stream factory
    {:entry entry :input-stream-factory factory}))

;;--------------------------------------------------------------------------------------
;; import-payload - imports a Payload object from Archive::Payload field
;;
;; We separate Archive from Payload to delineate signature boundaries.  Everything within
;; Payload is expected to be optionally digitally signed (and thus verified upon import)
;;--------------------------------------------------------------------------------------
(defn import-payload [archive] (->> archive :payload .newInput (fl/protobuf-load-stream Payload)))

;;--------------------------------------------------------------------------------------
;; synth-index - synthesize an index of entries, keyed by :path
;;
;; Takes a payload object and constructs a map of entries, keyed by their path.  Each
;; entry is fully verified and processed (such as attaching an input-stream filter)
;;--------------------------------------------------------------------------------------
(defn synth-index [payload]
  (let [compression (:compression payload)]
    (->> (:entries payload) (map #(vector (:path %) (import-entry compression %))) (into {}))))

;;--------------------------------------------------------------------------------------
;; entry-stream - instantiate an input-stream from the factory
;;
;; This allows a caller to obtain a simple input-stream interface to our entries where
;; all the details such as compression are already factored in.  Therefore, this stream
;; is suitable to any number of tasks such as interpreting results, verifying contents,
;; or writing data to files
;;--------------------------------------------------------------------------------------
(defn entry-stream [entry]
  (let [factory (:input-stream-factory entry)]
    (factory)))
