{"id":50665774,"url":"https://github.com/samuraiwriter7/royalty-pool-formula","last_synced_at":"2026-06-08T06:05:22.238Z","repository":{"id":351474746,"uuid":"1211030602","full_name":"SamuraiWriter7/royalty-pool-formula","owner":"SamuraiWriter7","description":"Machine-readable specification for permission-aware trace-based royalty allocation, with ARA, cultural lineage mapping, and audit-ready trace ledger architecture.","archived":false,"fork":false,"pushed_at":"2026-04-15T06:32:41.000Z","size":63,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-15T07:31:07.376Z","etag":null,"topics":["json-schema","machine-readable","royalty-formula","royalty-os","trace-based-allocation","yaml-spec"],"latest_commit_sha":null,"homepage":"","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SamuraiWriter7.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-15T02:09:34.000Z","updated_at":"2026-04-15T06:41:14.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/SamuraiWriter7/royalty-pool-formula","commit_stats":null,"previous_names":["samuraiwriter7/royalty-pool-formula"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/SamuraiWriter7/royalty-pool-formula","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SamuraiWriter7%2Froyalty-pool-formula","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SamuraiWriter7%2Froyalty-pool-formula/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SamuraiWriter7%2Froyalty-pool-formula/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SamuraiWriter7%2Froyalty-pool-formula/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SamuraiWriter7","download_url":"https://codeload.github.com/SamuraiWriter7/royalty-pool-formula/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SamuraiWriter7%2Froyalty-pool-formula/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34050258,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-08T02:00:07.615Z","response_time":111,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["json-schema","machine-readable","royalty-formula","royalty-os","trace-based-allocation","yaml-spec"],"created_at":"2026-06-08T06:04:49.690Z","updated_at":"2026-06-08T06:05:22.233Z","avatar_url":"https://github.com/SamuraiWriter7.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# Royalty Pool Formula v0.1\n\nMachine-readable specification for royalty allocation from permission-aware trace events.  \nBuilt with JSON Schema, YAML examples, and GitHub Actions validation.  \nDesigned for auditable permission → trace → resonance → allocation workflows.\n\n---\n\n## Overview\n\n`Royalty Pool Formula v0.1` is a machine-readable foundation for **trace-based royalty allocation**.\n\nThis repository defines how value can be:\n\n- specified\n- calculated\n- explained\n- visualized\n- recorded\n\nThe core flow is:\n\n**permission → trace → resonance → allocation → recirculation → audit**\n\nThe goal is not to reward raw activity, but to define how value can flow back through **permitted**, **traceable**, and **auditable** contribution structures.\n\nFor a compact architectural summary, see [`docs/one-page-overview.md`](docs/one-page-overview.md).\n\n---\n\n## Core Flow\n\nThis repository is organized around the following logic:\n\n1. **Permission**  \n   Confirm whether a use is permitted, restricted, or prohibited.\n\n2. **Trace**  \n   Record relevant trace-linked events in a structured form.\n\n3. **Resonance**  \n   Compute contribution scores from similarity, confidence, decay, and policy-aware factors.\n\n4. **Allocation**  \n   Normalize contribution scores into proportional royalty shares.\n\n5. **Recirculation**  \n   Optionally return part of downstream value to upstream structures or origins.\n\n6. **Audit**  \n   Record committed outputs in an append-only, tamper-evident form.\n\n---\n\n## Repository Structure\n\n```text\n.\n├─ README.md\n├─ LICENSE\n├─ CITATION.cff\n├─ docs/\n│  └─ one-page-overview.md\n├─ schema/\n│  └─ royalty-pool-formula-v0.1.schema.json\n├─ examples/\n│  └─ royalty-pool-formula-v0.1.sample.yaml\n├─ spec/\n│  ├─ trace-vector-profile-v0.1.yaml\n│  ├─ ara-engine-v0.1.yaml\n│  ├─ cultural-lineage-map-v0.1.yaml\n│  └─ trace-ledger-architecture-v0.1.yaml\n└─ .github/\n   └─ workflows/\n      └─ validate-specs.yml\n\n## Start Here\n\nThis repository can be read from two directions:\n\n- **from formula to system**\n- **from system to audit**\n\nFor most readers, the recommended reading order is:\n\n### 1. Read this README\nStart with the overview, repository structure, and design principles to understand the scope of the repository.\n\n### 2. Open the sample file\nRead:\n\n- `examples/royalty-pool-formula-v0.1.sample.yaml`\n\nThis is the fastest way to understand the intended document shape.\n\n### 3. Check the validation schema\nOpen:\n\n- `schema/royalty-pool-formula-v0.1.schema.json`\n\nThis defines the machine-readable contract for the formula document.\n\n### 4. Read the trace representation layer\nOpen:\n\n- `spec/trace-vector-profile-v0.1.yaml`\n\nThis defines how traces are represented as a stable multi-vector profile across:\n\n- behavior\n- semantic\n- structural\n\nIt is the bridge between trace capture and ARA scoring.\n\n### 5. Read the execution layer\nOpen:\n\n- `spec/ara-engine-v0.1.yaml`\n\nThis shows how the system computes:\n\n- scoring\n- allocation\n- hold decisions\n- recirculation\n- explanation\n- ledger events\n\n### 6. Read the visualization layer\nOpen:\n\n- `spec/cultural-lineage-map-v0.1.yaml`\n\nThis shows how lineage, structure reuse, and value flow are visualized.\n\n### 7. Read the audit layer\nOpen:\n\n- `spec/trace-ledger-architecture-v0.1.yaml`\n\nThis shows how committed outputs are stored in an append-only, tamper-evident form.\n\n### 8. Read the one-page summary\nOpen:\n\n- `docs/one-page-overview.md`\n\nThis gives a compact architectural summary.\n\n### 9. Run validation locally\nUse the schema validation command described below to confirm that the example passes.\n\n### 10. Review CI behavior\nOpen:\n\n- `.github/workflows/validate-specs.yml`\n\nThis shows how validation is enforced automatically.\n\n### Recommended reading paths\n\n#### For specification readers\nREADME → sample YAML → schema JSON → trace vector profile → ARA spec\n\n#### For architecture readers\nREADME → trace vector profile → ARA spec → lineage map spec → ledger spec\n\n#### For audit / governance readers\nREADME → ledger spec → lineage map spec → license\n\n### In one sentence\n\nThis repository defines how trace-aware royalty allocation can be **specified, vectorized, executed, visualized, and audited**.\n\nDirectory overview\ndocs/\n\nCompact high-level documentation.\n\none-page-overview.md\nA one-page architectural summary of the repository.\nschema/\n\nMachine-readable validation schemas.\n\nroyalty-pool-formula-v0.1.schema.json\nJSON Schema for validating the Royalty Pool Formula document structure.\nexamples/\n\nHuman-readable sample specifications.\n\nroyalty-pool-formula-v0.1.sample.yaml\nA minimal sample document conforming to the schema.\nspec/\n\nCore human-readable specifications for execution, visualization, and audit.\n\nara-engine-v0.1.yaml\nAutonomous Royalty Allocator engine specification\ncultural-lineage-map-v0.1.yaml\nCultural lineage visualization and graph structure specification\ntrace-ledger-architecture-v0.1.yaml\nTrace ledger architecture for auditability, replayability, and tamper-evident history\n.github/workflows/\n\nContinuous Integration workflows.\n\nvalidate-specs.yml\nAutomatically validates the schema and example files on push and pull request.\nStart Here\n\nThis repository can be read from two directions:\n\nfrom formula to system\nfrom system to audit\n\nFor most readers, the recommended reading order is:\n\n1. Read this README\n\nStart with the overview, repository structure, and design principles to understand the scope of the repository.\n\n2. Open the sample file\n\nRead:\n\nexamples/royalty-pool-formula-v0.1.sample.yaml\n\nThis is the fastest way to understand the intended document shape.\n\n3. Check the validation schema\n\nOpen:\n\nschema/royalty-pool-formula-v0.1.schema.json\n\nThis defines the machine-readable contract for the formula document.\n\n4. Read the three core specifications\n\nOpen these in order:\n\nspec/ara-engine-v0.1.yaml\nspec/cultural-lineage-map-v0.1.yaml\nspec/trace-ledger-architecture-v0.1.yaml\n\nThis sequence shows how the system works:\n\nARA computes allocation\nCultural Lineage Map visualizes lineage and value flow\nTrace Ledger Architecture records committed results for auditability\n5. Read the one-page summary\n\nOpen:\n\ndocs/one-page-overview.md\n\nThis gives a compact architectural summary.\n\n6. Run validation locally\n\nUse the schema validation command described below to confirm that the example passes.\n\n7. Review CI behavior\n\nOpen:\n\n.github/workflows/validate-specs.yml\n\nThis shows how validation is enforced automatically.\n\nRecommended reading paths\nFor specification readers\n\nREADME → sample YAML → schema JSON → ARA spec\n\nFor architecture readers\n\nREADME → ARA spec → lineage map spec → ledger spec\n\nFor audit / governance readers\n\nREADME → ledger spec → lineage map spec → license\n\nIn one sentence\n\nThis repository defines how trace-aware royalty allocation can be specified, executed, visualized, and audited.\n\nSpecification Set\n\nThis repository currently contains four major specification layers.\n\n1. Royalty Pool Formula\n\nDefines how a distributable royalty pool is calculated and proportionally allocated.\n\nMain role:\n\nturn contribution scores into normalized shares\npreserve permission, origin traceability, and agency attribution\nsupport internal accounting units such as QCoin\n\nKey files:\n\nschema/royalty-pool-formula-v0.1.schema.json\nexamples/royalty-pool-formula-v0.1.sample.yaml\n2. ARA Engine\n\nThe Autonomous Royalty Allocator is the execution engine.\n\nMain role:\n\nevaluate permission\ncompute multi-layer similarity\napply confidence, decay, and anomaly controls\ngenerate allocations, holds, and explanations\nemit commit-ready ledger events\n\nKey file:\n\nspec/ara-engine-v0.1.yaml\n3. Cultural Lineage Map\n\nA graph-based view of how questions, works, structures, traces, and allocations relate.\n\nMain role:\n\nshow lineage and derivation\nshow where value flowed\nshow what was recirculated upstream\nsupport reviewer understanding and dispute analysis\n\nKey file:\n\nspec/cultural-lineage-map-v0.1.yaml\n4. Trace Ledger Architecture\n\nThe audit layer that records committed outputs in an append-only, tamper-evident form.\n\nMain role:\n\nstore committed events\npreserve recalculation history\npreserve dispute history\nverify payload integrity and hash continuity\nseparate operational event flow from immutable audit records\n\nKey file:\n\nspec/trace-ledger-architecture-v0.1.yaml\nHow the pieces connect\nTrace Input\n   ↓\nRoyalty Pool Formula\n   ↓\nARA Engine\n   ├─→ Cultural Lineage Map\n   └─→ Trace Ledger Architecture\n\nOr more explicitly:\n\npermission\n   ↓\ntrace capture\n   ↓\nresonance scoring\n   ↓\nallocation\n   ↓\nrecirculation\n   ↓\naudit commit\nSchema Usage\n\nThis repository provides a machine-readable schema and a sample YAML document for the Royalty Pool Formula specification.\n\nFiles\nschema/royalty-pool-formula-v0.1.schema.json\nexamples/royalty-pool-formula-v0.1.sample.yaml\n.github/workflows/validate-specs.yml\nWhat this does\nschema/royalty-pool-formula-v0.1.schema.json\nJSON Schema that defines the document structure for Royalty Pool Formula v0.1\nexamples/royalty-pool-formula-v0.1.sample.yaml\nA minimal sample document expected to pass schema validation\n.github/workflows/validate-specs.yml\nGitHub Actions workflow that automatically validates the sample YAML\nLocal validation\n1. Install dependencies\npython -m pip install --upgrade pip\npython -m pip install jsonschema PyYAML\n2. Validate the sample YAML against the schema\npython - \u003c\u003c'PY'\nimport json\nimport yaml\nfrom jsonschema import Draft202012Validator\n\nschema_path = \"schema/royalty-pool-formula-v0.1.schema.json\"\nsample_path = \"examples/royalty-pool-formula-v0.1.sample.yaml\"\n\nwith open(schema_path, \"r\", encoding=\"utf-8\") as f:\n    schema = json.load(f)\n\nwith open(sample_path, \"r\", encoding=\"utf-8\") as f:\n    sample = yaml.safe_load(f)\n\nvalidator = Draft202012Validator(schema)\nerrors = sorted(validator.iter_errors(sample), key=lambda e: e.path)\n\nif errors:\n    for err in errors:\n        path = \".\".join(str(x) for x in err.path)\n        print(f\"[ERROR] path={path or '\u003croot\u003e'}\")\n        print(err.message)\n        print(\"-\" * 80)\n    raise SystemExit(1)\n\nprint(\"Validation passed: royalty-pool-formula-v0.1.sample.yaml\")\nPY\nExpected result\nValidation passed: royalty-pool-formula-v0.1.sample.yaml\nValidation scope\n\nThis schema validates the structural integrity of the specification, including:\n\ntop-level required sections\nvariable definition objects\nformula expression containers\nsimilarity weight defaults\npolicy rule structure\nextension blocks\nsample input/output structure\nNotes\nThe schema validates document structure, not mathematical correctness.\nFormula strings in expression fields are treated as human-readable symbolic expressions.\nYAML is used for readability, while JSON Schema is used for deterministic validation.\nThe GitHub Actions workflow runs the same validation logic automatically on push, pull request, and manual dispatch.\nDesign Layers\n\nThis repository is organized into four layers:\n\nFormula layer\nThe royalty calculation logic and structural validation rules\nExecution layer\nThe ARA engine that computes scores, allocations, holds, and recirculation\nVisualization layer\nThe Cultural Lineage Map that makes trace, structure, and value flow visible\nAudit layer\nThe Trace Ledger Architecture that records committed results in an append-only, tamper-evident form\nWhy this structure\n\nThis layout separates concerns clearly:\n\nschema/ defines formal validation\nexamples/ shows minimal valid usage\nspec/ defines the higher-level architecture\n.github/workflows/ enforces consistency in CI\n\nIt is designed to stay readable for humans while remaining extensible for machine-verifiable workflows.\n\nDesign Principles\n\nThis repository is based on the following principles:\n\nPermission first\nNo valid allocation without valid permission context.\nTrace before reward\nValue should not be allocated without trace-linked reasoning.\nOrigin traceability\nUpstream origins should remain visible.\nAgency attribution\nThe acting or represented subject should remain attributable.\nAuditability\nAllocation decisions should be reviewable, replayable, and tamper-evident.\nInternal accounting\nThe current scope uses internal accounting units rather than speculative tokenization.\nExtensibility\nFormula, engine, visualization, and ledger layers should remain versionable and replaceable.\nFormula Philosophy\n\nThis specification is not intended to be a generic engagement score.\n\nIt is designed to preserve:\n\npermission-aware use\ntrace-based allocation\norigin traceability\nagency attribution\nvalue recirculation\nauditability\ninternal accounting discipline\n\nIn other words, the aim is not merely to reward activity, but to formalize how value can flow back through permitted and traceable contribution structures.\n\nOne-Page Overview\n\nA compact summary is available here:\n\ndocs/one-page-overview.md\n\nThat document is recommended for readers who want:\n\na short architectural summary\nthe main flow in one page\na quick map of the repository\na faster entry point before reading each spec\nStatus\n\nCurrent status: Draft (v0.1.0)\n\nThis repository currently defines:\n\nmachine-readable formula structure\nhuman-readable execution architecture\nlineage visualization structure\nappend-only audit architecture\nvalidation workflow\ncitation metadata\na custom core-preservation license\n\nThis repository does not yet define:\n\nexternal payment rails\ntoken markets\npublic blockchain deployment\nlegal settlement enforcement\nproduction UI implementation\nRecommended Workflow\nEdit the schema in schema/\nUpdate or add examples in examples/\nUpdate core specs in spec/ if architecture changes\nRun local validation\nCommit changes\nConfirm GitHub Actions passes\nUpdate docs/one-page-overview.md when architectural scope changes\nFuture Expansion\n\nA natural future layout may look like this:\n\n.\n├─ docs/\n│  ├─ one-page-overview.md\n│  └─ architecture-notes.md\n├─ schema/\n│  ├─ royalty-pool-formula-v0.1.schema.json\n│  ├─ royalty-pool-formula-v0.2.schema.json\n│  └─ allocation-report-v0.1.schema.json\n├─ examples/\n│  ├─ royalty-pool-formula-v0.1.sample.yaml\n│  ├─ royalty-pool-formula-v0.1.sample.json\n│  ├─ allocation-report-v0.1.sample.yaml\n│  └─ ledger-event-v0.1.sample.yaml\n├─ spec/\n│  ├─ ara-engine-v0.1.yaml\n│  ├─ cultural-lineage-map-v0.1.yaml\n│  ├─ trace-ledger-architecture-v0.1.yaml\n│  └─ dispute-review-v0.1.yaml\n└─ .github/\n   └─ workflows/\n      └─ validate-specs.yml\n\nPotential future additions:\n\nsemantic version evolution\nJSON example support\nstricter schema constraints\nallocation report schemas\nledger event schemas\ndispute review specs\ngraph export specs\ninteroperability profiles\nsigned verification receipts\nLicense\n\nThis repository is distributed under the terms described in LICENSE-KAZENE-ROYALTY-CORE.\n\nPlease review the license carefully before reuse, modification, redistribution, or compatibility claims.\n\nIn short, the license is designed to allow reading, study, implementation, modification, and commercial use, while preserving the core requirements of:\n\norigin visibility\ntrace preservation\nagency attribution\ncompatibility honesty\nvalue recirculation capability\nCitation\n\nIf you use this specification, please cite it using the metadata in CITATION.cff\n.\n\nSuggested citation source:\n\nCITATION.cff\n\nThe repository includes citation metadata for:\n\ntitle\nabstract\nversion\nauthorship\nkeywords\nrepository URL\nContributing\n\nContributions may include:\n\nschema refinements\nadditional examples\nvalidation improvements\ndocumentation cleanup\narchitectural clarifications\nfuture version drafting\n\nWhen contributing:\n\npreserve structural clarity\npreserve version traceability\navoid silent breaking changes\nkeep examples and specs aligned\nupdate documentation when behavior changes\n\nA dedicated CONTRIBUTING.md can be added as the repository expands.\n\nStart Summary\n\nIf you only open three files, open these first:\n\nexamples/royalty-pool-formula-v0.1.sample.yaml\nspec/ara-engine-v0.1.yaml\nspec/trace-ledger-architecture-v0.1.yaml\n\nThat path gives the fastest understanding of:\n\nwhat the formula looks like\nhow allocation is executed\nhow committed results are recorded\nIn One Line\n\nThis repository describes how trace-aware value can be calculated, explained, visualized, and recorded.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsamuraiwriter7%2Froyalty-pool-formula","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsamuraiwriter7%2Froyalty-pool-formula","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsamuraiwriter7%2Froyalty-pool-formula/lists"}