A machine-readable trace layer for recording authorized AI usage, retrieval events, provenance signals, attribution evidence, and allocation-trigger candidates.
This repository defines the Trace Layer of Royalty OS v3.0.
The Trace Layer is designed to record how AI systems access, retrieve, reference, quote, summarize, transform, or structurally depend on creative and knowledge-based content.
Its purpose is not to directly decide payment, ownership, or legal liability. Its purpose is to provide a reliable evidence layer that can connect to review and downstream allocation systems.
Royalty OS v3.0 is based on three major layers:
Permission Layer
↓
Trace Layer
↓
Allocation Layer
This repository focuses on the middle layer:
Trace Layer = evidence infrastructure for AI-era value circulation
The Trace Layer aims to move AI-based content use from:
AI reference as invisible extraction
toward:
AI reference as traceable value circulation
Royalty OS Trace Layer v3.0 can also be understood as part of a broader Civilization OS architecture.
In that wider architecture, the Trace Layer sits between Permission and Allocation.
Origin
↓
Structure
↓
Permission
↓
Trace
↓
Allocation
↓
Civilization Circulation
The Trace Layer records AI usage evidence and produces allocation-trigger candidates, while leaving judgment and distribution to downstream review and allocation systems.
See:
docs/civilization-os-architecture.md
Royalty OS Trace Layer v3.0 is designed to support:
- Machine-readable recording of AI retrieval and reference events
- Permission-aware usage evidence
- RAG retrieval logging
- Direct quote tracing
- Concept-level reference tracing
- Structure-level influence tracing
- Outlier origin detection
- C2PA-inspired provenance metadata
- Lightweight Royalty OS C2PA Extension metadata
- Watermark-aware verification signals
- Privacy-aware trace records
- Allocation-readiness status
- Allocation Trigger generation
- Human or multi-party review before final distribution
- note/RAG-style social proof experiments
- Civilization OS-level architecture mapping
- Interoperability with future Royalty OS, RSL, C2PA, RAG, provenance, and AI audit ecosystems
This repository does not attempt to:
- Prove legal authorship by itself
- Automatically determine payment
- Replace copyright law
- Replace licensing contracts
- Replace platform policies
- Replace C2PA
- Decide disputes without review
- Claim perfect attribution accuracy
- Require all AI systems to use one centralized registry
- Store unnecessary user identity or raw prompts
- Claim that any external platform currently implements this specification
- Define a complete Civilization OS implementation
The Trace Layer provides evidence.
Trace = evidence
Review = judgment
Allocation = distribution
Royalty OS Trace Layer v3.0 consists of three internal sublayers:
Embedding Layer
↓
Logging Layer
↓
Verification Layer
The Embedding Layer attaches machine-readable identifiers, permission metadata, or provenance signals to participating content.
Possible mechanisms include:
- Text watermarking
- Media watermarking
- C2PA-style manifest metadata
- Royalty OS C2PA Extension metadata
- Royalty OS content identifiers
- Soft binding to external manifests or registries
- Article-level metadata blocks for early experiments
Example metadata:
royalty:
os_id: "royalty-os:example:content:001"
permission_scope: "allow_reference"
version: "3.0"
trace_priority: "high"The Embedding Layer should be opt-in where possible.
The Logging Layer records what happened when an AI system retrieved, referenced, quoted, or structurally used content.
Typical logging sources include:
- RAG retrieval logs
- AI search logs
- Agent memory logs
- Training data audits
- Evaluation runs
- Manual audits
- Third-party reports
- Simulated note/RAG experiment records
The core object of this layer is the Royalty Trace Event.
The Verification Layer checks whether a trace event is supported by evidence.
Possible verification signals include:
- Watermark detection
- C2PA-style manifest detection
- Royalty OS C2PA Extension detection
- Soft binding resolution
- Retrieval log confirmation
- Fragment hash comparison
- Semantic similarity analysis
- Structure similarity analysis
- Outlier origin detection
- Manual review
- Third-party attestation
The goal is not perfect certainty.
The goal is structured, reviewable evidence.
The high-level flow is:
Content with Royalty OS metadata
↓
AI retrieval or reference
↓
Royalty Trace Event
↓
Verification
↓
Attribution scoring
↓
Allocation readiness status
↓
Allocation Trigger
↓
Human or multi-party review
↓
Allocation Layer
A simplified version:
Evidence first.
Review second.
Distribution third.
This repository currently defines three core schemas.
schemas/royalty-trace-event-v3.0.schema.json
schemas/royalty-allocation-trigger-v3.0.schema.json
schemas/royalty-c2pa-extension-v3.0.schema.json
A Royalty Trace Event records one meaningful instance of AI usage.
It may describe:
- Direct quote
- Factual grounding
- Concept reference
- Structural influence
- Style reference
- Summary
- Translation
- Paraphrase
- Training signal
- Evaluation reference
- note/RAG-style reference experiment
Schema:
schemas/royalty-trace-event-v3.0.schema.json
A Royalty Allocation Trigger is generated when one or more Trace Events become strong enough to justify downstream allocation review.
It does not execute payment.
It says:
These trace events may deserve allocation review.
Schema:
schemas/royalty-allocation-trigger-v3.0.schema.json
A Royalty C2PA Extension defines lightweight Royalty OS metadata fields that may complement C2PA-style provenance records.
It does not replace C2PA.
It adds machine-readable signals such as:
- Royalty OS content ID
- Permission scope
- Preferred usage
- Attribution request
- Trace priority
- Trace policy
- Evidence references
- Allocation trigger permission flags
Schema:
schemas/royalty-c2pa-extension-v3.0.schema.json
{
"schema_version": "3.0",
"trace_id": "trace_2026_05_royalty_os_structural_0001",
"content_os_id": "royalty-os:jp:example:trace-layer-001",
"timestamp": "2026-05-27T10:30:00+09:00",
"actor": {
"ai_model_id": "example-rag-agent-v1",
"provider_id": "example-provider",
"deployment_context": "rag",
"system_role": "generator"
},
"retrieval": {
"retrieval_score": 0.92,
"retrieval_granularity": "structure",
"retrieval_method": "hybrid_search"
},
"usage": {
"usage_type": "structural_influence",
"citation_visible_to_user": false,
"human_visible_use": true
},
"permission": {
"permission_scope": "allow_reference",
"permission_status": "valid"
},
"verification": {
"watermark_detected": true,
"c2pa_manifest_detected": true,
"soft_binding_resolved": true,
"retrieval_log_confirmed": true,
"outlier_origin_detected": true,
"verification_confidence": 0.89
},
"attribution": {
"influence_estimate": 0.76,
"origin_score": 0.94,
"attribution_confidence": 0.82,
"allocation_readiness": "trigger_candidate",
"attribution_method": "hybrid"
}
}Trace events may be recorded at different levels of granularity.
token
sentence
paragraph
section
document
concept
structure
dataset
unknown
Direct quotation often occurs at sentence or paragraph level.
Conceptual influence may occur at concept level.
Structural influence may occur at structure level.
This allows the Trace Layer to record both visible and non-visible forms of AI usage.
The current schema supports the following usage types:
direct_quote
factual_grounding
concept_reference
structural_influence
style_reference
summary
translation
paraphrase
training_signal
evaluation_reference
other
This distinction is important because AI systems do not only quote text.
They may also reuse:
- Concepts
- Frameworks
- Classifications
- Structural patterns
- Original terminology
- Reasoning architectures
Royalty OS v3.0 is especially concerned with concept-level and structure-level traces.
Outlier Origin Detection is one of the distinctive features of Royalty OS Trace Layer v3.0.
It identifies unusually original concepts, structures, or frameworks that may function as origin points for later AI-generated outputs.
Examples include:
- Newly coined terms
- Original theoretical structures
- Unique combinations of fields
- High-density conceptual architectures
- Rare structural patterns
Outlier detection does not automatically prove ownership.
It marks the trace as high-priority evidence.
Outlier detection = high-priority evidence
Outlier detection ≠ final ownership proof
See:
docs/outlier-origin-detection.md
This repository includes an experimental note/RAG workflow.
The experiment explores whether a public article with machine-readable metadata can be represented as a traceable AI reference event.
The minimal flow is:
note-style article
↓
Royalty OS Metadata block
↓
RAG retrieval or AI reference
↓
Royalty Trace Event
↓
Allocation Trigger candidate
This is not a claim that note or any external platform currently implements this specification.
It is a social proof and prototyping model for AI-era traceability.
Relevant files:
docs/note-rag-experiment-notes.md
examples/trace-event.note-rag-reference.example.json
Example metadata block:
Royalty OS Metadata:
os_id: "royalty-os:jp:samuraiwriter7:example-article-001"
title: "Example Article Title"
author_id: "royalty-os:creator:jp:samuraiwriter7"
permission_scope: "allow_reference"
preferred_usage:
- concept_reference
- structural_influence
- factual_grounding
attribution_request: "cite_origin_when_possible"
trace_priority: "high"
version: "1.0"
related_repository: "SamuraiWriter7/royalty-os-trace-layer-v3.0"The purpose is to show that AI reference activity can be:
visible
structured
privacy-aware
reviewable
allocation-ready
This repository includes a lightweight Royalty OS C2PA Extension schema.
The extension is designed to complement C2PA-style provenance records.
It does not replace C2PA.
The relationship is:
C2PA-style provenance = where the content came from
Royalty OS Trace = how AI used the content
Relevant files:
docs/relationship-to-c2pa.md
schemas/royalty-c2pa-extension-v3.0.schema.json
examples/royalty-c2pa-extension.example.json
The C2PA Extension may include:
royalty.os_idroyalty.permission_scoperoyalty.preferred_usageroyalty.attribution_requestroyalty.trace_prioritytrace_policy.trace_enabledtrace_policy.outlier_origin_trackingtrace_policy.allocation_trigger_allowedtrace_policy.review_required_before_allocation
Example:
{
"schema_version": "3.0",
"extension_type": "royalty_os_c2pa_extension",
"royalty": {
"os_id": "royalty-os:jp:samuraiwriter7:royalty-os-trace-layer-v3.0",
"permission_scope": "allow_reference",
"preferred_usage": [
"concept_reference",
"structural_influence",
"factual_grounding"
],
"attribution_request": "cite_origin_when_possible",
"trace_priority": "high"
},
"trace_policy": {
"trace_enabled": true,
"trace_granularity": [
"concept",
"structure",
"document"
],
"outlier_origin_tracking": true,
"allocation_trigger_allowed": true,
"review_required_before_allocation": true,
"privacy_mode": "hash_only"
}
}The purpose is to connect content provenance to AI usage traceability.
This repository includes a higher-level Civilization OS architecture document.
It explains where Trace Layer v3.0 sits in the broader flow from human origin to evidence, allocation, and value circulation.
Relevant file:
docs/civilization-os-architecture.md
The broader flow is:
Origin
↓
Structure
↓
Permission
↓
Trace
↓
Allocation
↓
Civilization Circulation
This document clarifies that Royalty OS Trace Layer v3.0 is not the entire Civilization OS.
It is the evidence layer that makes Civilization OS technically discussable.
The Trace Layer does not distribute value directly.
Instead, it assigns an allocation_readiness status.
not_ready
review_required
trigger_candidate
ready
Meaning:
| Status | Meaning |
|---|---|
not_ready |
Evidence is weak, incomplete, or unsuitable |
review_required |
Human or multi-party review is needed |
trigger_candidate |
The trace may justify an allocation trigger |
ready |
The trace is structured enough for downstream allocation processing |
The Allocation Layer should treat these values as signals, not final commands.
An Allocation Trigger is the bridge between Trace evidence and Allocation review.
Example:
{
"schema_version": "3.0",
"trigger_id": "allocation_trigger_2026_05_royalty_os_0001",
"trigger_type": "aggregated_trace_events",
"source_trace_events": [
{
"trace_id": "trace_2026_05_royalty_os_structural_0001",
"content_os_id": "royalty-os:jp:example:trace-layer-001",
"usage_type": "structural_influence",
"allocation_readiness": "trigger_candidate",
"influence_estimate": 0.76,
"origin_score": 0.94,
"verification_confidence": 0.89
}
],
"allocation_candidate": {
"candidate_id": "allocation_candidate_2026_05_royalty_os_0001",
"recipient_os_id": "royalty-os:creator:jp:example",
"content_os_id": "royalty-os:jp:example:trace-layer-001",
"allocation_basis": "structural_influence",
"candidate_score": 0.91,
"recommended_action": "request_review",
"suggested_allocation_band": "medium"
}
}The trigger does not execute payment.
It signals that review may be justified.
royalty-os-trace-layer-v3.0/
README.md
LICENSE
CITATION.cff
CHANGELOG.md
schemas/
royalty-trace-event-v3.0.schema.json
royalty-allocation-trigger-v3.0.schema.json
royalty-c2pa-extension-v3.0.schema.json
examples/
trace-event.structural-influence.example.json
trace-event.concept-reference.example.json
trace-event.direct-quote.example.json
trace-event.outlier-origin.example.json
trace-event.note-rag-reference.example.json
allocation-trigger.example.json
royalty-c2pa-extension.example.json
docs/
architecture-overview.md
civilization-os-architecture.md
relationship-to-allocation-layer.md
relationship-to-c2pa.md
outlier-origin-detection.md
privacy-and-compliance-notes.md
note-rag-experiment-notes.md
.github/
workflows/
validate-schemas.yml
Recommended reading order:
README.mddocs/architecture-overview.mddocs/civilization-os-architecture.mdschemas/royalty-trace-event-v3.0.schema.jsonexamples/trace-event.structural-influence.example.jsonexamples/trace-event.concept-reference.example.jsonexamples/trace-event.direct-quote.example.jsonexamples/trace-event.outlier-origin.example.jsondocs/note-rag-experiment-notes.mdexamples/trace-event.note-rag-reference.example.jsonschemas/royalty-allocation-trigger-v3.0.schema.jsonexamples/allocation-trigger.example.jsondocs/relationship-to-allocation-layer.mddocs/relationship-to-c2pa.mdschemas/royalty-c2pa-extension-v3.0.schema.jsonexamples/royalty-c2pa-extension.example.jsondocs/outlier-origin-detection.mddocs/privacy-and-compliance-notes.md
| Document | Purpose |
|---|---|
docs/architecture-overview.md |
Explains the full Trace Layer architecture |
docs/civilization-os-architecture.md |
Places Trace Layer v3.0 inside the broader Civilization OS stack |
docs/relationship-to-allocation-layer.md |
Explains how Trace connects to Allocation without directly distributing value |
docs/relationship-to-c2pa.md |
Explains how Royalty OS Trace complements C2PA-style provenance |
docs/outlier-origin-detection.md |
Defines the v3.0 origin-detection concept |
docs/privacy-and-compliance-notes.md |
Provides privacy and compliance design notes |
docs/note-rag-experiment-notes.md |
Describes an experimental note/RAG workflow for social proof and trace validation |
| Example | Purpose |
|---|---|
trace-event.structural-influence.example.json |
AI reuses a framework, architecture, or structural pattern |
trace-event.concept-reference.example.json |
AI references an original concept or coined term |
trace-event.direct-quote.example.json |
AI directly quotes a registered source fragment |
trace-event.outlier-origin.example.json |
AI references a statistically distinctive origin signal |
trace-event.note-rag-reference.example.json |
A note-style article is retrieved in a RAG-like environment and traced as a concept or structure reference |
allocation-trigger.example.json |
Trace events are converted into an allocation-review candidate |
royalty-c2pa-extension.example.json |
Royalty OS metadata complements a C2PA-style provenance record |
This repository includes a GitHub Actions workflow for schema validation.
.github/workflows/validate-schemas.yml
The workflow validates:
schemas/royalty-trace-event-v3.0.schema.json
├─ examples/trace-event.structural-influence.example.json
├─ examples/trace-event.concept-reference.example.json
├─ examples/trace-event.direct-quote.example.json
├─ examples/trace-event.outlier-origin.example.json
└─ examples/trace-event.note-rag-reference.example.json
schemas/royalty-allocation-trigger-v3.0.schema.json
└─ examples/allocation-trigger.example.json
schemas/royalty-c2pa-extension-v3.0.schema.json
└─ examples/royalty-c2pa-extension.example.json
Local validation can be performed with Python and jsonschema.
python -m pip install jsonschemaThe GitHub Actions workflow contains the validation script directly.
Royalty OS Trace Layer v3.0 should be privacy-aware by design.
Recommended defaults:
{
"user_prompt_stored": false,
"user_identity_stored": false,
"anonymized_session": true,
"raw_content_stored": false,
"privacy_mode": "hash_only"
}The design principle is:
Make AI usage traceable without making people traceable.
The Trace Layer should record content usage evidence without becoming a surveillance layer.
See:
docs/privacy-and-compliance-notes.md
RAG systems are one of the most important target environments for this specification.
In a RAG workflow, an AI system retrieves documents or fragments before producing an answer.
Royalty OS Trace Layer v3.0 records that retrieval as a traceable event.
Example:
User asks a question
↓
RAG system retrieves source content
↓
Model generates answer
↓
Trace event records source, usage, permission, and influence
This makes AI reference activity visible and auditable.
The note/RAG experiment is a lightweight social proof model for this direction.
See:
docs/note-rag-experiment-notes.md
Royalty OS Trace Layer v3.0 can work with provenance metadata systems.
C2PA-style manifests may provide:
- Content identity
- Creator or publisher metadata
- Edit history
- Manifest references
- Asset provenance
- External binding records
Royalty OS extends this idea toward AI usage traceability.
C2PA-style provenance and Royalty OS Trace are related but not identical:
C2PA-style provenance = where the content came from
Royalty OS Trace = how AI used the content
The Royalty C2PA Extension is a lightweight bridge between these layers.
See:
docs/relationship-to-c2pa.md
schemas/royalty-c2pa-extension-v3.0.schema.json
examples/royalty-c2pa-extension.example.json
Royalty OS Trace Layer v3.0 is one component of a broader Civilization OS architecture.
In that broader model:
Provenance identifies.
Permission allows.
Trace records.
Review judges.
Allocation distributes.
Civilization remembers.
This repository focuses on Trace Layer v3.0 and its immediate bridges.
It does not attempt to implement the full Civilization OS.
See:
docs/civilization-os-architecture.md
Watermarking may help verify whether content was generated, transformed, or derived from a known source.
However, watermarking alone is not sufficient.
Royalty OS Trace Layer v3.0 uses multi-signal verification.
Watermark
+ Manifest
+ Retrieval Log
+ Fragment Hash
+ Semantic Similarity
+ Outlier Detection
= Stronger Trace Evidence
This avoids overdependence on a single fragile signal.
Trace events and allocation triggers may be disputed.
Possible reasons include:
- Similar independent origins
- Prior art
- Incorrect permission status
- False positive similarity
- Incomplete retrieval logs
- Weak attribution confidence
- Multiple competing claims
- Misidentified recipient
For this reason, the architecture assumes review before final allocation.
The Trace Layer preserves evidence. The Allocation Layer and review systems decide how that evidence should be handled.
Status: Draft
Specification version: Royalty OS Trace Layer v3.0
Repository release stage: v0.1.3 candidate
This repository is experimental and intended for specification design, prototyping, and interoperability discussion.
It should not be treated as:
- Legal advice
- A final technical standard
- A complete implementation
- A payment system
- A copyright enforcement system
- A replacement for C2PA
- A claim of external platform adoption
- A complete Civilization OS implementation
Possible future schemas:
schemas/royalty-attribution-score-v3.0.schema.json
schemas/evidence-bundle-v3.0.schema.json
schemas/trace-receipt-v3.0.schema.json
Possible future examples:
examples/trace-event.factual-grounding.example.json
examples/trace-event.summary.example.json
examples/trace-event.training-signal.example.json
examples/allocation-trigger.direct-quote.example.json
examples/allocation-trigger.aggregated-usage.example.json
examples/allocation-trigger.note-rag.example.json
Possible future documents:
docs/implementation-roadmap.md
docs/embedding-layer.md
docs/logging-layer.md
docs/verification-layer.md
docs/relationship-to-rag-ecosystem.md
docs/relationship-to-rsl.md
docs/evidence-bundle-model.md
docs/trace-receipt-model.md
docs/review-gate-model.md
docs/dispute-and-review-flow.md
docs/note-metadata-block-template.md
docs/note-rag-experiment-report-template.md
docs/c2pa-extension-implementation-notes.md
Possible implementation components:
- RAG trace adapter
- Trace receipt generator
- Allocation trigger generator
- Evidence bundle builder
- Provider-side trace reporter
- Dashboard data model
- Privacy-preserving proof format
- Multi-provider trace aggregation prototype
- note/RAG experiment report generator
- C2PA-style metadata adapter
- Civilization OS architecture map
Royalty OS Trace Layer v3.0 follows this principle:
No allocation without trace.
No trace without permission.
No permission without machine-readable structure.
AI systems increasingly retrieve, summarize, transform, and recombine human knowledge.
The purpose of this repository is to define a minimal but extensible structure for recording that process.
Not every AI reference should become a payment event. Not every influence claim should be accepted automatically. But meaningful usage should not disappear without evidence.
The Trace Layer exists to preserve that evidence.
This repository is released under the MIT License.
See:
LICENSE
If you use or reference this specification, please cite this repository.
See:
CITATION.cff
Adds Civilization OS architecture mapping.
Includes:
docs/civilization-os-architecture.md- Updated README sections for Civilization OS Context, Design Goals, Civilization OS Architecture, Repository Structure, Start Here, Key Documents, Relationship to Civilization OS, Current Status, and Future Extensions
Adds C2PA Extension support.
Includes:
docs/relationship-to-c2pa.mdschemas/royalty-c2pa-extension-v3.0.schema.jsonexamples/royalty-c2pa-extension.example.json- Updated schema validation workflow to include the C2PA Extension schema and example
- Updated README sections for Core Schemas, C2PA Extension, Repository Structure, Start Here, Key Documents, Examples, validation targets, C2PA relationship, and Future Extensions
Adds the note/RAG experiment line.
Includes:
docs/note-rag-experiment-notes.mdexamples/trace-event.note-rag-reference.example.json- Updated schema validation workflow to include the note/RAG trace example
- Updated README sections for Repository Structure, Start Here, Key Documents, Examples, and validation targets
Initial repository structure for Royalty OS Trace Layer v3.0.
Includes:
- Royalty Trace Event schema
- Royalty Allocation Trigger schema
- Structural influence trace example
- Concept reference trace example
- Direct quote trace example
- Outlier origin trace example
- Allocation trigger example
- Architecture overview
- Relationship to Allocation Layer notes
- Outlier Origin Detection notes
- Privacy and Compliance notes
- GitHub Actions schema validation workflow