{
  "markdown": "# 🐍 spec-objects-safety\n\n> Filament Module: safety ObjectTypes (hazard, failure_mode) — IEC 61508 / ISO 26262 / FMEA\n\n---\n\n## 🧭 What this module ships\n\nThe package root **is** the Filament module. `spec_objects_safety/manifest.yaml`\ndeclares two object types — `hazard` (a system state that can lead to harm) and\n`failure_mode` (the manner in which a component fails) — with their body\ncontracts, their authoring skeletons, the domain lexicon, and the\n`traceability` model that reports a hazard nothing mitigates.\n\nSince 0.3.0 it is a **semantic module** (quoin FR-070): the archetypes are\nauthored in `typespec/main.tsp` against `@agent-ix/semantic-core`, emitted to\nJSON Schema 2020-12 under `spec_objects_safety/schemas/`, and referenced from\nthe manifest by path and digest.\n\nThe rule those schemas exist to enforce: every scored axis — severity,\nlikelihood, ISO 26262 exposure and controllability, FMEA detection — admits\neither its own ordinal scale **or** one of `unknown`, `not_assessed`,\n`not_applicable`. Those three share no member with any scale, so an axis nobody\nlooked at can never be read, sorted or scored as a safe one. Nothing here\ndefaults a safety judgement, and `status: accepted` requires a `provenance`\nnaming who accepted the risk and when.\n\n### Working on the schemas\n\n```bash\nmake schemas        # re-emit spec_objects_safety/schemas/ from typespec/main.tsp\nmake schemas-check  # fail on schema or digest drift (also run by `make lint`)\nmake dev-quire      # install the Quire wheel the semantic tests need\n```\n\n`make schemas` needs `npm ci` first and a user-level npm config that routes\n`@agent-ix` to npm.ix; the repository carries no `.npmrc`. A wrong schema is\nfixed in `typespec/main.tsp` and regenerated — never hand-edited.\n\n`make dev-quire` exists because the Quire build exposing `extract_semantic` is\non no index this repository may commit a dependency against\n(`agent-ix/quire-rs#392`). Without it the semantic tests **fail**; they never\nskip, because a skipped row is not coverage.\n\n---\n\n## 📐 Project Structure and Development Philosophy\n\n- **Library Name:** `spec_objects_safety`\n- **Layout:** Flat project layout (package at root, no `src/`)\n- **Language:** Python 3.13+\n- **Dependency Management:** [Poetry](https://python-poetry.org/)\n- **Build and CI:** GitHub Actions\n- **Publishing:** Google Artifact Registry (PyPI-compatible)\n\n---\n\n## 🛠 Prerequisites\n\n- **Python 3.13+** installed on your system\n- **Poetry 2.x** installed (`pip install poetry` or [official installer](https://python-poetry.org/docs/#installation))\n- **devpi-client** (optional, for local publishing): `pip install devpi-client`\n\n---\n\n## 🚀 Quick Start\n\n```bash\n# Install dependencies and create venv\nmake install\n\n# Run tests\nmake test\n\n# Format code\nmake format\n\n# Lint code\nmake lint\n\n# Build distribution\nmake build\n```\n\n---\n\n## 📦 Build Process\n\n- **Local Development**:\n  - `make install` - Install dependencies in Poetry venv\n  - `make test` - Run tests\n  - `make format` - Auto-format code (Black + Ruff)\n  - `make lint` - Run linting checks\n- **Artifact Building**:\n  - `make build` - Build wheel and sdist under `dist/`\n- **Artifact Upload**:\n  - Artifacts uploaded via `twine upload` in CI\n\n---\n\n## 🚀 Continuous Integration (CI)\n\n- **GitHub Actions Workflow**:\n  - Triggers: `push`, `pull_request`, `tag v*.*.*`\n  - Runs tests and lint checks\n  - Builds artifacts with `poetry build`\n  - Publishes to Google Artifact Registry using `twine upload -r internal-pypi`\n\n---\n\n## 🔑 Required GitHub Secrets\n\n| Secret Name | Purpose |\n|:------------|:--------|\n| `GCP_SERVICE_ACCOUNT_KEY` | Raw JSON of GCP Service Account Key |\n\n| Variable Name | Purpose |\n|:------------|:--------|\n| `GCP_REGION` | GCP Region for Artifact Registry (e.g., `us-west1`) |\n| `GCP_PROJECT_NAME` | GCP Project ID (e.g., `agent-ix`) |\n| `GCP_PYPI` | Artifact Registry repository name (e.g., `internal-pypi`) |\n\n---\n\n## 🐳 Makefile Targets\n\n| Target | Description |\n|:-------|:------------|\n| `install` | Install dependencies in Poetry venv |\n| `build` | Build wheel and sdist artifacts |\n| `test` | Run tests |\n| `lint` | Run linting (Ruff + Black check + schema drift gate) |\n| `schemas` | Re-emit `spec_objects_safety/schemas/` from `typespec/main.tsp` |\n| `schemas-check` | Fail on schema or manifest-digest drift |\n| `dev-quire` | Install the Quire wheel the semantic tests need |\n| `format` | Auto-format code (Black + Ruff --fix) |\n| `shell` | Open Poetry shell |\n| `clean` | Remove all build artifacts |\n| `version` | Show project version |\n| `info` | Show Git and version info |\n| `update-lock` | Update poetry.lock |\n| `update-packages` | Update all dependencies |\n| `add-package p=<name>` | Add a production dependency |\n| `add-dev-package p=<name>` | Add a dev dependency |\n| `local-publish` | Build and publish to local PyPI |\n\n---\n\n## 🏠 Local Development with Local PyPI\n\nFor local development and testing, you can publish packages to the local PyPI proxy.\n\n### Prerequisites\n\n1. **Local Kubernetes cluster** running with PyPI proxy:\n   ```bash\n   # In the local repo\n   make up\n   make pypi-up\n   ```\n\n2. **devpi-client** installed locally:\n   ```bash\n   pip install devpi-client\n   ```\n\n### Publishing Locally\n\n```bash\nmake local-publish\n```\n\n### Installing from Local PyPI\n\n```bash\npip install --index-url http://pypi.ix/root/dev/+simple/ spec_objects_safety\n```\n\n---\n\n## 📜 Design Philosophy\n\n- Native Poetry-based development (no Docker required for development)\n- Isolated Poetry virtualenv (no global pip pollution)\n- Direct uploads to Artifact Registry using correct PyPI-style authentication\n- Always source-driven — no hand-editing built artifacts\n- Dynamic, Git-tag-based versioning\n- Clear Makefile and CI workflows matching production standards\n\n---\n",
  "bytes": 5779,
  "sha": "b45a13a200403e0ffd4e74a428d66975481142629ac849e7f1a955b5a3330a19",
  "repo_slug": "agent-ix/spec-objects-safety",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/okf_agent_ix_spec_objects_safety_spec_index__be0f09a3/readme"
}