diff --git a/.markdownlint.json b/.markdownlint.json new file mode 100644 index 0000000..b077f0e --- /dev/null +++ b/.markdownlint.json @@ -0,0 +1,4 @@ +{ + "default": true, + "MD013": false +} diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4e96c49..96b9dc8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,4 +1,4 @@ -## Contributing +# Contributing - Spec-first: changes that affect behavior must update spec/. - Keep SourceOS independent of socios by default. diff --git a/README.md b/README.md index d4d7b38..85da22b 100644 --- a/README.md +++ b/README.md @@ -3,3 +3,20 @@ Immutable, local-first OS substrate (workstation + edge) with verifiable policy and user-space isolation. **No community automation dependency.** + +## Topology position + +- **Role:** immutable OS substrate for workstation and edge lanes. +- **Connects to:** + - `SociOS-Linux/agentos-spine` — current Linux-side integration/workspace spine that assembles or routes adjacent layers around the substrate + - `SourceOS-Linux/sourceos-spec` — canonical typed contracts, JSON-LD contexts, and shared vocabulary for policy, assets, and events + - `SociOS-Linux/workstation-contracts` — workstation/CI contract and conformance lane + - `SociOS-Linux/socios` — opt-in automation commons, never a required dependency + - `SociOS-Linux/socioslinux-web` — Linux public web/docs surface that explains the substrate downstream + - Linux build and publish surfaces such as image/package lanes may realize this substrate, but this repo is the substrate rather than the builder +- **Not this repo:** + - opt-in automation commons + - workspace controller + - public docs site + - canonical typed-contract registry +- **Semantic direction:** this repo should eventually publish a substrate-focused repo descriptor that references the shared SourceOS/SociOS vocabulary from `sourceos-spec`. diff --git a/SECURITY.md b/SECURITY.md index 1ff8d74..5b3d8d4 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -1,4 +1,4 @@ -## Security +# Security Report vulnerabilities privately. diff --git a/caps/semantic-search-bi/docs/README.md b/caps/semantic-search-bi/docs/README.md index a41656c..df28305 100644 --- a/caps/semantic-search-bi/docs/README.md +++ b/caps/semantic-search-bi/docs/README.md @@ -4,20 +4,25 @@ Canonical upstream for this contract package now lives in `SocioProphet/sherlock This SourceOS copy is retained as a mirror/reference so local docs and tooling do not break, but changes should land upstream first. This package defines contracts for a semantic search capability: + - triRPC service surface (rpc/semantic.search.v0.yaml) - topic taxonomy for event bus integration (topics/*.yaml) - JSON Schemas for payload validation (schemas/*.json) - a local validator (tools/validate_package.py) ## Non-goals + This package does **not** ship any runtime implementation. Implementations live in separate packages and MUST: + 1) enforce a policy guard (default deny) 2) emit governance evidence events 3) speak triRPC for all method surfaces ## Optional backends + Implementations MAY provide: + - Lexical inverted index (e.g., Xapian) - Vector ANN index (e.g., FAISS/HNSW) - Symbolic graph store (e.g., AtomSpace) diff --git a/docs/BOUNDARIES.md b/docs/BOUNDARIES.md index 2b1ff7f..f572c9b 100644 --- a/docs/BOUNDARIES.md +++ b/docs/BOUNDARIES.md @@ -1,4 +1,4 @@ -## Boundaries +# Boundaries - SourceOS: OS + local policy/attestations. - socios: opt-in community automation layer (updates/CI/CD/training). diff --git a/docs/adr/0001-silverblue-toolbx-flatpak-podman.md b/docs/adr/0001-silverblue-toolbx-flatpak-podman.md index 4bdb0ca..434308c 100644 --- a/docs/adr/0001-silverblue-toolbx-flatpak-podman.md +++ b/docs/adr/0001-silverblue-toolbx-flatpak-podman.md @@ -3,15 +3,18 @@ Status: proposed Decision: + - Use Fedora Silverblue (GNOME) as workstation base. - Use Toolbx for dev environments. - Use Flatpak for GUI apps. - Use rootless Podman for services. Why: + - Immutable base reduces drift. - User-space isolation avoids breaking system environments (PEP 668-style issues). - Sandboxed GUI reduces app-level blast radius. Consequences: + - We must provide first-class tooling to make user-space ergonomics excellent. diff --git a/docs/compression-commons/v0/README.md b/docs/compression-commons/v0/README.md index 484b451..2ad6a12 100644 --- a/docs/compression-commons/v0/README.md +++ b/docs/compression-commons/v0/README.md @@ -1 +1,9 @@ -# Compression Commons (v0)\n\nUnifies:\n- Vanity Press Economy metrics (subsidy gradient, seigniorage, paper-mill equilibrium)\n- Lawful Learning constraints (projection to feasibility + replay evidence)\n- SourceOS enforcement (CapD + Triune RPC + policy guards + evidence ledger)\n\nThis module defines contracts first; reference implementations are optional.\n +# Compression Commons (v0) + +Unifies: + +- Vanity Press Economy metrics (subsidy gradient, seigniorage, paper-mill equilibrium) +- Lawful Learning constraints (projection to feasibility + replay evidence) +- SourceOS enforcement (CapD + Triune RPC + policy guards + evidence ledger) + +This module defines contracts first; reference implementations are optional. diff --git a/docs/semantic-search/README.md b/docs/semantic-search/README.md index f726be0..77ca8b5 100644 --- a/docs/semantic-search/README.md +++ b/docs/semantic-search/README.md @@ -7,18 +7,22 @@ When updating the semantic-search contract, update `sherlock-search` first and t This directory explains the **Semantic Search** capability contract in plain English. ## What this is + This package defines a **contract-only capability**: it specifies *interfaces* (schemas, RPC surface, topics, governance hooks), but **does not ship an implementation**. It’s like a “power outlet standard” — vendors can build compatible devices, but the contract itself isn’t the device. ## Why we do it this way + We want capabilities that are: + - **Composable**: other capabilities can depend on this one without importing a specific engine. - **Auditable**: every call can be policy-guarded and emits evidence events. - **Replaceable**: Xapian/FAISS/AtomSpace/etc. are optional implementations behind the same stable interface. - **Linux-first** and open-source-only. ## What’s in the contract package + The capability contract is defined by these folders: - `capd/` (if present): Capability descriptor (identity, version, requirements, compatibility rules). @@ -28,19 +32,24 @@ The capability contract is defined by these folders: - `tools/validate_package.py`: A local validator that ensures the contract package is structurally sane. ## Governance requirements (non-negotiable) + Every implementation of this contract MUST: + 1) Enforce **policy guards** (default deny) for ingest/query/delete. 2) Emit **evidence events** for every meaningful action (ingest accepted/rejected, query executed, results delivered, deletes). 3) Support **quota + identity hooks** (caller identity / tenant / namespace). 4) Be compatible with triRPC request/response schema validation. ## How to read the contract + Start at: + - `rpc/semantic.search.v0.yaml` — the canonical RPC surface - `schemas/query_request.schema.json` and `schemas/query_response.schema.json` - `schemas/evidence_event.schema.json` — what we log as auditable evidence - `topics/semantic.search.topics.v0.yaml` — pubsub surfaces ## “BI” naming note + If the folder is `caps/semantic-search-bi`, “bi” should mean *behavioral indexing* (or whatever we intended), not “business intelligence”. If that’s not what we mean, we should rename now while it’s early. diff --git a/docs/semantic-search/UPSTREAM.md b/docs/semantic-search/UPSTREAM.md index 879130a..26cfa7f 100644 --- a/docs/semantic-search/UPSTREAM.md +++ b/docs/semantic-search/UPSTREAM.md @@ -3,9 +3,11 @@ Canonical repository: `SocioProphet/sherlock-search` Canonical PR that moved ownership upstream: + - `SocioProphet/sherlock-search#1` Policy for updates: + 1. Change the contract in `sherlock-search` first. 2. Validate there. 3. Mirror here only if SourceOS needs a local reference copy. diff --git a/semantic/repo.jsonld b/semantic/repo.jsonld new file mode 100644 index 0000000..39e0948 --- /dev/null +++ b/semantic/repo.jsonld @@ -0,0 +1,27 @@ +{ + "@context": "https://raw.githubusercontent.com/SourceOS-Linux/sourceos-spec/main/semantic/context.jsonld", + "@id": "urn:sourceos:repo:SociOS-Linux:SourceOS", + "@type": ["RepoDescriptor", "Repository"], + "name": "SourceOS", + "description": "Immutable, local-first operating-system substrate for workstation and edge lanes.", + "repositoryFullName": "SociOS-Linux/SourceOS", + "repoUrl": "https://github.com/SociOS-Linux/SourceOS", + "organization": "SociOS-Linux", + "defaultBranch": "main", + "semanticDescriptorVersion": "0.1.0", + "topologyRole": "roleOSSubstrate", + "connectsTo": [ + "urn:sourceos:repo:SociOS-Linux:agentos-spine", + "urn:sourceos:repo:SourceOS-Linux:sourceos-spec", + "urn:sourceos:repo:SociOS-Linux:workstation-contracts", + "urn:sourceos:repo:SociOS-Linux:socios", + "urn:sourceos:repo:SociOS-Linux:socioslinux-web" + ], + "consumesVocabularyFrom": "urn:sourceos:repo:SourceOS-Linux:sourceos-spec", + "notThisRepo": [ + "opt-in automation commons", + "workspace controller", + "public docs site", + "canonical typed-contract registry" + ] +} diff --git a/spec/volumes/volumes.yml b/spec/volumes/volumes.yml index eeeb755..84216cb 100644 --- a/spec/volumes/volumes.yml +++ b/spec/volumes/volumes.yml @@ -1,10 +1,10 @@ volumes: Documents: {path: "~/Documents", policy: {snapshots: true, sync: off, backup: off}} Downloads: {path: "~/Downloads", policy: {noexec: true, snapshots: false, sync: off, backup: off}} - Desktop: {path: "~/Desktop", policy: {snapshots: true, sync: off, backup: off}} - Music: {path: "~/Music", policy: {snapshots: true, sync: off, backup: off}} - Videos: {path: "~/Videos", policy: {snapshots: true, sync: off, backup: off}} - Public: {path: "~/Public", policy: {snapshots: true, sync: off, backup: off}} - Pictures: {path: "~/Pictures", policy: {snapshots: true, sync: off, backup: off}} - Projects: {path: "~/Projects", policy: {snapshots: true, sync: off, backup: off}} - Secrets: {path: "~/Secrets", policy: {encrypted: true, sync: off, backup: off}} + Desktop: {path: "~/Desktop", policy: {snapshots: true, sync: off, backup: off}} + Music: {path: "~/Music", policy: {snapshots: true, sync: off, backup: off}} + Videos: {path: "~/Videos", policy: {snapshots: true, sync: off, backup: off}} + Public: {path: "~/Public", policy: {snapshots: true, sync: off, backup: off}} + Pictures: {path: "~/Pictures", policy: {snapshots: true, sync: off, backup: off}} + Projects: {path: "~/Projects", policy: {snapshots: true, sync: off, backup: off}} + Secrets: {path: "~/Secrets", policy: {encrypted: true, sync: off, backup: off}}