# Shazam: A Portable Perl Capability Library Shazam was my attempt to turn a large personal library of Perl routines into a portable capability system: one function per module, a stable callable façade, generated documentation, and a bundled distribution for environments where many small files were inconvenient. In present-day language, it was a standard library organized for more than one deployment geometry. A developer could load capabilities individually, call them through one generated namespace, or carry a single combined file. The implementation predates modern package habits, but the architectural question is current: **how can the same behavior remain modular for development and portable for deployment?** Shazam is also the clearest recovered ancestor of the later [[projects/X and XApps - Drop the Folder and It Runs|X and XApps]] philosophy. --- ## What this architecture would be called now - **One capability per Perl module.** Modern translation: [[wiki/Capability-Oriented Architecture|capability-oriented architecture]] and fine-grained modularity. - **One public façade over many implementation files.** Modern translation: [[wiki/Facade Pattern|façade pattern]] and [[wiki/Capability Registry|capability discovery]]. - **Require a module only when its function is first called.** Modern translation: [[wiki/Lazy-Loading Facade|lazy loading]] and on-demand capability activation. - **Generate documentation, façade code, and a combined library from one module corpus.** Modern translation: [[wiki/Generated Packaging|generated packaging]], documentation-as-code, and a build pipeline. - **Preserve modular source while shipping one combined file.** Modern translation: [[wiki/Generated Combined Distribution|generated bundle]] and [[wiki/Single-File Portability|single-file portability]]. - **Stable function names hide the file that implements them.** Modern translation: a stable public API over replaceable implementations. - **A prefix taxonomy such as `io_`, `string_`, and `struct_` groups callable behavior.** Modern translation: a namespaced [[wiki/Tool Contract|tool/capability surface]]. - **KeyDB supplies portable file persistence.** Modern translation: an embedded [[wiki/Key-Value Store|key-value store]] and [[wiki/Local-First Software|local-first persistence]]. - **The same primitives support many applications.** Modern translation: a reusable platform library or small [[wiki/Modular Monolith|modular monolith]]. - **A function is found and loaded through filesystem conventions.** Modern translation: a filesystem-native [[wiki/Plugin Architecture|plugin architecture]]. - **Future runtimes implement the same named behavior.** Modern translation: [[wiki/Polyglot API|polyglot API parity]], [[wiki/Portable Contract|portable contracts]], and [[wiki/Conformance Testing|contract testing]]. - **A model or host sees only the capabilities relevant to a task.** Modern analogy: [[wiki/Filesystem-Based Agent Skills|filesystem-based agent skills]], [[wiki/Progressive Disclosure|progressive disclosure]], and AI [[wiki/Capability Discovery|capability discovery]]. The compact translation is: **Shazam was a capability-oriented, filesystem-native standard library with generated façades, documentation, lazy loading, and alternate deployment bundles.** In an AI system, the same design instinct appears when tools or skills are separately addressable, loaded only when relevant, and governed by stable schemas. See [[wiki/Modern Technical Translation Map|Modern Technical Translation Map]] for the shared vocabulary. ## From a monolith to a capability library The earliest large recovered source in this lineage is `Pro.pm`, identified internally as the Professional Developer's Library. It contains 144 routines and bears a 1999–2000 copyright notice. It is a conventional large library file: useful behavior accumulated in one place. Shazam decomposed and expanded that collection. The recovered top-level Shazam directory contains 236 Perl module files. Its generated façade exposes 233 callable routines, and the documentation generator produced a matching set of 233 text references. A surviving `shazam-complete.pm` bundle is 8,315 lines long. The exact totals differ depending on whether support and generator modules are counted. The important architectural fact does not: the library had hundreds of separately addressable capabilities and tooling that generated alternative ways to consume them. ```text Pro.pm one large Perl library | v Shazam modules one capability per file | +--> generated lazy-loading façade +--> generated reference documents +--> generated combined distribution ``` ## The build system The build script did more than concatenate files. It treated the modules as a source corpus from which several products could be generated. For each capability, it created a small façade routine that required the relevant module on first use and forwarded the original arguments into it. The same build process assembled the combined distribution and emitted reference material. That creates three useful operating modes: 1. **Modular development** — inspect, edit, or deploy one capability at a time. 2. **Stable namespace** — call the library through a predictable façade without manually locating modules. 3. **Single-file portability** — deploy a combined version where directory depth, file count, or installation control is limited. This is a primitive form of generated packaging. It separated the authoritative capability files from the way a particular host needed to load them. ## What the library contained The functions were broad enough to support real application development rather than one product. The recovered categories include: - string processing and text normalization; - filesystem and stream operations; - CGI and web request handling; - HTML construction and escaping; - structured data conversion; - dates and times; - images and graphics; - network operations; - finance and calculations; - desktop GUI experiments; - KeyDB file persistence. The category prefixes later reappear conceptually in X. At least one function has been compared directly across the generations: Shazam's HTML select-box builder and its later PHP X descendant use the same core construction algorithm, with the PHP version adding evolved inputs and escaping behavior. That comparison matters because similar names alone do not prove lineage. A preserved algorithm does. ## KeyDB and file-native persistence [[wiki/KeyDB|KeyDB]] sits beside Shazam as its first-party persistence layer. It exposes operations for reading and writing files and fields, merging keyed data, incrementing values, deleting keys, creating unique identifiers, searching and replacing, flattening and expanding structures, and serializing data. The design reflects an enduring preference: keep information in inspectable, transferable files and make the library supply the structure. This reduced environmental assumptions and allowed applications to operate without first requiring a database server. That does not mean a file store is the correct answer to every scale problem. It means the canonical record remained portable. Later systems explored rebuildable SQLite projections for faster reading while preserving folders and text as the authority. ## Why it was technically significant Shazam anticipated several practices that are now ordinary: - a capability-oriented rather than application-oriented library; - stable public interfaces over replaceable implementations; - generated documentation from an implementation corpus; - lazy loading to reduce unnecessary initialization; - more than one distribution format from the same source; - small modules that can be assembled into larger systems; - file-native storage with minimal external infrastructure. It should not be misrepresented as a modern package manager or a formally specified cross-language SDK. It did not have today's manifest standards, semantic-version discipline, typed interfaces, or conformance infrastructure. Its significance is that it was already solving the underlying portability and reuse problem. ## From Shazam to X The later X work broadened the goal from a Perl library to aligned capabilities across PHP, browser JavaScript, Node, and future runtimes. Shazam supplies both a donor corpus and a warning. The donor value is obvious: many behaviors already exist, with names, algorithms, and years of accumulated edge-case thinking. The warning is that copying functions into several languages does not keep them aligned. Once implementations diverge, the shared name can conceal different behavior. The modern continuation therefore begins with contracts: ```text canonical capability name + input rules + normalized output + error behavior + shared fixtures = portable contract ``` PHP, JavaScript, Python, and Perl implementations can then prove conformance against the same fixtures. Host-specific operations—files, HTTP, editors, databases—remain adapters around deterministic core logic. ## Present relevance Shazam is not merely historical code to be displayed. It answers a current architectural need in the writing platform. The quote and passage generator requires text cleanup, protected-region handling, Markdown-aware parsing, deterministic identity, collision detection, paths, slugs, and provenance. Those capabilities must eventually work in an Obsidian plugin, AutoSites, Node command-line tools, PHP services, Python recovery scripts, and Perl migration utilities. If each host reimplements them, the archive will accumulate subtly incompatible truths. If they share contracts, Shazam's original goal becomes enforceable: one capability, many usable forms. The right modernization policy is therefore selective: 1. identify the earliest and most mature versions of a function; 2. record its observed behavior and provenance; 3. separate pure transformation logic from host assumptions; 4. create fixtures for ordinary cases and historical edge cases; 5. adopt, adapt, defer, or reject the capability explicitly; 6. preserve compatibility aliases only where they serve real data or applications. That is archaeology converted into engineering. --- ## Evidence status | Claim | Basis | Status | |---|---|---| | `Pro.pm` contains 144 routines and identifies a 1999–2000 library lineage | Surviving Perl source | Artifact-visible | | The recovered Shazam tree contains 236 top-level module files | Direct filesystem inventory | Artifact-visible | | The generated façade and documentation cover 233 callable capabilities | Surviving generated façade, modules, and reference files | Artifact-visible | | Shazam generated modular, lazy-loading, documented, and combined forms | Surviving build script and generated outputs | Artifact-visible | | KeyDB supplied first-party file persistence | Surviving `KeyDB.pm` interface and implementation | Artifact-visible | | Shazam is a direct ancestor of later X functions | Matching naming structure plus a verified Perl-to-PHP algorithm comparison | Artifact-visible reconstruction | | Some routines originated in work from 1996 onward and were formalized later | Bryant McGill's recollection | Owner account | ## Related projects - [[wiki/Shazam Perl Library|Shazam Perl Library]] - [[wiki/KeyDB|KeyDB]] - [[projects/X and XApps - Drop the Folder and It Runs|X and XApps: Drop the Folder and It Runs]] - [[projects/AutoSites - Folder-Native Publishing and Distribution|AutoSites: Folder-Native Publishing and Distribution]] - [[projects/XDO - Executable Markdown and Portable Workflows|XDO: Executable Markdown and Portable Workflows]]