generated from coulomb/repo-seed
Add capability registry scaffold and seed entries from reuse-surface
Bootstrap registry/indexes/capabilities.yaml and migrate helix_forge capability entries owned by this repository for federation publishing.
This commit is contained in:
12
registry/README.md
Normal file
12
registry/README.md
Normal file
@@ -0,0 +1,12 @@
|
||||
# Capability Registry
|
||||
|
||||
Markdown-first capability index for federation and reuse planning.
|
||||
|
||||
## Authoring
|
||||
|
||||
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`.
|
||||
103
registry/capabilities/capability.wiki.adapter-contract.md
Normal file
103
registry/capabilities/capability.wiki.adapter-contract.md
Normal file
@@ -0,0 +1,103 @@
|
||||
---
|
||||
id: capability.wiki.adapter-contract
|
||||
name: Capability-Aware Shard Adapter Contract
|
||||
summary: A versioned backend interface where each binding declares a verified capability profile (positions on capability spectra), so federation ops degrade by capability.
|
||||
owner: shard-wiki
|
||||
status: draft
|
||||
domain: helix_forge
|
||||
tags: [wiki, adapter, capability, contract, conformance, shard-wiki]
|
||||
|
||||
maturity:
|
||||
discovery:
|
||||
current: D5
|
||||
target: D6
|
||||
confidence: high
|
||||
rationale: >
|
||||
Fifteen capability spectra with an orthogonal core + implication rules, plus
|
||||
a normative contract spec (TSD Section A); derived from a ~23-system synthesis.
|
||||
availability:
|
||||
current: A2
|
||||
target: A5
|
||||
confidence: medium
|
||||
rationale: >
|
||||
AdapterContract + a read/write FolderAdapter + a conformance suite that
|
||||
verifies declared profile == observed behaviour exist as a source module.
|
||||
|
||||
external_evidence:
|
||||
completeness:
|
||||
level: C2
|
||||
name: Partial
|
||||
confidence: medium
|
||||
basis: scope_vs_intent_and_consumer_expectations
|
||||
satisfied_expectations:
|
||||
- versioned interface with declared, conformance-verified capability profiles
|
||||
- one concrete adapter (file-store) passes the conformance suite
|
||||
broken_expectations:
|
||||
- only one substrate implemented (git-IS-store, REST, CRDT adapters planned)
|
||||
out_of_scope_expectations:
|
||||
- hosting backends
|
||||
reliability:
|
||||
level: R1
|
||||
confidence: low
|
||||
basis: consumer_quality_signals
|
||||
known_reliability_risks:
|
||||
- single adapter implemented so far
|
||||
|
||||
discovery:
|
||||
intent: >
|
||||
Mediate heterogeneity at one narrow waist: a backend participates by implementing a
|
||||
versioned interface and declaring a verified position on each capability spectrum.
|
||||
includes:
|
||||
- capability profile as data (orthogonal-core spectra + implied positions)
|
||||
- operation verbs (read/write/diff/merge/notify/.../derive-projection/execute)
|
||||
- a conformance suite (profiles verified, not self-asserted)
|
||||
excludes:
|
||||
- assuming uniform backend capabilities
|
||||
use_cases:
|
||||
- "shard-wiki UseCaseCatalog UC-34..UC-43, UC-50, UC-57, UC-60..UC-69 (shard attachment & adapter binding)"
|
||||
|
||||
availability:
|
||||
current_level: A2
|
||||
target_level: A5
|
||||
current_artifacts:
|
||||
- "shard-wiki/src/shard_wiki/adapters/"
|
||||
consumption_modes:
|
||||
- source module
|
||||
|
||||
relations:
|
||||
depends_on:
|
||||
- capability.wiki.page-model
|
||||
supports:
|
||||
- capability.wiki.shard-orchestration
|
||||
|
||||
evidence:
|
||||
documentation:
|
||||
- "shard-wiki/spec/TechnicalSpecificationDocument.md (Section A)"
|
||||
- "shard-wiki/spec/CoreArchitectureBlueprint.md (Section 6)"
|
||||
tests:
|
||||
- "shard-wiki/tests/test_folder_adapter.py"
|
||||
- "shard-wiki/tests/test_conformance.py"
|
||||
|
||||
consumer_guidance:
|
||||
recommended_for:
|
||||
- exposing any page store as a capability-described, conformance-checked shard
|
||||
not_recommended_for:
|
||||
- backends that cannot honestly describe their capabilities
|
||||
known_limitations:
|
||||
- reference implementation covers the file-store substrate only so far
|
||||
---
|
||||
|
||||
# Capability-Aware Shard Adapter Contract
|
||||
|
||||
The bottom narrow waist of shard-wiki: a versioned interface plus a **verified** capability
|
||||
profile per binding. Core logic is written once against capabilities (not per-backend), and
|
||||
the conformance suite rejects profiles whose declared abilities don't match observed behaviour.
|
||||
|
||||
## Assessment notes
|
||||
|
||||
### Discovery
|
||||
Fifteen spectra reduced to an orthogonal core with implication rules (CoreArchitectureBlueprint
|
||||
Section 6.5); normative in TSD Section A.
|
||||
|
||||
### Availability
|
||||
`adapters/` ships the contract, a folder adapter, and `assert_conformant`.
|
||||
103
registry/capabilities/capability.wiki.coordination-journal.md
Normal file
103
registry/capabilities/capability.wiki.coordination-journal.md
Normal file
@@ -0,0 +1,103 @@
|
||||
---
|
||||
id: capability.wiki.coordination-journal
|
||||
name: Event-Sourced Coordination Journal
|
||||
summary: An append-only, totally-ordered-per-space decision log (overlays, bindings, aliases, merges, forks) whose current state is a derived fold; git-addressable history.
|
||||
owner: shard-wiki
|
||||
status: draft
|
||||
domain: helix_forge
|
||||
tags: [wiki, event-sourcing, coordination, git, journal, shard-wiki]
|
||||
|
||||
maturity:
|
||||
discovery:
|
||||
current: D5
|
||||
target: D6
|
||||
confidence: high
|
||||
rationale: >
|
||||
Keystone resolved across two architecture reviews: coordination-canonical state
|
||||
as an append-only decision log with a per-space append authority; current state
|
||||
is a derived fold (derived = f(log)).
|
||||
availability:
|
||||
current: A2
|
||||
target: A4
|
||||
confidence: medium
|
||||
rationale: >
|
||||
In-memory DecisionLog + fold work as a source module; the git-backed store with a
|
||||
per-space lease (the production backing) is planned.
|
||||
|
||||
external_evidence:
|
||||
completeness:
|
||||
level: C2
|
||||
name: Partial
|
||||
confidence: medium
|
||||
basis: scope_vs_intent_and_consumer_expectations
|
||||
satisfied_expectations:
|
||||
- append-only, totally-ordered-per-space log with read-your-writes
|
||||
- derived fold to aliases + transitively-merged equivalence groups
|
||||
broken_expectations:
|
||||
- git-backed storage and per-space lease/append-authority not yet implemented
|
||||
out_of_scope_expectations:
|
||||
- general-purpose event bus
|
||||
reliability:
|
||||
level: R1
|
||||
confidence: low
|
||||
basis: consumer_quality_signals
|
||||
known_reliability_risks:
|
||||
- in-memory backing only; cross-process durability pending
|
||||
|
||||
discovery:
|
||||
intent: >
|
||||
Make coordination-canonical decisions durable and git-addressable as events, with the
|
||||
queryable current state always recomputable by replay.
|
||||
includes:
|
||||
- append-only decision log, totally ordered per information space
|
||||
- derived fold to current coordination state (aliases, equivalence groups, overlays)
|
||||
- per-space append authority (concurrency model)
|
||||
excludes:
|
||||
- storing derived/disposable union state
|
||||
use_cases:
|
||||
- "shard-wiki UseCaseCatalog UC-29, UC-33 (history, attribution, coordination journal)"
|
||||
|
||||
availability:
|
||||
current_level: A2
|
||||
target_level: A4
|
||||
current_artifacts:
|
||||
- "shard-wiki/src/shard_wiki/coordination/decision_log.py"
|
||||
target_artifacts:
|
||||
- git-backed log store with per-space lease
|
||||
consumption_modes:
|
||||
- source module
|
||||
|
||||
relations:
|
||||
supports:
|
||||
- capability.wiki.shard-orchestration
|
||||
- capability.wiki.overlay
|
||||
|
||||
evidence:
|
||||
documentation:
|
||||
- "shard-wiki/spec/CoreArchitectureBlueprint.md (Section 8.1)"
|
||||
tests:
|
||||
- "shard-wiki/tests/test_decision_log.py"
|
||||
|
||||
consumer_guidance:
|
||||
recommended_for:
|
||||
- durable, replayable, git-addressable coordination state for a federated space
|
||||
not_recommended_for:
|
||||
- high-frequency general event streaming
|
||||
known_limitations:
|
||||
- production git backing + lease are still on the roadmap (SHARD-WP-0009)
|
||||
---
|
||||
|
||||
# Event-Sourced Coordination Journal
|
||||
|
||||
The keystone: coordination-canonical state (overlays, equivalence bindings, aliases, merges,
|
||||
forks) is an append-only **decision log**, totally ordered per information space; the queryable
|
||||
current state is a derived **fold** of the log (`derived = f(log)`). The log is git-addressable,
|
||||
giving history/patch/review/backup for coordination decisions for free.
|
||||
|
||||
## Assessment notes
|
||||
|
||||
### Discovery
|
||||
Resolved across the round-1/round-2 architecture reviews (CoreArchitectureBlueprint Section 8.1).
|
||||
|
||||
### Availability
|
||||
`decision_log.py` ships an in-memory, totally-ordered log + fold; git+lease backing is planned.
|
||||
87
registry/capabilities/capability.wiki.derived-views.md
Normal file
87
registry/capabilities/capability.wiki.derived-views.md
Normal file
@@ -0,0 +1,87 @@
|
||||
---
|
||||
id: capability.wiki.derived-views
|
||||
name: Wiki Derived Views
|
||||
summary: Recomputable views over a wiki union — BackLinks, RecentChanges, AllPages, SiteMap, and (delegate-or-derive) Search — carrying provenance.
|
||||
owner: shard-wiki
|
||||
status: draft
|
||||
domain: helix_forge
|
||||
tags: [wiki, derived-views, backlinks, recentchanges, search, shard-wiki]
|
||||
|
||||
maturity:
|
||||
discovery:
|
||||
current: D3
|
||||
target: D5
|
||||
confidence: medium
|
||||
rationale: >
|
||||
Core-vs-adapter classification and behaviours are decided (FederationRequirements ADR-03);
|
||||
implementation is planned (SHARD-WP-0010), not built.
|
||||
availability:
|
||||
current: A0
|
||||
target: A4
|
||||
confidence: low
|
||||
rationale: >
|
||||
Designed; no implementation yet. Informational/planning reuse only today.
|
||||
|
||||
external_evidence:
|
||||
completeness:
|
||||
level: C0
|
||||
name: Absent
|
||||
confidence: low
|
||||
basis: scope_vs_intent_and_consumer_expectations
|
||||
satisfied_expectations: []
|
||||
broken_expectations:
|
||||
- no derived view is implemented yet
|
||||
out_of_scope_expectations:
|
||||
- presentation / rendering of views
|
||||
reliability:
|
||||
level: R0
|
||||
confidence: low
|
||||
basis: consumer_quality_signals
|
||||
known_reliability_risks:
|
||||
- planning-stage
|
||||
|
||||
discovery:
|
||||
intent: >
|
||||
Provide recomputable, provenance-carrying views over the union (link graph, change feed,
|
||||
enumeration, search) without introducing canonical state.
|
||||
includes:
|
||||
- BackLinks (link graph), RecentChanges (journal + shard signals), AllPages, SiteMap
|
||||
- Search as delegate-to-native-or-derive-index
|
||||
excludes:
|
||||
- view presentation / UI
|
||||
use_cases:
|
||||
- "shard-wiki UseCaseCatalog UC-17..UC-21, UC-63"
|
||||
|
||||
availability:
|
||||
current_level: A0
|
||||
target_level: A4
|
||||
current_artifacts:
|
||||
- "shard-wiki/workplans/SHARD-WP-0010-derived-views.md"
|
||||
consumption_modes:
|
||||
- informational
|
||||
|
||||
relations:
|
||||
depends_on:
|
||||
- capability.wiki.shard-orchestration
|
||||
- capability.wiki.page-model
|
||||
related_to:
|
||||
- capability.wiki.engine-typed-extensions
|
||||
|
||||
evidence:
|
||||
documentation:
|
||||
- "shard-wiki/spec/FederationRequirements.md (ADR-03)"
|
||||
|
||||
consumer_guidance:
|
||||
recommended_for:
|
||||
- planning derived navigation/discovery over a federated wiki union
|
||||
not_recommended_for:
|
||||
- implementation reuse today (planning-stage)
|
||||
known_limitations:
|
||||
- not implemented; Search ranking policy undecided
|
||||
---
|
||||
|
||||
# Wiki Derived Views
|
||||
|
||||
Recomputable views over the union (BackLinks, RecentChanges, AllPages, SiteMap, Search). All
|
||||
are derived/disposable (no canonical state) and carry provenance; Search is delegate-to-native
|
||||
where a shard's query capability allows, else a derived index. Planned in SHARD-WP-0010.
|
||||
115
registry/capabilities/capability.wiki.engine-typed-extensions.md
Normal file
115
registry/capabilities/capability.wiki.engine-typed-extensions.md
Normal file
@@ -0,0 +1,115 @@
|
||||
---
|
||||
id: capability.wiki.engine-typed-extensions
|
||||
name: Wiki Engine with Typed Extensions
|
||||
summary: A small-core wiki engine realizing a stringent typed-extension framework that addresses all wiki use cases and lets each shard activate only the features it needs.
|
||||
owner: shard-wiki
|
||||
status: draft
|
||||
domain: helix_forge
|
||||
tags: [wiki, engine, typed-extensions, feature-activation, shard-wiki]
|
||||
|
||||
maturity:
|
||||
discovery:
|
||||
current: D3
|
||||
target: D5
|
||||
confidence: medium
|
||||
rationale: >
|
||||
Architecture authored (shard-wiki/spec/WikiEngineCoreArchitecture.md): small page-store
|
||||
kernel + typed-extension framework, per-shard activation, engine-as-canonical-mode-shard,
|
||||
and a conflict-mediation realization are explored. Detailed extension SDK/ABI and the API
|
||||
protocol remain (so D3 Explored, not yet D4/D5).
|
||||
availability:
|
||||
current: A0
|
||||
target: A4
|
||||
confidence: low
|
||||
rationale: >
|
||||
Planned. No engine kernel or extensions exist yet; informational/planning reuse only.
|
||||
|
||||
external_evidence:
|
||||
completeness:
|
||||
level: C0
|
||||
name: Absent
|
||||
confidence: low
|
||||
basis: scope_vs_intent_and_consumer_expectations
|
||||
satisfied_expectations: []
|
||||
broken_expectations:
|
||||
- engine core and typed-extension mechanism not yet designed in detail
|
||||
out_of_scope_expectations:
|
||||
- replacing other wiki engines or mandating one implementation
|
||||
reliability:
|
||||
level: R0
|
||||
confidence: low
|
||||
basis: consumer_quality_signals
|
||||
known_reliability_risks:
|
||||
- planning-stage capability
|
||||
|
||||
discovery:
|
||||
intent: >
|
||||
Provide shard-wiki's reference first-party shard backend: a small core + a stringent
|
||||
typed-extension framework covering all collected use cases, mediating conflicting
|
||||
requirements into an integrated whole, with per-shard activation (only what you need).
|
||||
includes:
|
||||
- a minimal engine kernel (page lifecycle, storage via the adapter contract, the typing mechanism)
|
||||
- typed extensions that declare contracts and compose
|
||||
- per-shard feature activation
|
||||
excludes:
|
||||
- replacing or mandating other wiki engines (it is one shard type among many)
|
||||
- a single canonical implementation for all wikis
|
||||
use_cases:
|
||||
- "shard-wiki UseCaseCatalog UC-08..UC-25 and the full catalog (the engine must cover all)"
|
||||
|
||||
availability:
|
||||
current_level: A0
|
||||
target_level: A4
|
||||
current_artifacts:
|
||||
- "shard-wiki/workplans/SHARD-WP-0013-wiki-engine-prep.md"
|
||||
- "shard-wiki/spec/WikiEngineCoreArchitecture.md"
|
||||
consumption_modes:
|
||||
- informational
|
||||
|
||||
relations:
|
||||
depends_on:
|
||||
- capability.wiki.adapter-contract
|
||||
- capability.wiki.page-model
|
||||
related_to:
|
||||
- capability.feature-control.evaluate
|
||||
- capability.authorization.policy-evaluate
|
||||
|
||||
evidence:
|
||||
documentation:
|
||||
- "shard-wiki/workplans/SHARD-WP-0013-wiki-engine-prep.md"
|
||||
|
||||
consumer_guidance:
|
||||
recommended_for:
|
||||
- planning a composable, feature-activatable native wiki engine
|
||||
not_recommended_for:
|
||||
- implementation reuse today (planning-stage)
|
||||
known_limitations:
|
||||
- architecture authored; extension SDK/ABI + API protocol still to design; not yet built
|
||||
|
||||
promotion_history:
|
||||
- date: "2026-06-15"
|
||||
dimension: discovery
|
||||
from: D2
|
||||
to: D3
|
||||
rationale: WikiEngineCoreArchitecture.md authored (kernel + typed-extension framework explored); INTENT amendment ratified.
|
||||
author: shard-wiki
|
||||
---
|
||||
|
||||
# Wiki Engine with Typed Extensions
|
||||
|
||||
shard-wiki's planned reference first-party shard backend — a *canonical-mode shard* it
|
||||
implements natively: a small core plus a stringent typed-extension framework addressing all
|
||||
collected use cases, mediating conflicting requirements into a consistent whole, with per-shard
|
||||
activation (activate only what you need). It is one shard type among many — not a replacement
|
||||
for other engines. Per-shard activation is a candidate consumer of
|
||||
`capability.feature-control.evaluate`.
|
||||
|
||||
## Assessment notes
|
||||
|
||||
### Discovery
|
||||
Architecture authored: `shard-wiki/spec/WikiEngineCoreArchitecture.md` (small kernel +
|
||||
typed-extension framework; engine = canonical-mode shard). INTENT amendment ratified
|
||||
(2026-06-15, decision 84ffdb48). Extension SDK/ABI + API protocol are the next deliverables.
|
||||
|
||||
### Availability
|
||||
Planning-stage; informational reuse only.
|
||||
97
registry/capabilities/capability.wiki.federation-models.md
Normal file
97
registry/capabilities/capability.wiki.federation-models.md
Normal file
@@ -0,0 +1,97 @@
|
||||
---
|
||||
id: capability.wiki.federation-models
|
||||
name: Selectable Federation-Model Taxonomy
|
||||
summary: Federation as a plural, composable coordination axis (fork+journal, VCS-replication+ping, query-time graph-join, feed, activity-streams, engine-mirror) selected per space.
|
||||
owner: shard-wiki
|
||||
status: draft
|
||||
domain: helix_forge
|
||||
tags: [wiki, federation, taxonomy, composable, shard-wiki]
|
||||
|
||||
maturity:
|
||||
discovery:
|
||||
current: D4
|
||||
target: D6
|
||||
confidence: high
|
||||
rationale: >
|
||||
A six-model taxonomy distilled from a ~23-system synthesis, each model anchored in a
|
||||
real system, with capability prerequisites and per-space/per-shard composition rules.
|
||||
availability:
|
||||
current: A0
|
||||
target: A4
|
||||
confidence: low
|
||||
rationale: >
|
||||
Designed and specified (FederationArchitecture T17) but not implemented; informational
|
||||
reuse only today.
|
||||
|
||||
external_evidence:
|
||||
completeness:
|
||||
level: C1
|
||||
name: Sparse
|
||||
confidence: low
|
||||
basis: scope_vs_intent_and_consumer_expectations
|
||||
satisfied_expectations:
|
||||
- the model taxonomy and selection/composition rules are documented
|
||||
broken_expectations:
|
||||
- no federation transport is implemented yet
|
||||
out_of_scope_expectations:
|
||||
- mandating a single federation mechanism
|
||||
reliability:
|
||||
level: R0
|
||||
confidence: low
|
||||
basis: consumer_quality_signals
|
||||
known_reliability_risks:
|
||||
- design-stage; no runtime evidence
|
||||
|
||||
discovery:
|
||||
intent: >
|
||||
Treat federation as selectable and composable rather than one mechanism, so each space
|
||||
picks fork+journal, VCS-replication, query-join, feed, activity-streams, or engine-mirror.
|
||||
includes:
|
||||
- the six federation models + their capability floors
|
||||
- per-space selection and per-shard composition
|
||||
excludes:
|
||||
- imposing one homogeneous federation network
|
||||
use_cases:
|
||||
- "shard-wiki UseCaseCatalog UC-26, UC-31, UC-33, UC-71, UC-72, UC-74, UC-79"
|
||||
|
||||
availability:
|
||||
current_level: A0
|
||||
target_level: A4
|
||||
current_artifacts:
|
||||
- "shard-wiki/spec/FederationArchitecture.md (T17)"
|
||||
consumption_modes:
|
||||
- informational
|
||||
|
||||
relations:
|
||||
depends_on:
|
||||
- capability.wiki.shard-orchestration
|
||||
- capability.wiki.coordination-journal
|
||||
|
||||
evidence:
|
||||
documentation:
|
||||
- "shard-wiki/spec/FederationArchitecture.md"
|
||||
- "shard-wiki/research/260614-shard-spectrum-synthesis/findings.md"
|
||||
|
||||
consumer_guidance:
|
||||
recommended_for:
|
||||
- planning a federation strategy that mixes models per source
|
||||
not_recommended_for:
|
||||
- implementation reuse today (design-stage)
|
||||
known_limitations:
|
||||
- no transport implemented; informational planning reuse only
|
||||
---
|
||||
|
||||
# Selectable Federation-Model Taxonomy
|
||||
|
||||
Federation is plural and composable: fork+journal (Federated Wiki), VCS-replication+ping
|
||||
(ikiwiki), query-time graph-join (Wikibase SERVICE), feed aggregation, activity streams
|
||||
(ActivityPub), and engine-mirror (Wiki.js). A space selects a model and composes per shard;
|
||||
the default is fork+journal over git. Design-stage capability — strong for planning reuse.
|
||||
|
||||
## Assessment notes
|
||||
|
||||
### Discovery
|
||||
FederationArchitecture T17, distilled from the shard-spectrum synthesis (v3).
|
||||
|
||||
### Availability
|
||||
Specified, not implemented — informational reuse only.
|
||||
102
registry/capabilities/capability.wiki.overlay.md
Normal file
102
registry/capabilities/capability.wiki.overlay.md
Normal file
@@ -0,0 +1,102 @@
|
||||
---
|
||||
id: capability.wiki.overlay
|
||||
name: Overlay-Before-Mutation Write Path
|
||||
summary: Non-destructive edits (draft -> patch -> apply-under-drift) that let read-only, rate-limited, or lossy backends be edited safely without silent remote mutation.
|
||||
owner: shard-wiki
|
||||
status: draft
|
||||
domain: helix_forge
|
||||
tags: [wiki, overlay, patch, write-path, conflict, shard-wiki]
|
||||
|
||||
maturity:
|
||||
discovery:
|
||||
current: D5
|
||||
target: D6
|
||||
confidence: high
|
||||
rationale: >
|
||||
Overlay lifecycle and apply-under-drift semantics are specified (ADR-05, blueprint
|
||||
Section 8.6) and implemented as a single principled write path.
|
||||
availability:
|
||||
current: A2
|
||||
target: A4
|
||||
confidence: medium
|
||||
rationale: >
|
||||
OverlayEngine (draft/patch/apply), writable adapter, and InformationSpace.edit
|
||||
exist as a source module; three-way merge is not (refuse-on-drift only).
|
||||
|
||||
external_evidence:
|
||||
completeness:
|
||||
level: C2
|
||||
name: Partial
|
||||
confidence: medium
|
||||
basis: scope_vs_intent_and_consumer_expectations
|
||||
satisfied_expectations:
|
||||
- draft -> patch -> apply with fast-forward / refuse-on-drift / keep-draft outcomes
|
||||
- no silent remote mutation; overlay_state surfaced in provenance
|
||||
broken_expectations:
|
||||
- three-way / auto merge not implemented (refuse-on-conflict only)
|
||||
out_of_scope_expectations:
|
||||
- federation propagation of applied overlays
|
||||
reliability:
|
||||
level: R1
|
||||
confidence: low
|
||||
basis: consumer_quality_signals
|
||||
known_reliability_risks:
|
||||
- early implementation; conflict handling is detect-and-refuse only
|
||||
|
||||
discovery:
|
||||
intent: >
|
||||
Make any sub-write-through backend editable safely: an edit is an overlay first, applied
|
||||
only on explicit intent and only when the source has not drifted.
|
||||
includes:
|
||||
- overlay drafts recorded as coordination-canonical events
|
||||
- patch rendering (unified diff)
|
||||
- apply-under-drift (fast-forward / refuse / keep-draft)
|
||||
excludes:
|
||||
- destructive write without drift check
|
||||
use_cases:
|
||||
- "shard-wiki UseCaseCatalog UC-04, UC-26, UC-29 (remix primitives, overlay)"
|
||||
|
||||
availability:
|
||||
current_level: A2
|
||||
target_level: A4
|
||||
current_artifacts:
|
||||
- "shard-wiki/src/shard_wiki/coordination/overlay.py"
|
||||
- "shard-wiki/src/shard_wiki/coordination/patch.py"
|
||||
consumption_modes:
|
||||
- source module
|
||||
|
||||
relations:
|
||||
depends_on:
|
||||
- capability.wiki.coordination-journal
|
||||
- capability.wiki.adapter-contract
|
||||
|
||||
evidence:
|
||||
documentation:
|
||||
- "shard-wiki/spec/FederationRequirements.md (ADR-05)"
|
||||
- "shard-wiki/spec/CoreArchitectureBlueprint.md (Section 8.2, 8.6)"
|
||||
tests:
|
||||
- "shard-wiki/tests/test_apply.py"
|
||||
- "shard-wiki/tests/test_write_path_integration.py"
|
||||
|
||||
consumer_guidance:
|
||||
recommended_for:
|
||||
- safe editing over read-only / rate-limited / lossy backends
|
||||
not_recommended_for:
|
||||
- workflows needing automatic conflict resolution today
|
||||
known_limitations:
|
||||
- merge is detect-and-refuse; three-way merge is future work
|
||||
---
|
||||
|
||||
# Overlay-Before-Mutation Write Path
|
||||
|
||||
One principled write path: every edit drafts an overlay (a coordination-canonical event),
|
||||
renders as a patch, and applies under drift checks — fast-forwarding a writable target,
|
||||
keeping a local draft on a read-only target, and refusing (never clobbering) on external drift.
|
||||
|
||||
## Assessment notes
|
||||
|
||||
### Discovery
|
||||
Specified in FederationRequirements ADR-05 and CoreArchitectureBlueprint Section 8.2/8.6.
|
||||
|
||||
### Availability
|
||||
`overlay.py` + `patch.py` + `InformationSpace.edit` ship the path; built in SHARD-WP-0008.
|
||||
104
registry/capabilities/capability.wiki.page-model.md
Normal file
104
registry/capabilities/capability.wiki.page-model.md
Normal file
@@ -0,0 +1,104 @@
|
||||
---
|
||||
id: capability.wiki.page-model
|
||||
name: Backend-Neutral Wiki Page Model
|
||||
summary: A Markdown-first but stretchable page model with stable identity separate from placement and layered provenance, spanning prose to typed-graph and computational shapes.
|
||||
owner: shard-wiki
|
||||
status: draft
|
||||
domain: helix_forge
|
||||
tags: [wiki, page-model, identity, provenance, markdown, shard-wiki]
|
||||
|
||||
maturity:
|
||||
discovery:
|
||||
current: D5
|
||||
target: D6
|
||||
confidence: high
|
||||
rationale: >
|
||||
Page shapes (prose, typed records, typed-graph, inline-embedded, non-Markdown,
|
||||
and four computational shapes) plus identity != placement and layered provenance
|
||||
are specified and grounded in the dive research.
|
||||
availability:
|
||||
current: A2
|
||||
target: A5
|
||||
confidence: medium
|
||||
rationale: >
|
||||
Identity/Placement/Span/Page and layered ProvenanceEnvelope exist as a source
|
||||
module; richer shapes (typed-graph, notebook) are modeled but not all built.
|
||||
|
||||
external_evidence:
|
||||
completeness:
|
||||
level: C2
|
||||
name: Partial
|
||||
confidence: medium
|
||||
basis: scope_vs_intent_and_consumer_expectations
|
||||
satisfied_expectations:
|
||||
- stable identity distinct from placement and from content fingerprint
|
||||
- layered (effective-vs-own) provenance with near-zero per-span cost
|
||||
broken_expectations:
|
||||
- non-prose shapes (typed-graph, notebook, inline-embedded) not fully realized
|
||||
out_of_scope_expectations:
|
||||
- rendering / presentation
|
||||
reliability:
|
||||
level: R1
|
||||
confidence: low
|
||||
basis: consumer_quality_signals
|
||||
known_reliability_risks:
|
||||
- prose shape is the only exercised path so far
|
||||
|
||||
discovery:
|
||||
intent: >
|
||||
One backend-neutral lingua franca every consumer sees; every shape reduces to
|
||||
(content|source, structure, provenance envelope, optional derivation rule).
|
||||
includes:
|
||||
- page identity (stable handle) vs placement (N paths/shards) vs equivalence (fingerprint)
|
||||
- layered provenance envelope (page + span deltas)
|
||||
- page-shape taxonomy incl. computational shapes
|
||||
excludes:
|
||||
- deriving identity from content (a fingerprint identifies a version, not a page)
|
||||
use_cases:
|
||||
- "shard-wiki UseCaseCatalog UC-34, UC-39, UC-44..UC-49, UC-55, UC-73, UC-83, UC-84"
|
||||
|
||||
availability:
|
||||
current_level: A2
|
||||
target_level: A5
|
||||
current_artifacts:
|
||||
- "shard-wiki/src/shard_wiki/model/"
|
||||
- "shard-wiki/src/shard_wiki/provenance/"
|
||||
consumption_modes:
|
||||
- source module
|
||||
|
||||
relations:
|
||||
supports:
|
||||
- capability.wiki.adapter-contract
|
||||
- capability.wiki.shard-orchestration
|
||||
|
||||
evidence:
|
||||
documentation:
|
||||
- "shard-wiki/spec/CoreArchitectureBlueprint.md (Section 7)"
|
||||
- "shard-wiki/spec/FederationRequirements.md (ADR-02, ADR-04)"
|
||||
tests:
|
||||
- "shard-wiki/tests/test_model.py"
|
||||
- "shard-wiki/tests/test_provenance.py"
|
||||
|
||||
consumer_guidance:
|
||||
recommended_for:
|
||||
- a portable, provenance-carrying representation of wiki pages across backends
|
||||
not_recommended_for:
|
||||
- cases needing a single canonical path per page (use identity, not path)
|
||||
known_limitations:
|
||||
- non-prose shapes specified ahead of implementation
|
||||
---
|
||||
|
||||
# Backend-Neutral Wiki Page Model
|
||||
|
||||
The top narrow waist: a Markdown-first model that stretches to typed records, typed-graph
|
||||
statements, inline-embedded objects, non-Markdown assets, and computational shapes. Identity
|
||||
is a stable handle; placement and equivalence are separate mechanisms; provenance is layered
|
||||
(effective = page envelope + span delta).
|
||||
|
||||
## Assessment notes
|
||||
|
||||
### Discovery
|
||||
Specified in CoreArchitectureBlueprint Section 7 and FederationRequirements ADR-02/04.
|
||||
|
||||
### Availability
|
||||
`model/` + `provenance/` ship the prose path and the layered envelope today.
|
||||
114
registry/capabilities/capability.wiki.shard-orchestration.md
Normal file
114
registry/capabilities/capability.wiki.shard-orchestration.md
Normal file
@@ -0,0 +1,114 @@
|
||||
---
|
||||
id: capability.wiki.shard-orchestration
|
||||
name: Wiki Shard Orchestration
|
||||
summary: Present a union of pages across heterogeneous wiki-shaped shards while preserving each shard's provenance, capabilities, and history.
|
||||
owner: shard-wiki
|
||||
status: draft
|
||||
domain: helix_forge
|
||||
tags: [wiki, federation, orchestration, union, shard-wiki]
|
||||
|
||||
maturity:
|
||||
discovery:
|
||||
current: D5
|
||||
target: D6
|
||||
confidence: high
|
||||
rationale: >
|
||||
Grounded in 84 documented use cases and a twice-reviewed whole-system
|
||||
architecture (CoreArchitectureBlueprint) derived from ~23 prior-art systems.
|
||||
availability:
|
||||
current: A2
|
||||
target: A5
|
||||
confidence: medium
|
||||
rationale: >
|
||||
InformationSpace orchestrator (attach -> resolve -> read, chorus on
|
||||
ambiguity) works as a Python source module; network API and incremental
|
||||
union are planned.
|
||||
|
||||
external_evidence:
|
||||
completeness:
|
||||
level: C2
|
||||
name: Partial
|
||||
confidence: medium
|
||||
basis: scope_vs_intent_and_consumer_expectations
|
||||
satisfied_expectations:
|
||||
- attach folder shards and read a union page with layered provenance
|
||||
- chorus presentation of equivalent-but-divergent pages (union without erasure)
|
||||
broken_expectations:
|
||||
- incremental union maintenance and equivalence index not yet built
|
||||
- write-through federation transports not yet built
|
||||
out_of_scope_expectations:
|
||||
- hosting or replacing the underlying wiki engines
|
||||
reliability:
|
||||
level: R1
|
||||
confidence: low
|
||||
basis: consumer_quality_signals
|
||||
known_reliability_risks:
|
||||
- early implementation; 64 tests but no production exposure
|
||||
|
||||
discovery:
|
||||
intent: >
|
||||
Let independently stored, differently implemented wikis behave as one
|
||||
coherent, versionable, inspectable information space without homogenizing them.
|
||||
includes:
|
||||
- union resolution across shards (identity-keyed)
|
||||
- chorus / designated-canonical presentation of equivalent pages
|
||||
- lazy replication projection of remote content with freshness
|
||||
excludes:
|
||||
- implementing a backend wiki engine (see capability.wiki.engine-typed-extensions)
|
||||
- silent remote mutation
|
||||
assumptions:
|
||||
- canonical truth lives in shards + a git coordination journal; the union is derived
|
||||
use_cases:
|
||||
- "shard-wiki UseCaseCatalog UC-01..UC-07, UC-26..UC-33 (information space, federation, coordination)"
|
||||
|
||||
availability:
|
||||
current_level: A2
|
||||
target_level: A5
|
||||
current_artifacts:
|
||||
- "shard-wiki/src/shard_wiki/union/"
|
||||
- "shard-wiki/src/shard_wiki/space.py"
|
||||
target_artifacts:
|
||||
- orchestrator network API
|
||||
consumption_modes:
|
||||
- source module
|
||||
|
||||
relations:
|
||||
depends_on:
|
||||
- capability.wiki.adapter-contract
|
||||
- capability.wiki.page-model
|
||||
- capability.wiki.coordination-journal
|
||||
supports:
|
||||
- capability.wiki.federation-models
|
||||
|
||||
evidence:
|
||||
documentation:
|
||||
- "shard-wiki/spec/CoreArchitectureBlueprint.md"
|
||||
- "shard-wiki/spec/FederationArchitecture.md"
|
||||
tests:
|
||||
- "shard-wiki/tests/test_union.py"
|
||||
- "shard-wiki/tests/test_integration.py"
|
||||
|
||||
consumer_guidance:
|
||||
recommended_for:
|
||||
- composing multiple Markdown/wiki stores into one provenance-preserving view
|
||||
not_recommended_for:
|
||||
- replacing a single wiki engine
|
||||
known_limitations:
|
||||
- resolution is recompute-on-read until the incremental tier lands
|
||||
---
|
||||
|
||||
# Wiki Shard Orchestration
|
||||
|
||||
shard-wiki's core capability: orchestrate wiki-shaped content across heterogeneous *shards*
|
||||
as a union of pages, preserving provenance, capabilities, and history per shard. Canonical
|
||||
truth stays at the edges (shards + the git coordination journal); the union is a derived,
|
||||
recomputable view (orchestrator, not engine).
|
||||
|
||||
## Assessment notes
|
||||
|
||||
### Discovery
|
||||
Grounded by `UseCaseCatalog.md` (84 UCs) and the hardened `CoreArchitectureBlueprint.md`.
|
||||
|
||||
### Availability
|
||||
`InformationSpace` provides attach/resolve/read today (source module); a network API is the
|
||||
target availability step.
|
||||
145
registry/indexes/capabilities.yaml
Normal file
145
registry/indexes/capabilities.yaml
Normal file
@@ -0,0 +1,145 @@
|
||||
version: 1
|
||||
updated: '2026-06-16'
|
||||
domain: helix_forge
|
||||
capabilities:
|
||||
- id: capability.wiki.shard-orchestration
|
||||
name: Wiki Shard Orchestration
|
||||
summary: Present a union of pages across heterogeneous wiki-shaped shards while
|
||||
preserving each shard's provenance, capabilities, and history.
|
||||
vector: D5 / A2 / C2 / R1
|
||||
domain: helix_forge
|
||||
status: draft
|
||||
owner: shard-wiki
|
||||
path: registry/capabilities/capability.wiki.shard-orchestration.md
|
||||
tags:
|
||||
- wiki
|
||||
- federation
|
||||
- orchestration
|
||||
- union
|
||||
- shard-wiki
|
||||
consumption_modes:
|
||||
- source module
|
||||
- id: capability.wiki.adapter-contract
|
||||
name: Capability-Aware Shard Adapter Contract
|
||||
summary: A versioned backend interface where each binding declares a verified capability
|
||||
profile, so federation ops degrade by capability.
|
||||
vector: D5 / A2 / C2 / R1
|
||||
domain: helix_forge
|
||||
status: draft
|
||||
owner: shard-wiki
|
||||
path: registry/capabilities/capability.wiki.adapter-contract.md
|
||||
tags:
|
||||
- wiki
|
||||
- adapter
|
||||
- capability
|
||||
- contract
|
||||
- conformance
|
||||
- shard-wiki
|
||||
consumption_modes:
|
||||
- source module
|
||||
- id: capability.wiki.page-model
|
||||
name: Backend-Neutral Wiki Page Model
|
||||
summary: A Markdown-first but stretchable page model with stable identity separate
|
||||
from placement and layered provenance.
|
||||
vector: D5 / A2 / C2 / R1
|
||||
domain: helix_forge
|
||||
status: draft
|
||||
owner: shard-wiki
|
||||
path: registry/capabilities/capability.wiki.page-model.md
|
||||
tags:
|
||||
- wiki
|
||||
- page-model
|
||||
- identity
|
||||
- provenance
|
||||
- markdown
|
||||
- shard-wiki
|
||||
consumption_modes:
|
||||
- source module
|
||||
- id: capability.wiki.coordination-journal
|
||||
name: Event-Sourced Coordination Journal
|
||||
summary: An append-only, totally-ordered-per-space decision log whose current state
|
||||
is a derived fold; git-addressable history.
|
||||
vector: D5 / A2 / C2 / R1
|
||||
domain: helix_forge
|
||||
status: draft
|
||||
owner: shard-wiki
|
||||
path: registry/capabilities/capability.wiki.coordination-journal.md
|
||||
tags:
|
||||
- wiki
|
||||
- event-sourcing
|
||||
- coordination
|
||||
- git
|
||||
- journal
|
||||
- shard-wiki
|
||||
consumption_modes:
|
||||
- source module
|
||||
- id: capability.wiki.overlay
|
||||
name: Overlay-Before-Mutation Write Path
|
||||
summary: Non-destructive edits (draft -> patch -> apply-under-drift) that let read-only
|
||||
or limited backends be edited safely without silent remote mutation.
|
||||
vector: D5 / A2 / C2 / R1
|
||||
domain: helix_forge
|
||||
status: draft
|
||||
owner: shard-wiki
|
||||
path: registry/capabilities/capability.wiki.overlay.md
|
||||
tags:
|
||||
- wiki
|
||||
- overlay
|
||||
- patch
|
||||
- write-path
|
||||
- conflict
|
||||
- shard-wiki
|
||||
consumption_modes:
|
||||
- source module
|
||||
- id: capability.wiki.federation-models
|
||||
name: Selectable Federation-Model Taxonomy
|
||||
summary: Federation as a plural, composable coordination axis (fork+journal, VCS-replication,
|
||||
query-join, feed, activity-streams, engine-mirror) selected per space.
|
||||
vector: D4 / A0 / C1 / R0
|
||||
domain: helix_forge
|
||||
status: draft
|
||||
owner: shard-wiki
|
||||
path: registry/capabilities/capability.wiki.federation-models.md
|
||||
tags:
|
||||
- wiki
|
||||
- federation
|
||||
- taxonomy
|
||||
- composable
|
||||
- shard-wiki
|
||||
consumption_modes:
|
||||
- informational
|
||||
- id: capability.wiki.engine-typed-extensions
|
||||
name: Wiki Engine with Typed Extensions
|
||||
summary: A small-core wiki engine realizing a typed-extension framework that addresses
|
||||
all wiki use cases and lets each shard activate only the features it needs.
|
||||
vector: D3 / A0 / C0 / R0
|
||||
domain: helix_forge
|
||||
status: draft
|
||||
owner: shard-wiki
|
||||
path: registry/capabilities/capability.wiki.engine-typed-extensions.md
|
||||
tags:
|
||||
- wiki
|
||||
- engine
|
||||
- typed-extensions
|
||||
- feature-activation
|
||||
- shard-wiki
|
||||
consumption_modes:
|
||||
- informational
|
||||
- id: capability.wiki.derived-views
|
||||
name: Wiki Derived Views
|
||||
summary: Recomputable views over a wiki union — BackLinks, RecentChanges, AllPages,
|
||||
SiteMap, and (delegate-or-derive) Search — carrying provenance.
|
||||
vector: D3 / A0 / C0 / R0
|
||||
domain: helix_forge
|
||||
status: draft
|
||||
owner: shard-wiki
|
||||
path: registry/capabilities/capability.wiki.derived-views.md
|
||||
tags:
|
||||
- wiki
|
||||
- derived-views
|
||||
- backlinks
|
||||
- recentchanges
|
||||
- search
|
||||
- shard-wiki
|
||||
consumption_modes:
|
||||
- informational
|
||||
Reference in New Issue
Block a user