capsium 0.3.0 → 0.6.0

data/lib/capsium/package/composition.rb

@@ -3,28 +3,44 @@
 module Capsium
   class Package
     # Composite-package support (ARCHITECTURE.md section 4a), mixed into
-    # Package: metadata.dependencies resolution against a package store
-    # and load-time validation of dependency resource references.
+    # Package: metadata.dependencies resolution — bundled dependencies
+    # (Capsium::Package::Bundle) first, then the package store — and
+    # load-time validation of dependency resource references.
     module Composition
       private
 
-      # Resolves metadata.dependencies against the package store (the
-      # `store` argument, else CAPSIUM_STORE). Each resolved dependency
-      # loads recursively with an extended circularity chain; its
-      # exported content becomes lower read-only layers of this
-      # package's merged view.
-      def resolve_dependencies(store, chain)
+      # Resolves metadata.dependencies: bundled dependencies first
+      # (Capsium::Package::Bundle — encapsulated packages embed their
+      # dependencies under packages/, so they activate with no store or
+      # registry), then the store (the `store` argument, else
+      # CAPSIUM_STORE) with the given `registry` (else CAPSIUM_REGISTRY)
+      # as install fallback for store misses. The store resolver is only
+      # constructed when a dependency is not bundled, so a fully
+      # bundled package needs neither. Each resolved dependency loads
+      # recursively with an extended circularity chain and this
+      # package's bundle underneath its own (re-declared transitive
+      # dependencies resolve from it); its exported content becomes
+      # lower read-only layers of this package's merged view.
+      def resolve_dependencies(store, registry, chain, bundle = nil)
         declared = @metadata.dependencies
         return [] if declared.empty?
 
-        resolver = DependencyResolver.new(store || Store.default)
         chain += [@metadata.guid]
+        bundle = Bundle.new(@path).merged_with(bundle)
+        resolver = nil
         declared.map do |guid, range|
-          cap_path = resolver.resolve_path(guid, range, chain: chain)
+          cap_path = bundle.resolve_path(guid, range, chain: chain)
+          if cap_path.nil?
+            resolver ||= DependencyResolver.new(store || Store.default, registry: registry)
+            cap_path = resolver.resolve_path(guid, range, chain: chain)
+          end
           ResolvedDependency.new(
             guid: guid, range: range, path: cap_path,
-            package: Package.new(cap_path, store: resolver.store,
-                                           dependency_chain: chain)
+            package: Package.new(cap_path,
+                                 store: resolver ? resolver.store : store,
+                                 registry: resolver ? resolver.registry : registry,
+                                 dependency_chain: chain,
+                                 bundle: bundle)
           )
         end
       end

data/lib/capsium/package/dataset.rb

@@ -67,6 +67,26 @@ module Capsium
         problems
       end
 
+      # The parsed JSON schema for this dataset, or nil when none is
+      # declared or the file is unreadable.
+      def json_schema
+        return nil unless @config.schema_file && @config.schema_type == "json-schema"
+        return nil unless File.file?(schema_path)
+
+        load_schema
+      end
+
+      # Schema validation of an arbitrary candidate document (used by
+      # the reactor's writable overlay before persisting a mutation):
+      # human-readable schema problems, empty when valid or when the
+      # dataset has no JSON schema.
+      def schema_errors_for(data)
+        return [] unless @config.schema_file && @config.schema_type == "json-schema"
+        return [] unless File.file?(schema_path)
+
+        JSON::Validator.fully_validate(load_schema, JSON.parse(JSON.generate(data)))
+      end
+
       private
 
       def schema_validation_errors

data/lib/capsium/package/dependency_resolver.rb

@@ -28,12 +28,14 @@ module Capsium
     end
 
     # Orchestrates metadata.dependencies resolution against a package
-    # store: circularity checks plus store lookup. Package loads the
-    # resolved .cap itself (recursively, with an extended chain).
+    # store: circularity checks plus store lookup, with a registry
+    # (Capsium::Registry) as install fallback for store misses.
+    # Package loads the resolved .cap itself (recursively, with an
+    # extended chain).
     class DependencyResolver
-      attr_reader :store
+      attr_reader :store, :registry
 
-      def initialize(store)
+      def initialize(store, registry: nil)
         if store.nil?
           raise DependencyError,
                 "metadata.dependencies declared but no package store " \
@@ -41,13 +43,21 @@ module Capsium
         end
 
         @store = store.is_a?(Store) ? store : Store.new(store.to_s)
+        @registry = if registry.nil? || registry.is_a?(Capsium::Registry)
+                      registry
+                    else
+                      Capsium::Registry.fetch(registry)
+                    end
+        @registry ||= Capsium::Registry.default
       end
 
-      # The newest store .cap satisfying the dependency. Raises
-      # CircularDependencyError when the GUID is already being resolved
-      # up-chain, DependencyNotFoundError when the store has no package
-      # for it and UnsatisfiableDependencyError when no stored version
-      # satisfies the range.
+      # The newest store .cap satisfying the dependency. Falls back to
+      # installing from the configured registry when the store has no
+      # package for the GUID. Raises CircularDependencyError when the
+      # GUID is already being resolved up-chain,
+      # DependencyNotFoundError when neither the store nor a registry
+      # provides it and UnsatisfiableDependencyError when no available
+      # version satisfies the range.
       def resolve_path(guid, range, chain:)
         if chain.include?(guid)
           raise CircularDependencyError,
@@ -55,6 +65,26 @@ module Capsium
         end
 
         @store.find(guid, range)
+      rescue DependencyNotFoundError => e
+        resolve_from_registry(guid, range, e)
+      end
+
+      private
+
+      # Registry fallback for store misses (fallback chain: store ->
+      # registry -> typed error). Installs the newest satisfying version
+      # into the store and returns its path; re-raises the store error
+      # when no registry is configured.
+      def resolve_from_registry(guid, range, store_error)
+        raise store_error if @registry.nil?
+
+        @registry.install(guid, range, store: @store)
+      rescue Registry::PackageNotFoundError
+        raise DependencyNotFoundError,
+              "#{store_error.message}; no package #{guid} in registry " \
+              "#{@registry.location} either"
+      rescue Registry::UnsatisfiableConstraintError => e
+        raise UnsatisfiableDependencyError, e.message
       end
     end
   end

data/lib/capsium/package/encryption_config.rb

@@ -5,13 +5,16 @@ require "lutaml/model"
 module Capsium
   class Package
     # The "encryption" object of signature.json in an encrypted package
-    # (05x-packaging "Encryption"): the AES-256-GCM envelope with the
-    # RSA-OAEP-SHA256 wrapped data encryption key (DEK), all binary
-    # values Base64-encoded.
+    # (05x-packaging "Encryption"): the AES-256-GCM envelope, all binary
+    # values Base64-encoded. keyManagement selects how the data
+    # encryption key (DEK) is protected: "RSA-OAEP-SHA256" carries it in
+    # encryptedDek (RSA-wrapped); "OpenPGP" carries an armored OpenPGP
+    # message containing the DEK in message.
     class EncryptionEnvelope < Lutaml::Model::Serializable
       attribute :algorithm, :string
       attribute :key_management, :string
       attribute :encrypted_dek, :string
+      attribute :message, :string
       attribute :iv, :string
       attribute :auth_tag, :string
 
@@ -19,6 +22,7 @@ module Capsium
         map :algorithm, to: :algorithm
         map "keyManagement", to: :key_management
         map "encryptedDek", to: :encrypted_dek
+        map :message, to: :message
         map :iv, to: :iv
         map "authTag", to: :auth_tag
       end

data/lib/capsium/package/manifest.rb

@@ -71,7 +71,7 @@ module Capsium
       private
 
       def content_files
-        Dir.glob(File.join(@content_path, "**", "*")).select do |file|
+        Dir.glob(File.join(@content_path, "**", "*"), File::FNM_DOTMATCH).select do |file|
           File.file?(file)
         end
       end

data/lib/capsium/package/merged_view.rb

@@ -26,6 +26,8 @@ module Capsium
     # With `exported_only: true` (the view a dependent package gets):
     # layers whose visibility is "private" are hidden entirely, and a path
     # resolves only when the manifest lists the resource as "exported".
+    # `extra_layers` stack on top of ALL own layers (e.g. the reactor's
+    # writable overlay, section 5a).
     class MergedView
       # A single read layer: an absolute root directory mirroring the
       # content/ tree, plus its parsed tombstone set.
@@ -45,13 +47,13 @@ module Capsium
       attr_reader :package_path, :layers, :dependency_views
 
       def initialize(package_path, storage:, manifest:, dependency_views: [],
-                     exported_only: false)
+                     exported_only: false, extra_layers: [])
         @package_path = package_path
         @storage = storage
         @manifest = manifest
         @exported_only = exported_only
         @dependency_views = dependency_views
-        @layers = build_layers
+        @layers = build_layers + extra_layers
       end
 
       # The absolute filesystem path serving a resource reference: a

data/lib/capsium/package/metadata.rb

@@ -11,7 +11,7 @@ module Capsium
 
       def_delegators :@config, :to_json, :to_hash, :name, :version,
                      :description, :guid, :uuid, :author, :license,
-                     :repository, :dependencies
+                     :repository, :dependencies, :read_only
 
       def initialize(path)
         @path = path

data/lib/capsium/package/metadata_config.rb

@@ -36,6 +36,7 @@ module Capsium
       attribute :repository, Repository
       attribute :dependencies, :hash, default: {}
       attribute :read_only, :boolean
+      attribute :modules, :string, collection: true
 
       json do
         map :name, to: :name
@@ -48,6 +49,7 @@ module Capsium
         map :repository, to: :repository
         map :dependencies, to: :dependencies
         map "readOnly", to: :read_only
+        map :modules, to: :modules
       end
 
       def self.from_json(json)
@@ -88,7 +90,13 @@ module Capsium
         problems << "version must be semver" if invalid?(version, SEMVER_PATTERN)
         problems << "guid must be a URI" if guid && !uri?(guid)
         problems << "uuid is not a valid UUID" if invalid?(uuid, UUID_PATTERN)
-        problems
+        problems + module_errors
+      end
+
+      def module_errors
+        return [] if modules.nil? || modules.all? { |mod| mod.match?(KEBAB_CASE_PATTERN) }
+
+        ["modules must be kebab-case module identifiers"]
       end
 
       def invalid?(value, pattern)

data/lib/capsium/package/open_pgp.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Capsium
+  class Package
+    # OpenPGP support (signatures per ARCHITECTURE.md section 6a and
+    # encryption per section 6b) through the rnp gem's binding to
+    # librnp.
+    #
+    # rnp is a soft dependency: it is only required when an OpenPGP
+    # feature is actually used, and this module is the single place that
+    # loads it. When the rnp gem or the librnp shared library cannot be
+    # loaded, the entry points raise OpenPgpUnavailableError with
+    # installation guidance.
+    module OpenPgp
+      # The rnp gem or the librnp shared library is not available.
+      class OpenPgpUnavailableError < Capsium::Error; end
+
+      # A key file is unreadable or holds no suitable OpenPGP key.
+      class KeyError < Capsium::Error; end
+
+      UNAVAILABLE_MESSAGE =
+        "OpenPGP support requires librnp and the rnp gem " \
+        "(e.g. `brew install rnp` and `gem install rnp`)"
+
+      # One loaded key file: the Rnp context holding the key material
+      # and the selected key within it.
+      LoadedKey = Data.define(:rnp, :key)
+
+      # A fresh Rnp context. Raises OpenPgpUnavailableError when the rnp
+      # gem or librnp cannot be loaded.
+      def self.rnp
+        require "rnp"
+        Rnp.new
+      rescue LoadError
+        raise OpenPgpUnavailableError, UNAVAILABLE_MESSAGE
+      end
+
+      # Loads the OpenPGP key at key_path (armored or binary, public or
+      # secret — the format is auto-detected) into a fresh Rnp context.
+      # With secret: true the selected key must hold secret key material
+      # (signing, decryption); otherwise any loaded key is selected
+      # (verification, encryption). Raises KeyError when the file is
+      # unreadable or holds no suitable key.
+      def self.load_key(key_path, secret: false)
+        instance = rnp
+        instance.load_keys(input: Rnp::Input.from_string(File.binread(key_path)),
+                           format: "GPG")
+        key = select_key(instance, secret: secret)
+        return LoadedKey.new(rnp: instance, key: key) if key
+
+        raise KeyError, "no suitable #{secret ? 'secret' : 'public'} OpenPGP key in: #{key_path}"
+      rescue Errno::ENOENT, Rnp::Error
+        raise KeyError, "cannot load OpenPGP key: #{key_path}"
+      end
+
+      def self.select_key(instance, secret:)
+        keys = instance.keyids.map { |keyid| instance.find_key(keyid: keyid) }
+        return keys.find(&:secret_key_present?) if secret
+
+        keys.first
+      end
+      private_class_method :select_key
+    end
+  end
+end

data/lib/capsium/package/open_pgp_cipher.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "base64"
+
+module Capsium
+  class Package
+    # Encrypts and decrypts whole Capsium packages with OpenPGP key
+    # management (ARCHITECTURE.md section 6b) through librnp
+    # (Capsium::Package::OpenPgp). Parallel to the RSA-OAEP-SHA256
+    # Cipher — same encrypted .cap layout, same AES-256-GCM content
+    # encryption, same typed errors — with the DEK carried as an armored
+    # OpenPGP message instead of an RSA-wrapped blob:
+    #
+    #   {"encryption": {"algorithm": "AES-256-GCM",
+    #                   "keyManagement": "OpenPGP",
+    #                   "message": <armored OpenPGP message with the DEK>,
+    #                   "iv": <base64>, "authTag": <base64>}}
+    #
+    # Keys are OpenPGP key files (armored or binary, auto-detected):
+    # encryption needs the recipient's public key, decryption the
+    # secret key.
+    class OpenPgpCipher < Cipher
+      KEY_MANAGEMENT = "OpenPGP"
+
+      # The OpenPGP symmetric cipher protecting the DEK message.
+      CIPHER_NAME = "AES256"
+
+      private
+
+      # The encryption envelope carrying the DEK as an armored OpenPGP
+      # message to the recipient's public key.
+      def envelope_for(dek, gcm_iv, auth_tag, recipient)
+        message = recipient.rnp.encrypt(
+          input: Rnp::Input.from_string(dek),
+          recipients: recipient.key, cipher: CIPHER_NAME, armored: true
+        )
+        EncryptionConfig.new(
+          encryption: EncryptionEnvelope.new(
+            algorithm: ALGORITHM, key_management: KEY_MANAGEMENT,
+            message: message,
+            iv: Base64.strict_encode64(gcm_iv), auth_tag: Base64.strict_encode64(auth_tag)
+          )
+        )
+      end
+
+      # Recovers the DEK by decrypting the envelope's OpenPGP message.
+      # Reached only after the rnp binding loaded successfully (the
+      # secret key is loaded first), so the Rnp error constants are
+      # defined here.
+      def unwrap_dek(envelope, secret_key)
+        secret_key.rnp.decrypt(input: Rnp::Input.from_string(envelope.message.to_s))
+      rescue Rnp::Error
+        # No suitable key, or a malformed or tampered message.
+        raise DecryptionError, "decryption failed: wrong key or tampered package"
+      end
+
+      def load_public_key(public_key_path)
+        OpenPgp.load_key(public_key_path)
+      end
+
+      def load_private_key(private_key_path)
+        OpenPgp.load_key(private_key_path, secret: true)
+      end
+    end
+  end
+end

data/lib/capsium/package/open_pgp_signer.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+module Capsium
+  class Package
+    # Signs and verifies Capsium packages with OpenPGP detached
+    # signatures (ARCHITECTURE.md section 6a) through librnp
+    # (Capsium::Package::OpenPgp). Parallel to the RSA-SHA256/X.509
+    # Signer with the same construction semantics and the same error
+    # taxonomy (Signer::SignatureError subclasses), so loaders and the
+    # CLI handle both schemes uniformly.
+    #
+    # The signed payload is identical to the Signer's: the
+    # concatenation, in sorted package-relative path order, of the raw
+    # bytes of every file covered by the security.json integrity
+    # checksums. signature.sig holds the armored detached OpenPGP
+    # signature (SHA-256) over that payload; the signer's armored
+    # public key is embedded as signature.pub.asc and security.json
+    # records:
+    #
+    #   "digitalSignatures": { "certificateType": "OpenPGP",
+    #     "publicKey": "signature.pub.asc",
+    #     "signatureFile": "signature.sig" }
+    #
+    # Keys are OpenPGP key files (armored or binary, auto-detected);
+    # signing needs a secret key, verification a public one.
+    class OpenPgpSigner
+      ALGORITHM = "OpenPGP"
+      CERTIFICATE_TYPE = "OpenPGP"
+      HASH = "SHA256"
+
+      # Package-relative name of the embedded armored OpenPGP public key
+      # recorded in security.json digitalSignatures.publicKey.
+      PUBLIC_KEY_FILE = "signature.pub.asc"
+
+      attr_reader :package_path
+
+      def initialize(package_path)
+        @package_path = package_path
+      end
+
+      # Signs a package directory in place, or a .cap file (unpacked,
+      # signed, recompressed), with the OpenPGP secret key at
+      # secret_key_path. Returns the signed path.
+      def self.sign_package(path, secret_key_path)
+        return new(path).sign(secret_key_path) unless cap?(path)
+
+        Packager.new.transform_cap(path) { |dir| new(dir).sign(secret_key_path) }
+        path
+      end
+
+      # Verifies the declared OpenPGP signature of a package directory
+      # or .cap file (false on mismatch; raises typed
+      # Signer::SignatureError subclasses on structural problems, e.g.
+      # an unsigned package). public_key_path is an OpenPGP public key
+      # file; without it the key embedded in the package is used.
+      def self.verify_package(path, public_key_path = nil)
+        return new(path).verify(public_key_path) unless cap?(path)
+
+        Packager.new.with_unpacked_cap(path) { |dir| new(dir).verify(public_key_path) }
+      end
+
+      def self.cap?(path)
+        File.extname(path) == ".cap"
+      end
+      private_class_method :cap?
+
+      # Signs the package directory in place: embeds the armored public
+      # key, regenerates security.json (checksums plus digitalSignatures
+      # with certificateType "OpenPGP") and writes the armored detached
+      # OpenPGP signature to signature.sig.
+      def sign(secret_key_path)
+        loaded = OpenPgp.load_key(secret_key_path, secret: true)
+        File.write(public_key_path, loaded.key.export_public(armored: true))
+        security = Security.generate(@package_path, digital_signatures: digital_signatures)
+        security.save_to_file
+        signature = loaded.rnp.detached_sign(
+          input: Rnp::Input.from_string(payload(security)),
+          signers: loaded.key, hash: HASH, armored: true
+        )
+        File.write(signature_path, signature)
+        signature_path
+      end
+
+      # True when the declared signature verifies against the payload.
+      # Without an explicit key path, the embedded public key is used.
+      def verify(public_key_path = nil)
+        signature = read_signature
+        data = payload(declared_security)
+        loaded = verification_key(public_key_path)
+        signature_matches(loaded, data, signature)
+      end
+
+      def verify!(public_key_path = nil)
+        return true if verify(public_key_path)
+
+        raise Signer::SignatureMismatchError,
+              "digital signature does not match the package contents"
+      end
+
+      def signed?
+        declared_security.signed?
+      end
+
+      private
+
+      # Reached only after the rnp binding loaded successfully (the
+      # verification key is loaded first), so the Rnp error constants
+      # are defined here.
+      def signature_matches(loaded, data, signature)
+        loaded.rnp.detached_verify(data: Rnp::Input.from_string(data),
+                                   signature: Rnp::Input.from_string(signature))
+        true
+      rescue Rnp::InvalidSignatureError
+        false
+      end
+
+      def declared_security
+        Security.new(File.join(@package_path, Package::SECURITY_FILE))
+      end
+
+      def digital_signatures
+        DigitalSignatures.new(certificate_type: CERTIFICATE_TYPE,
+                              public_key: PUBLIC_KEY_FILE,
+                              signature_file: Package::SIGNATURE_FILE)
+      end
+
+      # The canonical signed payload (ARCHITECTURE.md section 6a,
+      # identical to Signer's): the concatenation, in sorted
+      # package-relative path order, of the bytes of every file covered
+      # by the integrity checksums.
+      def payload(security)
+        security.checksums.keys.sort.map do |relative_path|
+          file_path = File.join(@package_path, relative_path)
+          unless File.file?(file_path)
+            raise Signer::SignatureError,
+                  "file covered by checksums is missing: #{relative_path}"
+          end
+
+          File.binread(file_path)
+        end.join
+      end
+
+      def read_signature
+        unless signed?
+          raise Signer::UnsignedPackageError,
+                "package is not signed (security.json declares no digitalSignatures)"
+        end
+        return File.binread(signature_path) if File.file?(signature_path)
+
+        raise Signer::SignatureError, "signature file missing: #{signature_file_name}"
+      end
+
+      def signature_file_name
+        declared_security.digital_signatures.signature_file || Package::SIGNATURE_FILE
+      end
+
+      def signature_path
+        File.join(@package_path, signature_file_name)
+      end
+
+      def public_key_path
+        File.join(@package_path, PUBLIC_KEY_FILE)
+      end
+
+      def verification_key(public_key_path)
+        return OpenPgp.load_key(public_key_path) if public_key_path
+
+        embedded = declared_security.digital_signatures&.public_key || PUBLIC_KEY_FILE
+        embedded_path = File.join(@package_path, embedded)
+        return OpenPgp.load_key(embedded_path) if File.file?(embedded_path)
+
+        raise Signer::SignatureError, "public key file missing: #{embedded}"
+      end
+    end
+  end
+end

data/lib/capsium/package/security_config.rb

@@ -19,13 +19,17 @@ module Capsium
       end
     end
 
-    # The "digitalSignatures" object of security.json. Signing is a later
-    # phase; the model parses the canonical fields only.
+    # The "digitalSignatures" object of security.json. certificateType
+    # selects the signature scheme: absent means RSA-SHA256 (X.509),
+    # "OpenPGP" an OpenPGP signature (the publicKey then holds an
+    # armored OpenPGP public key).
     class DigitalSignatures < Lutaml::Model::Serializable
+      attribute :certificate_type, :string
       attribute :public_key, :string
       attribute :signature_file, :string
 
       json do
+        map "certificateType", to: :certificate_type
         map "publicKey", to: :public_key
         map "signatureFile", to: :signature_file
       end

data/lib/capsium/package/signer.rb

@@ -54,11 +54,26 @@ module Capsium
 
       # Verifies the declared signature of a package directory or .cap
       # file (false on mismatch; raises typed SignatureError subclasses
-      # on structural problems, e.g. an unsigned package).
+      # on structural problems, e.g. an unsigned package). The signer is
+      # selected from the declared digitalSignatures certificateType:
+      # OpenPGP packages verify through OpenPgpSigner.
       def self.verify_package(path, public_key_path = nil)
-        return new(path).verify(public_key_path) unless cap?(path)
+        return signer_class_for(path).new(path).verify(public_key_path) unless cap?(path)
 
-        Packager.new.with_unpacked_cap(path) { |dir| new(dir).verify(public_key_path) }
+        Packager.new.with_unpacked_cap(path) do |dir|
+          signer_class_for(dir).new(dir).verify(public_key_path)
+        end
+      end
+
+      # The signer class matching a package's declared signature scheme:
+      # OpenPgpSigner when security.json declares
+      # digitalSignatures.certificateType "OpenPGP", Signer otherwise.
+      def self.signer_class_for(package_path)
+        security = Security.new(File.join(package_path, Package::SECURITY_FILE))
+        return OpenPgpSigner if security.digital_signatures&.certificate_type ==
+                                OpenPgpSigner::CERTIFICATE_TYPE
+
+        self
       end
 
       def self.cap?(path)

data/lib/capsium/package/store.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "fileutils"
 require "json"
 require "zip"
 
@@ -63,8 +64,34 @@ module Capsium
         end
       end
 
+      # Installs the .cap at source_path into the store as file_name
+      # (conventionally "<name>-<version>.cap"), records guid ->
+      # file_name in index.json (atomically, tmp + rename) and returns
+      # the installed path. Used by registry installs
+      # (Capsium::Registry#install).
+      def install(source_path, guid:, file_name:)
+        destination = File.join(@dir, file_name)
+        tmp = "#{destination}.tmp-#{Process.pid}"
+        FileUtils.cp(source_path, tmp)
+        File.rename(tmp, destination)
+        record_index(guid, file_name)
+        destination
+      end
+
       private
 
+      # Records guid -> file_name in the store's index.json and drops
+      # the memoized catalog so the new .cap is found.
+      def record_index(guid, file_name)
+        index = load_index.merge(guid => file_name)
+        path = File.join(@dir, INDEX_FILE)
+        tmp = "#{path}.tmp-#{Process.pid}"
+        File.write(tmp, JSON.pretty_generate(index))
+        File.rename(tmp, path)
+        @load_index = index
+        @catalog = nil
+      end
+
       def indexed_path(guid)
         file = load_index[guid]
         file && File.join(@dir, file)