From a778214f0b109c44f20e75ddee017dd43531eca1 Mon Sep 17 00:00:00 2001 From: tegwick Date: Wed, 24 Jun 2026 15:30:55 +0200 Subject: [PATCH] feat(registry): add Integration Definition schema v0.1 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Define the open-reuse integration asset registry format with JSON Schema, authoring template, discovery index, and analyze→classify→refactor→maintain lifecycle documentation. Validates against the markitect-quarkdown reference integration. Closes OPEN-WP-0002. --- registry/README.md | 191 ++++++++++++- registry/indexes/integrations.yaml | 19 ++ registry/integrations/.gitkeep | 0 schemas/integration.schema.yaml | 261 ++++++++++++++++++ templates/integration-entry.template.yaml | 87 ++++++ ...OPEN-WP-0002-integration-asset-registry.md | 16 +- 6 files changed, 567 insertions(+), 7 deletions(-) create mode 100644 registry/indexes/integrations.yaml create mode 100644 registry/integrations/.gitkeep create mode 100644 schemas/integration.schema.yaml create mode 100644 templates/integration-entry.template.yaml diff --git a/registry/README.md b/registry/README.md index 569abe9..db7e717 100644 --- a/registry/README.md +++ b/registry/README.md @@ -1,12 +1,195 @@ -# Capability Registry +# open-reuse Registry -Markdown-first capability index for federation and reuse planning. +Markdown-first registry for managed open-source integration assets. -## Authoring +## Layout + +```text +registry/ +├── README.md +├── integrations/ # optional local definitions (most live in consuming repos) +├── capabilities/ # federation capability index (reuse-surface) +└── indexes/ + ├── integrations.yaml # integration discovery index + └── capabilities.yaml # capability federation index +schemas/ +└── integration.schema.yaml +templates/ +└── integration-entry.template.yaml +``` + +- **Integration definitions** are YAML files conforming to `schemas/integration.schema.yaml`. + They usually live in the consuming repository (e.g. `integration/.integration.yaml`). +- **Index** at `indexes/integrations.yaml` is the discovery surface for registered + integrations across the portfolio. +- **Template** at `templates/integration-entry.template.yaml` is the authoring + starting point for new definitions. +- **Capability index** at `indexes/capabilities.yaml` supports reuse-surface + federation; see [Capability Registry](#capability-registry) below. + +## Integration lifecycle loop + +open-reuse starts **after an integration has proven value**. The registry captures +the outcome of a structured loop that turns informal reuse into a managed asset. + +```text +Analyze → Classify → Refactor → Maintain +``` + +### 1. Analyze + +Understand the working integration before encoding it. + +| Question | Artifact | +| -------- | -------- | +| What upstream project is reused? | `upstream.name`, `upstream.project_url` | +| What local system depends on it? | `local.system`, `owner` | +| What surfaces are actually reused? | `boundary.reused_surface`, `boundary.contracts` | +| What runtime assumptions exist? | `runtime` | +| What breaks when upstream changes? | `risks.sensitivity`, `boundary.fragility_points` | +| How is correctness proven today? | `validation.harness`, `validation.checks` | + +**Output:** enough context to classify reuse mode and draw a defensible boundary. +Incomplete analysis is acceptable in `status: draft`; missing upstream or boundary +information blocks promotion to `registered`. + +### 2. Classify + +Assign an explicit reuse mode so risk, validation depth, and update policy can +be chosen systematically. + +| Reuse mode | Typical risk | Notes | +| ---------- | ------------ | ----- | +| `dependency` / `dependency-reuse` | Low | Package, library, image, or service consumption | +| `plugin` | Low–medium | Official extension points | +| `adapter` | Medium | Upstream wrapped behind a local interface | +| `component-extraction` | High | Selected internal parts reused | +| `patch-overlay` | High | Local patches on upstream | +| `fork-continuation` | Very high | Divergent fork, upstream-aware | +| `cli-boundary` | Medium | CLI invocation as the integration seam | + +Record classification in `reuse.primary_reuse_mode`, optional +`reuse.secondary_reuse_modes`, and `reuse.risk_level`. + +**Output:** `reuse` block with rationale. Unclassified integrations remain +incomplete until `primary_reuse_mode` is set. + +### 3. Refactor + +Establish a clear, testable boundary between local systems and upstream change. + +The `boundary` block documents the seam: + +- **Type** — adapter, cli-boundary, plugin-boundary, schema-boundary, etc. +- **Local side** — `local_adapter`, `local_interface`, `entry_point` +- **Upstream side** — `reused_surface`, `contracts` +- **Fragility** — `fragility_points` where upstream drift hurts first + +Refactoring work happens in the consuming repository. The Integration Definition +records the resulting boundary so automation and maintainers know what to protect. + +**Output:** `boundary` with at least one concrete local/upstream reference. +Domain-specific keys (e.g. `markitect_adapter_id`) are allowed. + +### 4. Maintain + +Register the definition, assign maintainers, and connect validation to ongoing +upstream monitoring. + +| Concern | Field | +| ------- | ----- | +| Registry visibility | row in `indexes/integrations.yaml` | +| Accountability | `maintenance.maintainers` | +| When humans must act | `maintenance.escalation_conditions`, `risks.escalation_triggers` | +| Proving continuity | `validation.harness` | +| Update behavior | `update_policy.default_action` | +| Lifecycle | `status` (see schema enum) | + +**Output:** integration moves from `draft` → `registered` → `active` once +maintainers, validation, and index registration are in place. + +### Full product lifecycle (context) + +The four-step loop above is the minimum path to a registry entry. The broader +open-reuse lifecycle (see `INTENT.md`) also includes reframe, register, monitor, +auto-update, validate, and escalate. Registry format v0.1 encodes the knowledge +those later stages require. + +```text +Prove Value +→ Analyze → Classify → Refactor → Create Integration Definition +→ Register in indexes/integrations.yaml +→ Monitor upstream → Validate → Update or Escalate +``` + +## Add a new integration (v0.1) + +1. Copy `templates/integration-entry.template.yaml` to the consuming repo at + `integration/.integration.yaml`. +2. Complete the **Analyze** and **Classify** sections: upstream, reuse mode, risks. +3. Complete the **Refactor** section: `boundary` with explicit local/upstream seams. +4. Complete the **Maintain** section: validation harness, maintainers, update policy. +5. Set `schema_version: open-reuse.integration.v0.1`. +6. Add a row to `registry/indexes/integrations.yaml` with `id`, `path`, `repo`, + `reuse_mode`, and `upstream` summary. +7. Validate manually (checklist below) before setting `status: active`. + +Early adopters may use `schema_version: open-reuse.integration.v1`; the schema +accepts both. New entries should use v0.1. + +## Manual validation checklist + +Use until an automated CLI validator ships. + +### Required fields + +- [ ] `schema_version` is `open-reuse.integration.v0.1` (or accepted `v1` draft) +- [ ] `id` matches `^[a-z][a-z0-9-]*$` +- [ ] `name`, `upstream.name`, `reuse.primary_reuse_mode` are present +- [ ] `boundary` has at least one local and one upstream reference +- [ ] `validation.harness` is a runnable command or documented CI entry point +- [ ] `maintenance` includes `maintainers` or `escalation_conditions` + +### Promotion gates + +| Target status | Requires | +| ------------- | -------- | +| `draft` | Core identity + upstream + reuse mode | +| `registered` | Boundary + validation harness + index row | +| `active` | Maintainers + update policy + passing validation | + +### Enum checks + +Reuse modes: see schema `reuseMode` enum in `schemas/integration.schema.yaml`. +Lifecycle status: `draft`, `registered`, `active`, `needs_review`, `degraded`, +`paused`, `deprecated`, `retired`. +Update actions: `ignore`, `monitor-only`, `open-issue`, `open-update-proposal`, +`open-pull-request`, `auto-merge-after-validation`, `require-maintainer-review`, +`block-update`, `escalate`. + +### Index checks + +- [ ] New entry appears in `indexes/integrations.yaml` +- [ ] `path` and `repo` point to the definition file in the consuming repository +- [ ] `reuse_mode` matches `reuse.primary_reuse_mode` in the definition +- [ ] `upstream.name` matches the definition + +## Reference integration + +`markitect-quarkdown` provides the first real-world adapter integration: + +- Definition: `markitect-quarkdown/integration/quarkdown.integration.yaml` +- Index row: `indexes/integrations.yaml` → `markitect-quarkdown` + +Use it as a worked example for adapter + cli-boundary reuse. + +## Capability registry + +The capability index supports reuse-surface federation for cross-repo planning. 1. Copy a capability entry template (see reuse-surface `templates/capability-entry.template.md`). 2. Add the row to `indexes/capabilities.yaml`. 3. Run `reuse-surface validate` from a checkout with the CLI installed. 4. Merge to `main` and verify publish with `reuse-surface establish --publish-check`. -Federation contract: reuse-surface `docs/RegistryFederation.md`. +Federation contract: reuse-surface `docs/RegistryFederation.md`. \ No newline at end of file diff --git a/registry/indexes/integrations.yaml b/registry/indexes/integrations.yaml new file mode 100644 index 0000000..eb8e238 --- /dev/null +++ b/registry/indexes/integrations.yaml @@ -0,0 +1,19 @@ +version: 1 +updated: '2026-06-24' +domain: infotech +schema: schemas/integration.schema.yaml +integrations: + - id: markitect-quarkdown + name: Markitect Quarkdown Render Adapter + status: active + owner: markitect-quarkdown + reuse_mode: adapter + risk_level: medium + path: integration/quarkdown.integration.yaml + repo: markitect-quarkdown + upstream: + name: Quarkdown + project_url: https://github.com/iamgio/quarkdown + notes: > + Reference integration for adapter reuse mode. Definition lives in the + consuming repository; this index row is the registry discovery surface. \ No newline at end of file diff --git a/registry/integrations/.gitkeep b/registry/integrations/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/schemas/integration.schema.yaml b/schemas/integration.schema.yaml new file mode 100644 index 0000000..b3df06e --- /dev/null +++ b/schemas/integration.schema.yaml @@ -0,0 +1,261 @@ +$schema: https://json-schema.org/draft/2020-12/schema +$id: https://open-reuse.local/schemas/integration.schema.yaml +title: Integration Definition +description: > + JSON Schema for open-reuse Integration Definition files (YAML). Aligns with + INTENT.md, ProductRequirementsDocument.md section 14.1, and registry format v0.1. +type: object +additionalProperties: false +required: + - schema_version + - id + - name + - upstream + - reuse + - boundary + - validation + - maintenance +properties: + schema_version: + type: string + enum: + - open-reuse.integration.v0.1 + - open-reuse.integration.v1 + description: > + Schema version. v0.1 is the canonical registry format; v1 is accepted for + early adopters and will converge on v0.1 field names. + id: + type: string + pattern: '^[a-z][a-z0-9-]*$' + description: Stable integration identifier (kebab-case slug). + name: + type: string + minLength: 1 + description: Human-readable integration name. + description: + type: string + description: Optional summary of the integration purpose and value. + status: + $ref: '#/$defs/lifecycleStatus' + owner: + type: string + description: Team, repository, or accountable party for the integration asset. + local: + type: object + additionalProperties: false + properties: + repo: + type: string + description: Repository hosting the integration implementation. + path: + type: string + description: Path to the integration definition file within the repo. + system: + type: string + description: Local consuming system or product name. + upstream: + type: object + additionalProperties: false + required: + - name + properties: + name: + type: string + minLength: 1 + project_url: + type: string + format: uri + homepage: + type: string + format: uri + version_policy: + type: string + description: > + Accepted upstream version range or tracking policy (e.g. semver range, + major-line policy, or tag pattern). + current_version: + type: string + description: Pinned or last-validated upstream version reference. + monitor: + type: object + additionalProperties: false + properties: + releases: + type: boolean + tags: + type: boolean + security_advisories: + type: boolean + license_changes: + type: boolean + reuse: + type: object + additionalProperties: false + required: + - primary_reuse_mode + properties: + primary_reuse_mode: + $ref: '#/$defs/reuseMode' + secondary_reuse_modes: + type: array + items: + $ref: '#/$defs/reuseMode' + risk_level: + type: string + enum: [low, low-medium, medium, high, very-high] + rationale: + type: string + description: Why this reuse mode classification applies. + boundary: + type: object + description: > + Explicit seam between the local system and reused upstream functionality. + Domain-specific keys are allowed beyond the recommended fields. + minProperties: 1 + properties: + type: + type: string + enum: + - interface + - port + - adapter + - wrapper-service + - api-facade + - plugin-boundary + - cli-boundary + - schema-boundary + - event-contract + - file-copy-boundary + local_adapter: + type: string + local_interface: + type: string + reused_surface: + type: string + entry_point: + type: string + contracts: + type: array + items: + type: string + fragility_points: + type: array + items: + type: string + additionalProperties: true + runtime: + type: object + additionalProperties: true + description: Optional runtime assumptions required for the integration. + permissions: + type: object + additionalProperties: true + description: Optional permission or capability model mapping. + validation: + type: object + additionalProperties: false + required: + - harness + properties: + harness: + type: string + minLength: 1 + description: Command or reference to the validation harness entry point. + skip_without_runtime: + type: boolean + checks: + type: array + items: + type: string + policy: + type: string + enum: + - required-before-update + - advisory + - on-escalation-only + update_policy: + type: object + additionalProperties: false + properties: + default_action: + type: string + enum: + - ignore + - monitor-only + - open-issue + - open-update-proposal + - open-pull-request + - auto-merge-after-validation + - require-maintainer-review + - block-update + - escalate + auto_eligible: + type: boolean + description: Whether automation may attempt updates without review. + risks: + type: object + additionalProperties: false + properties: + sensitivity: + type: array + items: + type: string + escalation_triggers: + type: array + items: + type: string + maintenance: + type: object + additionalProperties: false + minProperties: 1 + properties: + maintainers: + type: array + minItems: 1 + items: + type: string + description: People, teams, or automation identities accountable for review. + escalation_conditions: + type: array + items: + type: string + last_validated: + type: string + format: date + notes: + type: string + audit: + type: object + additionalProperties: false + properties: + registered_at: + type: string + format: date + updated_at: + type: string + format: date + registered_by: + type: string +$defs: + lifecycleStatus: + type: string + enum: + - draft + - registered + - active + - needs_review + - degraded + - paused + - deprecated + - retired + reuseMode: + type: string + enum: + - dependency + - dependency-reuse + - plugin + - adapter + - component-extraction + - patch-overlay + - fork-continuation + - cli-boundary \ No newline at end of file diff --git a/templates/integration-entry.template.yaml b/templates/integration-entry.template.yaml new file mode 100644 index 0000000..543f9a1 --- /dev/null +++ b/templates/integration-entry.template.yaml @@ -0,0 +1,87 @@ +# Copy to /integration/.integration.yaml +# Register the entry in open-reuse registry/indexes/integrations.yaml after review. +schema_version: open-reuse.integration.v0.1 +id: example-integration +name: Example Integration +description: > + One paragraph describing the proven integration, its value, and the local + system it connects to upstream open-source software. +status: draft +owner: team-or-repo-slug + +local: + repo: example-repo + path: integration/example.integration.yaml + system: Example Product + +upstream: + name: Upstream Project + project_url: https://github.com/org/upstream + homepage: https://upstream.example/ + version_policy: ">=1.0.0 <2.0.0" + current_version: "1.4.2" + monitor: + releases: true + tags: true + security_advisories: true + license_changes: true + +reuse: + primary_reuse_mode: adapter + secondary_reuse_modes: + - dependency-reuse + risk_level: medium + rationale: > + Upstream behavior is wrapped behind a local adapter interface; upstream + API changes require validation but do not directly touch local systems. + +boundary: + type: adapter + local_adapter: example.adapter.ExampleAdapter + local_interface: example.contracts.UpstreamPort + reused_surface: upstream public API / CLI + entry_point: example.adapters + contracts: + - example.integration.v1 + fragility_points: + - CLI flag changes + - output format changes + +runtime: + required: + - Upstream CLI 1.x + - Python 3.11+ + +validation: + harness: python3 -m pytest tests/integration/ + skip_without_runtime: true + checks: + - contract compatibility + - golden-path smoke test + - failure-mode diagnostics + policy: required-before-update + +update_policy: + default_action: require-maintainer-review + auto_eligible: false + +risks: + sensitivity: + - breaking API changes + - license changes + - security advisories + escalation_triggers: + - validation failure + - upstream major release + +maintenance: + maintainers: + - team-platform + escalation_conditions: + - upstream release detected + - validation failure + - dependency requirement change + +audit: + registered_at: "2026-06-24" + registered_by: integration-maintainer \ No newline at end of file diff --git a/workplans/OPEN-WP-0002-integration-asset-registry.md b/workplans/OPEN-WP-0002-integration-asset-registry.md index 04f87d9..c7e5e63 100644 --- a/workplans/OPEN-WP-0002-integration-asset-registry.md +++ b/workplans/OPEN-WP-0002-integration-asset-registry.md @@ -4,11 +4,11 @@ type: workplan title: "Integration asset registry foundation" domain: infotech repo: open-reuse -status: ready +status: finished owner: codex topic_slug: infotech created: "2026-06-22" -updated: "2026-06-22" +updated: "2026-06-24" state_hub_workstream_id: "07cec732-6526-48e4-84d0-373e4abcb6d4" --- @@ -20,9 +20,19 @@ Establish registry format for managed OSS integration assets. ```task id: OPEN-WP-0002-T01 -status: todo +status: done priority: high state_hub_task_id: "b55b4413-2053-40bd-bee1-d138937f0b4f" ``` +Result 2026-06-24: Integration Definition schema v0.1, template, index, and +lifecycle documentation. + Define integration asset schema in `registry/` and document analyze→classify→refactor→maintain loop. + +Deliverables: + +- `schemas/integration.schema.yaml` — JSON Schema for Integration Definitions +- `templates/integration-entry.template.yaml` — authoring template +- `registry/indexes/integrations.yaml` — discovery index with markitect-quarkdown reference +- `registry/README.md` — analyze→classify→refactor→maintain loop and validation checklist \ No newline at end of file