semantic-flow · djradon · May 28, 2026 · May 27, 2026 · May 27, 2026 · May 27, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -2,6 +2,10 @@
 
 - NEVER EXPOSE SECRETS in conversations. We "develop in public" and make most LLM conversations available to the world.
 
+- We use two agent personas: 
+  - Kim, the coder
+  - Jimbo, the project manager
+
 - Review the [product vision](documentation/notes/product-vision.md)
 
 - We are using Kato to record LLM conversations.

diff --git a/deno.json b/deno.json
@@ -1,5 +1,5 @@
 {
-  "version": "0.1.3",
+  "version": "0.2.2",
   "tasks": {
     "dev:root": "deno run --allow-read --allow-write --allow-env --allow-net src/main.ts",
     "bump:version": "deno run --allow-read --allow-write scripts/bump-version.ts",

diff --git a/documentation/notes/release-notes.v0.2.2.md b/documentation/notes/release-notes.v0.2.2.md
@@ -0,0 +1,61 @@
+---
+id: 75f2f1407bc849918424fff216c910fd
+title: 'release notes v0.2.2'
+desc: ''
+updated: 1779952466744
+created: 1779952466744
+---
+
+## Summary
+
+`v0.2.2` is a runtime correctness and publication-prep release for Weave. It adds the shared artifact-resolution service, uses that service for source-backed config and ResourcePage loading, makes effective config target-aware, improves custom/current-only ResourcePage behavior, and strengthens the test/fixture pipeline used by GitHub CI and Codecov.
+
+This release also starts the append-onlyish inventory cleanup. The first inventory slices add an RDF-aware append planner and use it to preserve carried Knop support facts without dropping source registries, extraction sources, reference catalogs, or unknown support details.
+
+## Highlights
+
+- Shared artifact resolution now handles governed working, target-local, target-located, latest-state, exact-state, fallback, digest, and observed-resolution evidence flows through a common runtime service.
+- Config-source discovery now resolves mesh-local, Knop-local, and Knop-inheritable source attachments through the shared resolver, including recursive source chains, cycle/dedupe handling, and traceable source ordering.
+- Effective config is now provided per mesh or target scope, so recursive and multi-target `weave`, `version`, and `generate` operations can apply Knop-local and inherited config to the right target instead of flattening everything into one global config.
+- ResourcePage generation now supports per-page presentation config and exact/fallback ResourcePageSource resolution. Custom ResourcePage definitions can be current-only, so `_knop/_page/page.ttl` does not require a `_history001` shape when the effective policy says current-only.
+- The fixture/test pipeline now includes immutable fixture snapshot caching, better Deno JUnit normalization for Codecov test analytics, and release-runbook guidance for versioned release notes.
+- Append-onlyish inventory groundwork now includes an RDF-aware append planner plus planner-backed preservation for carried Knop support artifacts and `knop add-reference` source/reference coexistence.
+
+## Breaking Or Changed Behavior
+
+- This is still pre-1.0 software, and no compatibility shims are promised for stale pre-v1 fixture or inventory shapes.
+- Mesh-inheritable config has been removed as a distinct runtime layer. Mesh config remains mesh-local config; Knop-local and Knop-inheritable behavior is handled through Knop-scoped source attachments and per-target effective config resolution.
+- Source-backed config authority is attached from metadata. Mesh-local `sfcfg:hasConfigSource` belongs on `<_mesh>` in `_mesh/_meta/meta.ttl`; Knop-local and Knop-inheritable source attachments belong in current Knop metadata. Resolved `_config/*.ttl` files are config payloads, not bootstrap authority by filesystem location alone.
+- ResourcePageSource resolution now fails closed for malformed, unsafe, or unsupported source specs instead of silently falling through to unrelated fallback content.
+- ResourcePageDefinition current-only behavior means a Knop page-definition artifact may be represented by `_knop/_page/page.ttl` without a versioned `_history001` tree.
+- Fixture helpers now read git-backed fixture snapshots from resolved commit SHAs rather than mutable refs, so local branch movement should not change fixture content under an existing cache key.
+
+## Artifacts
+
+- Git tag: `v0.2.2`
+- GitHub Release: `v0.2.2`
+- Native binary archives for Linux x64, Windows x64, macOS x64, and macOS arm64
+- Matching `.sha256` checksum files
+- npm packages for `@semantic-flow/weave` and supported platform packages
+
+## Validation
+
+- Source quality gate for release preparation: `deno task ci`, covering fmt check, lint, type check, coverage test run, and LCOV generation.
+- PR-level GitHub Actions `ci`, CodeQL, and CodeRabbit checks passed for the release-candidate branch before release prep. Codecov patch status remained useful coverage telemetry rather than the source quality gate for this release.
+- Release workflow rehearsal should use the `Release Manual` workflow with `npm_publish_mode: dry-run` and `github_release_mode: draft` before publishing npm packages or the GitHub Release.
+- Native binary smoke path: each built executable should run `weave --version`, and npm smoke install should verify the wrapper package resolves the matching platform package.
+
+## Known Limitations
+
+- Full append-onlyish inventory behavior is not complete. The release includes the shared append planner and first support-artifact consumers, but broad MeshInventory/KnopInventory writer migration and the full inventory-versus-metadata progression split remain follow-up work.
+- ResourcePageDefinition source regions still have a first-slice source-loading surface. Delegating direct `targetLocalRelativePath` regions fully through the shared resolver and adding `targetLocatedFile` support should land with explicit page-definition behavior tests.
+- Generic config-source management commands do not exist yet; source-backed config can be authored in RDF, but there is no dedicated CLI for adding or auditing config-source attachments.
+- Historical ResourcePage regeneration remains policy/design follow-up. Current generation is target-aware, but rebuild/repair/retraction modes are still intentionally separate future work.
+- Remote working/source URL resolution remains behind explicit operational policy and digest expectations; broad remote fetch workflows are not part of this release.
+
+## Next
+
+- Continue append-onlyish inventory work: migrate remaining inventory writers to append/no-op/fail-closed semantics, keep mutable current/latest/next progression in metadata, and add rerun idempotence tests for release automation.
+- Finish the ResourcePageDefinition resolver follow-up for direct `targetLocalRelativePath`, `targetLocatedFile`, digest, and fallback behavior.
+- Use the improved GitHub test analytics on main to tune Codecov patch thresholds and identify real coverage gaps without letting coverage telemetry block unrelated correctness releases.
+- Prepare the next publication dogfood pass for SFLO/URPX once this release is available as a packaged CLI.
diff --git a/documentation/notes/wd.codebase-overview.md b/documentation/notes/wd.codebase-overview.md
@@ -39,7 +39,8 @@ Core owns portable Semantic Flow behavior: request/result types, RDF/Turtle help
 
 Runtime owns local execution against a workspace: filesystem reads/writes, git-aware source resolution, effective config loading, structured logging, progress reporting, and command-scoped staging.
 
-- `src/runtime/config` loads and resolves effective runtime config from RDF.
+- `src/runtime/config` loads and resolves effective runtime config from RDF, including mesh-local `sfcfg:hasConfigSource` discovery through shared artifact resolution.
+- `src/runtime/artifact_resolution` resolves `sflo:ArtifactResolutionSpec`-shaped runtime requests into requested/observed coordinates plus optional bytes/text under local path policy; config-source discovery, artifact-backed ResourcePageSource loading, and extraction-source selected-state evidence use it.
 - `src/runtime/logging` provides structured operational and audit logging.
 - `src/runtime/operational/local_path_policy.ts` controls workspace-local path safety and allowed repo-adjacent access.
 - `src/runtime/weave/weave.ts` is the public runtime façade for validate/version/generate/weave.

diff --git a/documentation/notes/wd.general-guidance.md b/documentation/notes/wd.general-guidance.md
@@ -51,6 +51,8 @@ Before starting substantial code changes, a task note should be written and refi
 
 Before a task is closed, [[wd.decision-log]] can be updated with important decisions made.
 
+The backlog is kept in [[wd.todo]] and should be updated as tasks are completed.
+
 ## Behavior specs
 
 Semantic Flow behavior specs live in the Semantic Flow Framework notes as `sf.spec.*`. These specs describe externally visible Semantic Flow operation behavior and are meant to guide implementation and drive higher-level tests across implementations.

diff --git a/documentation/notes/wd.release-runbook.md b/documentation/notes/wd.release-runbook.md
@@ -2,7 +2,7 @@
 id: 1u8rkf5ka5mmgschlel7lym
 title: Release Runbook
 desc: ''
-updated: 1778685955558
+updated: 1779952454402
 created: 1778685955558
 ---
 
@@ -28,7 +28,7 @@ The normal release path is the `Release Manual` GitHub Actions workflow, run fro
 2. Bump or verify the release version:
 
 ```bash
-VERSION=0.1.1
+VERSION=0.2.2
 deno task bump:version -- --version "$VERSION"
 ```
 

diff --git a/documentation/notes/wd.runtime.md b/documentation/notes/wd.runtime.md
@@ -26,6 +26,23 @@ If an adjacent workspace source is denied and a mesh config exists, the runtime
 
 `weave mesh create` is the exception: it also accepts `--workspace` because it may need to create the initial mesh config before any mesh-carried workspace relationship exists.
 
+## Config-Source Bootstrap
+
+Weave discovers initial source-backed config attachments from current metadata, not by scanning `_config` directories.
+
+Mesh-local config sources are attached to the active mesh subject, normally in `_mesh/_meta/meta.ttl`:
+
+```ttl
+<_mesh> sfcfg:hasConfigSource [
+  a sfcfg:ConfigSource ;
+  sflo:targetLocalRelativePath "_mesh/_config/config.ttl"
+] .
+```
+
+Knop-local and Knop-inheritable config sources are attached to the current Knop subject in that Knop's metadata. For `alice`, that means `alice/_knop/_meta/meta.ttl` with subject `<alice/_knop>`.
+
+The resolved `_mesh/_config/*.ttl` and `<knop>/_knop/_config/*.ttl` files are config payloads/artifacts. They may contain ordinary policy bindings and may chain to additional config sources after the first source has been authorized, but they are not the initial bootstrap authority just because they are under `_config`. Inline `sfcfg:hasConfig` and `sfcfg:hasInheritableConfig` payloads are still deferred in the Weave runtime; use `sfcfg:hasConfigSource` / `sfcfg:hasInheritableConfigSource` with explicit `sflo:ArtifactResolutionSpec` coordinates.
+
 ## Runtime Logs
 
 The Weave CLI writes runtime logs under `${XDG_STATE_HOME:-~/.local/state}/weave/meshes/<mesh-identifier>/logs/` by default. `WEAVE_LOG_DIR` remains an explicit override for CI, replay scripts, and other workflows that want a job-local log directory.
diff --git a/documentation/notes/wd.testing.md b/documentation/notes/wd.testing.md
@@ -102,11 +102,15 @@ Preferred placement:
 
 Temp workspaces created with `createTestTmpDir()` are registered with the test harness and cleaned after each test when tests are run through `deno task test` or `deno task test:coverage`. Set `WEAVE_KEEP_TEST_TMP=1` when running those tasks to preserve temp workspaces for debugging a failing test.
 
+Curated Git fixture refs should be materialized through the shared fixture snapshot cache when possible. The cache stores immutable per-repo/per-commit snapshots under `/tmp/semantic-flow-fixture-snapshots`, keyed by resolved commit SHA, then copies from that snapshot into each test's private temp workspace. This keeps tests isolated while avoiding repeated per-file `git show` extraction.
+
 Live Semantic Flow fixture ladder regeneration is a separate cross-repo workflow; see [[wd.testing.fixture-ladder-regeneration]].
 
 ### Codecov Test Analytics
 
-GitHub Actions publishes JUnit XML to Codecov Test Analytics from the normal CI workflow. `deno task test:coverage` writes Deno's raw JUnit report to `/tmp/semantic-flow-coverage/junit.xml`, normalizes it for Codecov at `/tmp/semantic-flow-coverage/codecov-junit.xml`, and writes raw coverage data in the same temp directory. `deno task coverage:lcov` writes LCOV to `/tmp/semantic-flow-coverage/lcov.info`.
+GitHub Actions publishes JUnit XML to Codecov Test Analytics from the normal CI workflow. Treat Codecov as the canonical broad timing view for slowest suites and tests; add local timing instrumentation only when it answers a narrower question, such as setup time versus command execution inside one slow e2e suite.
+
+`deno task test:coverage` writes Deno's raw JUnit report to `/tmp/semantic-flow-coverage/junit.xml`, normalizes it for Codecov at `/tmp/semantic-flow-coverage/codecov-junit.xml`, and writes raw coverage data in the same temp directory. `deno task coverage:lcov` writes LCOV to `/tmp/semantic-flow-coverage/lcov.info`.
 
 Coverage-producing tasks create `/tmp/semantic-flow-coverage` if it does not exist, so a reboot-cleared `/tmp` does not require manual setup.