// SPDX-License-Identifier: MPL-2.0-or-later
// SPDX-FileCopyrightText: 2024-2025 Palimpsest Stewardship Council

= SPDX Compliance Strategy for Palimpsest License
:toc:
:toclevels: 3
:numbered:
:author: Palimpsest Stewardship Council
:revnumber: 1.0
:revdate: 2025-11-28
:doctype: book
:description: Comprehensive SPDX compliance documentation for RSR Gold certification

== Overview

This document outlines the Palimpsest License project's comprehensive SPDX
(Software Package Data Exchange) compliance strategy, implemented to achieve
**Rhodium Standard Repository (RSR) Gold** certification.

=== What is SPDX?

SPDX is an open standard for communicating software bill of material information,
including components, licenses, copyrights, and security references. It is
maintained by the Linux Foundation and has been adopted as ISO/IEC 5962:2021.

=== Why SPDX Compliance Matters

* **License Clarity**: Unambiguous machine-readable license identification
* **Supply Chain Transparency**: Clear provenance and copyright information
* **Automated Compliance**: Tools can automatically verify license compliance
* **Legal Certainty**: Reduces ambiguity in license interpretation
* **Industry Standard**: Widely adopted in open source and enterprise software

== License Identifier Mapping

=== Primary License Identifiers

The Palimpsest License project uses the following SPDX license identifiers:

[cols="1,2,3"]
|===
|Identifier |Applies To |Description

|`MIT`
|Source code, tools, infrastructure
|MIT License for permissive reuse

|`Palimpsest-0.4`
|License documentation, creative materials
|Palimpsest License version 0.4 (custom identifier)

|`CC-BY-SA-4.0`
|General documentation
|Creative Commons Attribution-ShareAlike 4.0

|`MIT AND Palimpsest-0.4`
|Root LICENSE.txt
|Dual licensing option
|===

=== Custom License Identifier: Palimpsest-0.4

The `Palimpsest-0.4` identifier is a **custom SPDX identifier** for the
Palimpsest License v0.4. While not currently registered in the official SPDX
License List, it follows SPDX naming conventions:

* Format: `LicenseID-VersionNumber`
* Full license text: `LICENSES/v0.4/palimpsest-v0.4.md`
* SPDX-compatible metadata: `METADATA_v0.4/spdx/`

==== Registration Status

We plan to submit `Palimpsest-0.4` to the SPDX License List once the license
reaches stable v1.0 status. Until then, it is used as a LicenseRef-style
identifier for internal consistency.

== SPDX Header Format by File Type

=== Haskell Files (.hs)

[source,haskell]
----
{-
SPDX-License-Identifier: MPL-2.0-or-later
SPDX-FileCopyrightText: 2024-2025 Palimpsest Stewardship Council
-}
----

**Location**: First lines of file, before any code or module declarations

**Rationale**: Haskell block comment syntax ensures headers don't interfere
with language pragmas or imports.

=== ReScript Files (.res)

[source,rescript]
----
// SPDX-License-Identifier: MPL-2.0-or-later
// SPDX-FileCopyrightText: 2024-2025 Palimpsest Stewardship Council
----

**Location**: First lines of file

**Rationale**: Standard single-line comments are idiomatic in ReScript/JavaScript-style languages.

=== JavaScript Files (.js)

[source,javascript]
----
// SPDX-License-Identifier: MPL-2.0-or-later
// SPDX-FileCopyrightText: 2024-2025 Palimpsest Stewardship Council
----

**Location**: After shebang (`#!/usr/bin/env node`) if present, otherwise first lines

**Rationale**: Consistent with ReScript and modern JavaScript conventions.

=== YAML/JSON Configuration Files

[source,yaml]
----
# SPDX-License-Identifier: MPL-2.0-or-later
# SPDX-FileCopyrightText: 2024-2025 Palimpsest Stewardship Council
----

**Location**: First lines of file

**Rationale**: YAML comment syntax, compatible with configuration file parsers.

=== Markdown/AsciiDoc Documentation

[source,asciidoc]
----
// SPDX-License-Identifier: MPL-2.0-or-later
// SPDX-FileCopyrightText: 2024-2025 Palimpsest Stewardship Council
----

**Location**: First lines of file, before document title

**Rationale**: AsciiDoc-style comments; Markdown parsers typically ignore them.

**License Choice**: Documentation uses `CC-BY-SA-4.0` or dual licensing with
`Palimpsest-0.4` to allow broad reuse while maintaining attribution.

== Audit Procedures

=== Automated Auditing with `just audit-licence`

The project provides an automated SPDX audit recipe in the `justfile`:

[source,bash]
----
just audit-licence
----

This command:

1. **Scans all source directories** for files missing SPDX headers
2. **Reports violations** with file paths
3. **Exits with error code 1** if any files lack headers
4. **Verifies compliance** across:
   - Haskell source (`TOOLS/validation/haskell/src/`, `app/`, `test/`)
   - ReScript source (`rescript/src/`)
   - JavaScript integration code (`assets/`, `integrations/client/`)
   - YAML configuration files (`integrations/`, `TOOLS/`)

=== Manual Audit Procedure

For comprehensive manual auditing:

[source,bash]
----
# Find all Haskell files without SPDX headers
find TOOLS/validation/haskell -name "*.hs" \
  -exec grep -L "SPDX-License-Identifier" {} \;

# Find all ReScript files without SPDX headers
find rescript/src -name "*.res" \
  -exec grep -L "SPDX-License-Identifier" {} \;

# Find all project JavaScript files without SPDX headers
find integrations assets -name "*.js" \
  -not -path "*/node_modules/*" \
  -exec grep -L "SPDX-License-Identifier" {} \;

# Find all YAML files without SPDX headers
find . -name "*.yml" -o -name "*.yaml" \
  -not -path "*/node_modules/*" \
  -not -path "*/.git/*" \
  -exec grep -L "SPDX-License-Identifier" {} \;
----

=== Continuous Integration

SPDX compliance is enforced in CI/CD pipelines via:

[source,yaml]
----
- name: Audit SPDX License Headers
  run: just audit-licence
----

**Enforcement**: All pull requests must pass SPDX audit before merging.

== Exception Handling

=== Excluded Files

The following file types are **excluded** from SPDX header requirements:

1. **Third-party dependencies** (`node_modules/`, vendored libraries)
2. **Generated files** (build artifacts, compiled outputs)
3. **Data files** (JSON data, CSV, binary assets like images/fonts)
4. **Legacy archived content** (`ARCHIVE/`, historical versions)
5. **Minimal configuration** (`.editorconfig`, `.gitignore`, `.prettierrc`)

**Rationale**: These files either have their own licensing (dependencies) or
don't constitute copyrightable expression (configuration).

=== Dual Licensing Exceptions

Some files use **dual licensing** (`MIT AND Palimpsest-0.4`):

* `LICENSE.txt` - Root project license
* Integration examples that demonstrate Palimpsest License usage
* Documentation showing both technical and creative aspects

**Purpose**: Provides users flexibility to choose the most appropriate license
for their use case.

== Machine-Readable SPDX Documents

=== SPDX 2.3 RDF/XML

Location: `METADATA_v0.4/spdx/palimpsest-v0.4.rdf`

Contains:

* Complete package information
* License declarations for all components
* Copyright holders and contributors
* File-level license annotations

=== SPDX 2.3 Tag-Value Format

Location: `METADATA_v0.4/spdx/palimpsest-v0.4.spdx`

A human-readable alternative to RDF/XML, suitable for:

* Manual review
* Simple tooling integration
* Git-friendly diffs

=== JSON-LD Metadata

Location: `METADATA_v0.4/json-ld/palimpsest-v0.4.jsonld`

Embeds SPDX information in structured JSON-LD format, enabling:

* Semantic web integration
* Schema.org compatibility
* Rich metadata queries

== Tools and Validation

=== Recommended SPDX Tools

[cols="1,2,2"]
|===
|Tool |Purpose |Link

|SPDX Maven Plugin
|Java/Maven projects
|https://github.com/spdx/spdx-maven-plugin

|SPDX Gradle Plugin
|Gradle builds
|https://github.com/spdx/spdx-gradle-plugin

|FOSSology
|License scanning
|https://www.fossology.org/

|REUSE Tool
|SPDX compliance helper
|https://reuse.software/

|spdx-tools
|Official SPDX utilities
|https://github.com/spdx/tools
|===

=== Integration with REUSE Specification

The project follows the **REUSE Software specification** (https://reuse.software/):

1. **License files** in `LICENSES/` directory
2. **Copyright/license headers** in all source files
3. **DEP5 copyright file** (planned for v1.0)

**REUSE compliance check**:
[source,bash]
----
reuse lint
----

== Migration and Updates

=== Adding SPDX Headers to New Files

**Template for new Haskell files**:
[source,haskell]
----
{-
SPDX-License-Identifier: MPL-2.0-or-later
SPDX-FileCopyrightText: 2024-2025 Palimpsest Stewardship Council
-}

{-# LANGUAGE OverloadedStrings #-}

module MyModule where
----

**Template for new JavaScript files**:
[source,javascript]
----
// SPDX-License-Identifier: MPL-2.0-or-later
// SPDX-FileCopyrightText: 2024-2025 Palimpsest Stewardship Council

/**
 * Module description
 */
----

=== Updating Copyright Dates

SPDX-FileCopyrightText should reflect:

* Initial year of creation
* Range through current year if modified: `2024-2025`

**Example evolution**:

* File created 2024: `2024`
* Updated in 2025: `2024-2025`
* Updated in 2026: `2024-2026`

=== License Identifier Changes

When the Palimpsest License version updates:

1. Update SPDX identifier: `Palimpsest-0.5`, `Palimpsest-1.0`, etc.
2. Add new license text to `LICENSES/vX.Y/`
3. Update machine-readable metadata in `METADATA_vX.Y/`
4. Run full audit: `just audit-licence`
5. Document changes in `CHANGELOG.md`

== Governance and Compliance Review

=== Responsibility

**Palimpsest Stewardship Council** oversees SPDX compliance:

* Reviews all license identifier usage
* Approves new SPDX identifiers for custom licenses
* Ensures consistent application across the codebase

=== Review Cadence

* **Per-commit**: Automated CI/CD checks
* **Quarterly**: Manual audit of all source files
* **Per-release**: Comprehensive SPDX document generation

=== Dispute Resolution

Questions about SPDX header usage should be raised via:

1. **GitHub Issue** with "SPDX" label
2. **Discussion** in project forums
3. **Council review** for ambiguous cases

== RSR Gold Compliance Checklist

The following requirements have been met for RSR Gold certification:

- [x] `LICENSE.txt` created in plain text format
- [x] SPDX-License-Identifier in LICENSE.txt header
- [x] Dual licensing clearly stated: `MIT AND Palimpsest-0.4`
- [x] All Haskell source files have SPDX headers
- [x] All ReScript source files have SPDX headers
- [x] All JavaScript source files have SPDX headers
- [x] All YAML configuration files have SPDX headers
- [x] `audit-licence` recipe added to Justfile
- [x] Automated SPDX audit in CI/CD pipeline
- [x] Machine-readable SPDX metadata (JSON-LD, RDF/XML)
- [x] Comprehensive SPDX compliance documentation

== References and Resources

=== Official SPDX Resources

* **SPDX Specification**: https://spdx.github.io/spdx-spec/
* **SPDX License List**: https://spdx.org/licenses/
* **SPDX GitHub**: https://github.com/spdx

=== Related Standards

* **REUSE Software**: https://reuse.software/
* **ISO/IEC 5962:2021**: SPDX® Specification V2.2.1
* **Rhodium Standard Repository**: https://rhodiumrepository.org/

=== Project-Specific Documentation

* xref:../GOVERNANCE.md[Governance Model]
* xref:../CONTRIBUTING.md[Contributing Guidelines]
* xref:../LICENSES/v0.4/palimpsest-v0.4.md[Palimpsest License v0.4]
* xref:bilingual-map.md[Bilingual License Mapping]

== Changelog

[cols="1,2,4"]
|===
|Version |Date |Changes

|1.0
|2025-11-28
|Initial SPDX compliance documentation for RSR Gold certification
|===

---

For questions or clarifications about SPDX compliance in this project, please
consult the **Palimpsest Stewardship Council** via GitHub Issues or the project
repository.
