signal-codec

Verify transmission protocol compatibility across signal fragments

Part of the Amulet Digital Signal Archives

A minimal, fast protocol that scans your archival node and verifies that all signal fragments use compatible transmission codecs (licenses). Identifies codec conflicts, unverified protocols, and viral encoding that could corrupt the archive.

Overview

In the Signal Archives, every signal fragment is transmitted using a specific codec (license) that defines how it can be decoded, modified, and retransmitted.

When fragments with incompatible codecs interact, transmission fails or becomes corrupted. signal-codec verifies codec interoperability across your entire archival node.

Codec Types

Open Codecs (Permissive)

• MIT, Apache-2.0, BSD-3-Clause, ISC
• Universal interoperability
• Can be freely retransmitted

Viral Codecs (Copyleft)

• GPL-2.0, GPL-3.0, AGPL-3.0
• Force all connected fragments to adopt same encoding
• Override other codec standards

Encrypted Codecs (Restricted)

• UNLICENSED, PROPRIETARY
• Unknown compatibility
• Verification impossible

Multi-Codec Fragments (Dual-licensed)

• "MIT OR Apache-2.0"
• Adapt to compatible codec
• Flexible transmission

Features

• Fragment scanning - recursively analyzes all installed fragments
• Codec verification - validates transmission protocol compatibility
• Viral codec detection - flags GPL/AGPL fragments for review
• Multi-codec support - handles "MIT OR Apache-2.0" style encoding
• Fast - analyzes hundreds of fragments in seconds
• Beautiful output - formatted tables with color-coded conflicts
• JSON export - machine-readable output with --json flag

Installation

npm install -g signal-codec

Or run directly:

npx signal-codec

Usage

Analyze current archive

signal-codec

Analyze specific archive

signal-codec /path/to/archive

Detailed analysis

signal-codec --detailed

JSON output

signal-codec --json

Example Output

◆ SIGNAL-CODEC — Transmission Protocol Analysis
────────────────────────────────────────────

Archive Codec: MIT
Fragments Analyzed: 245
Codec Conflicts: 2

⚠ 2 transmission protocol conflicts detected

────────────────────────────────────────────
Codec Conflicts
────────────────────────────────────────────

Fragment              Codec       Conflict
────────────────────────────────────────────────────────
gpl-package           GPL-3.0     [error] Viral codec incompatible with MIT
internal-tool         ENCRYPTED   [warning] Codec verification failed

✗ 1 incompatible codec
⚠ 1 unverified codec

Configuration

Create a signal-codec.config.json in your archive root:

{
  "ignoreFragments": ["internal-package"],
  "allowViralCodecs": ["GPL-2.0"],
  "treatEncryptedAs": "warning"
}

Codec Interoperability Matrix

The tool includes a default interoperability matrix that handles common codec scenarios:

Open Codecs (Universal)

• MIT: Interoperable with MIT, Apache-2.0, BSD-3-Clause, ISC, BSD-2-Clause, MPL-2.0
• Apache-2.0: Interoperable with MIT, Apache-2.0, BSD-3-Clause, ISC
• BSD-3-Clause: Interoperable with MIT, Apache-2.0, BSD-3-Clause, ISC, BSD-2-Clause
• ISC: Interoperable with most open codecs

Viral Codecs (Override)

• GPL-2.0: Only interoperable with GPL-2.0, AGPL-2.0 (forces adoption)
• GPL-3.0: Only interoperable with GPL-3.0, AGPL-3.0 (forces adoption)
• AGPL-3.0: Most restrictive viral codec (network transmission clause)

Special Cases

• ENCRYPTED: Flags as warning - verification required
• PROPRIETARY: Flags as warning - manual review required
• Multi-codec (MIT OR Apache): Interoperable if any codec matches

How It Works

1. Reads archive manifest (package.json) to determine archive codec
2. Scans installed fragments to catalog transmission protocols
3. Checks each fragment's codec against interoperability matrix
4. Reports conflicts grouped by severity (error, warning, info)
5. Returns exit code (0 for verified, 1 for conflicts)

Common Conflicts

"Viral codec incompatible"

Viral codecs (GPL/AGPL) force all connected fragments to adopt the same encoding:

# Fragment pathway
your-archive (MIT)
└─ some-package
   └─ gpl-library (GPL-3.0) ⚠️

Resolution:

• Find open codec alternative
• Check for dual-codec release
• Isolate in development-only pathway
• Adopt GPL-3.0 for entire archive

"Codec verification failed"

Some fragments don't document their transmission protocol:

cd node_modules/fragment-name && cat LICENSE

"Fragments not found"

Run npm install first to install signal fragments.

API Usage

import { CodecGuard } from 'signal-codec';

const guard = new CodecGuard();
await guard.verify('./my-archive', { verbose: true });

Field Notes

Transmission protocol compatibility is essential for archival integrity. When fragments with incompatible codecs interact, the transmission either fails or corrupts surrounding signals.

Viral codecs (GPL/AGPL) are particularly challenging - they override all surrounding encoding standards, forcing the entire transmission pathway to adopt the same protocol. This is intentional: viral codecs ensure derivative transmissions remain open and verifiable.

Encrypted codecs (proprietary/unlicensed) present unknown risk. Without documented transmission protocols, codec verification is impossible. These fragments should be reviewed manually before integration.

Multi-codec fragments offer flexibility - they can adapt their encoding to match the surrounding transmission environment. When possible, prefer fragments that support multiple interoperable codecs.

Supported Codecs

signal-codec includes transmission protocol verification for:

Open Codecs:

• MIT, Apache-2.0, BSD-2-Clause, BSD-3-Clause, ISC
• 0BSD, Unlicense, WTFPL
• MPL-2.0, LGPL-2.1, LGPL-3.0

Viral Codecs:

• GPL-2.0, GPL-3.0
• AGPL-2.0, AGPL-3.0

Encrypted Codecs:

• UNLICENSED, PROPRIETARY
• Custom/Unknown codecs

Multi-Codec:

• Any SPDX expression (e.g., "MIT OR Apache-2.0")

For unknown codecs, signal-codec flags them for manual verification.

Troubleshooting

"Failed to analyze archive"

Ensure you're in an archival node with a manifest (package.json):

npm init
npm install signal-codec
signal-codec

"Viral codec detected"

Viral codecs (GPL/AGPL) force codec adoption. Options:

1. Replace with open codec alternative
2. Adopt viral codec for entire archive
3. Isolate fragment in development pathway
4. Check for dual-codec availability

"Codec verification failed"

Some fragments don't document codecs. Options:

1. Review fragment source for protocol info
2. Contact fragment maintainer
3. Assume open codec (risk)
4. Remove fragment if incompatible

Migration from spdx-checker

signal-codec is the rebranded version of spdx-checker, now part of the Amulet Digital Signal Archives.

To migrate:

npm uninstall -g spdx-checker
npm install -g signal-codec

All functionality is preserved. CLI commands are compatible.

Contributing

We welcome contributions to the Signal Archives! See CONTRIBUTING.md.

License

MIT License - see LICENSE file for details.

Support

• 🐛 Report codec conflicts
• 💬 Network discussions
• 📚 Archive documentation

Related Archival Tools

• void-purge — Remove orphaned artifacts
• signal-decay — Detect signal corruption
• PixelFactory — The Initiate's Lens

Signal integrity maintained by Amulet Digital
Archive Protocol • Node: signal-codec • Version: 1.0.0