Prepare SFLO v0.1.1 release

deno.json

@@ -4,7 +4,8 @@
     "fmt:check": "deno fmt --check deno.json scripts tests",
     "lint": "deno lint scripts tests",
     "check": "deno check scripts/**/*.ts tests/**/*.ts",
-    "test": "deno test --allow-read --allow-env=READABLE_STREAM tests",
+    "test": "deno test --allow-read --allow-write --allow-env=READABLE_STREAM tests",
+    "release:set-version": "deno run --allow-read --allow-write scripts/release_set_version.ts",
     "release:validate": "deno run --allow-read --allow-run=git --allow-env=READABLE_STREAM scripts/release_validate.ts",
     "ci": "deno task fmt:check && deno task lint && deno task check && deno task test && deno task release:validate"
   },

notes/ont.decision-log.md

@@ -10,6 +10,24 @@ created: 1773896763313
 
 Superseded decisions are intentionally retained for traceability. When a decision is reversed or replaced, mark it explicitly rather than deleting it.
 
+### 2026-05-24: Separate resolution targets from resolution observations and clarify reference sources
+
+- Status: Active
+- Decision: Keep `ArtifactResolutionTarget` as the requested-coordinate / resolution-policy relator, and add `ArtifactResolutionObservation` for observed resolution evidence. Add `ReferenceSource`, `ImportSource`, and `IntegrationSource` as `ArtifactResolutionTarget` subclasses alongside existing `ExtractionSource` and `ResourcePageSource`. Replace direct `ReferenceLink` target vocabulary with `hasReferenceSource`; remove `referenceTarget`, `referenceTargetState`, `referenceUriLiteral`, and extraction-scoped observed-source properties from the live model.
+- References: [[ont.summary.core]], [[ont.reference-links]], [[ont.task.2026.2026-05-24_1256-artifact-resolution-observations]], [[wa.task.2026.2026-05-22_1128-referencelink-clarification]]
+- Why:
+  - requested coordinates and observations have different lifecycles: coordinates are source-binding policy, while observations are appendable evidence records
+  - extraction-specific observed evidence would become increasingly awkward as import, integrate, reference, and page-source resolution all need the same evidence pattern
+  - `referenceTarget` was misleading because the target of the reference relation is already named by `referenceLinkFor`; the RDF data being read is a source
+  - `ReferenceLink` should remain the semantic curated-reference relator, while `ReferenceSource` carries byte-resolution coordinates
+  - import and integrate are distinct application concerns and should not be hidden behind bare `ArtifactResolutionTarget` bindings
+- Notes:
+  - `ReferenceLink` remains RDF-reference-data-only in this slice; do not rename it to `RdfReferenceLink`
+  - use `hasReferenceSource` from `ReferenceLink` to exactly one `ReferenceSource` in the first slice
+  - use `hasResolutionObservation` from an `ArtifactResolutionTarget` subclass to one or more `ArtifactResolutionObservation` records when an operation intentionally records evidence
+  - keep `expectsContentDigest` on `ArtifactResolutionTarget`, but record observed byte identity as `observedContentDigest` on observations
+  - ordinary runtime reads and page generation should not mutate RDF merely by resolving source bytes
+
 ### 2026-05-16: Separate sparse artifact file links from manifestation file links
 
 - Status: Active

notes/ont.dev.release-runbook.md

@@ -56,6 +56,14 @@ git diff --stat
 git diff
 ```
 
+After choosing the release version and issue date, update deterministic source metadata:
+
+```sh
+deno task release:set-version -- --version 0.1.0 --issued 2026-05-17
+```
+
+This command only updates release metadata in the active Turtle files. It does not create release notes, create tags, commit, push, generate Pages output, or infer release intent from source changes.
+
 Check version metadata:
 
 ```sh

notes/ont.reference-links.md

@@ -10,18 +10,34 @@ created: 1775175668572
 
 This note captures the current serialization and generation rules for `ReferenceCatalog` and `ReferenceLink`.
 
-Use it as the detailed companion to [ont.summary.core.md](./ont.summary.core.md). The summary note should stay compact; the path, fragment-IRI, and dereferenceability rules belong here.
+Use it as the detailed companion to [[ont.summary.core]]. The summary note should stay compact; the path, fragment-IRI, and dereferenceability rules belong here.
 
 ## Core Model
 
 - `ReferenceCatalog` is a narrow support artifact for managed `ReferenceLink` relators.
 - A `ReferenceCatalog` is owned by a `Knop` or `SemanticMesh`, but its contents are about the referent or mesh subject rather than about the support object as such.
 - `referenceLinkFor` points to the actual subject resource, not to a `Knop`.
-- `referenceTarget` points to a broad resource identity.
-- `referenceTargetState` may be used when a link should pin to a specific `HistoricalState`.
+- `hasReferenceSource` points to the `ReferenceSource` that identifies the RDF reference data used by the link.
+- `ReferenceSource` is an `ArtifactResolutionTarget` subclass. It uses generic target-resolution vocabulary such as `hasTargetArtifact`, `hasRequestedTargetState`, `targetAccessUrl`, and repository locator properties.
+- A first-slice `ReferenceSource` that uses `hasTargetArtifact` should target an `RdfDocument`. Non-RDF content such as Markdown page prose does not belong in `ReferenceLink`.
 
 `verifiedAt` and `verifiedBy` remain latest-verification convenience fields on `ReferenceLink`. They do not yet imply a separate verification object model.
 
+If source verification is intentionally recorded, the `ReferenceSource` should link to an `ArtifactResolutionObservation` with `hasResolutionObservation`. Ordinary page generation or source reads should not append observation records merely because bytes were resolved.
+
+Example:
+
+```turtle
+<alice/_knop/_references#reference001> a sflo:ReferenceLink ;
+  sflo:referenceLinkFor <alice> ;
+  sflo:hasReferenceRole sflo:referenceRole_canonical ;
+  sflo:hasReferenceSource <alice/_knop/_references#reference001-source> .
+
+<alice/_knop/_references#reference001-source> a sflo:ReferenceSource ;
+  sflo:hasTargetArtifact <alice/bio> ;
+  sflo:hasRequestedTargetState <alice/bio/_history001/_s0002> .
+```
+
 ## Serialization Direction
 
 For a Knop-owned catalog, the support artifact lives under the Knop:
@@ -45,6 +61,7 @@ This keeps `ReferenceCatalog` aligned with other support artifacts such as `_met
 For example:
 
 - `<alice/_knop/_references#reference001>`
+- `<alice/_knop/_references#reference001-source>` for the companion `ReferenceSource`
 
 Use the same mesh-root `@base` everywhere in the mesh or sub-mesh, and write the full mesh-root-relative fragment IRI explicitly. Do not use bare `<#reference001>` in historical snapshots, because that would re-root the identity to the snapshot document instead of preserving the stable catalog-fragment IRI.
 
@@ -82,5 +99,7 @@ If historical link-name collisions are detected while scanning current plus prio
 ## Scope Boundaries
 
 - `ReferenceCatalog` is for `ReferenceLink` relators only.
+- `ReferenceLink` is for curated RDF reference data; do not use it for page prose, Markdown imports, image assets, or generic source provenance.
+- `ReferenceSource` helper nodes may live in the same catalog because they are immediate source bindings for the links.
 - Broader descriptive RDF about the referent should normally live in a payload artifact or dataset.
 - This note does not broaden `ReferenceCatalog` to cover `owl:sameAs` or arbitrary referent description.

notes/ont.release-notes.v0.1.1.md → notes/ont.release-notes.v0.2.0.md

@@ -1,14 +1,14 @@
 ---
 id: d7pl15zys1da0kvfyfpni7k
-title: 'SFLO Ontology Release Notes v0.1.1'
+title: 'SFLO Ontology Release Notes v0.2.0'
 desc: ''
 updated: 1779178697607
 created: 1779178697607
 ---
 
 ## Summary
 
-`v0.1.1` is the next Semantic Flow ontology release after the initial `v0.1.0` tag. It focuses on publication and source-resolution vocabulary needed by Weave's branch-published and sidecar mesh workflows: explicit publication profiles, clearer artifact resolution modes, repository-backed source bindings, and SHACL severities that distinguish hard violations from warnings and informational modeling guidance.
+`v0.2.0` is the next planned Semantic Flow ontology release after the initial `v0.1.0` tag. It folds the unpublished `v0.1.1` branch work into a minor-version bump because the branch now contains breaking vocabulary and SHACL changes. The release focuses on publication and source-resolution vocabulary needed by Weave's branch-published and sidecar mesh workflows: explicit publication profiles, repository-backed source bindings, floating repository working sources, clearer artifact resolution modes, reference-source records, observation evidence records, and ResourcePage presentation configuration.
 
 ## Release Surfaces
 
@@ -22,18 +22,28 @@ The tagged source contains:
 
 The Pages publication exposes the core ontology, core SHACL, and config ontology under the `/sflo/` project Pages mesh:
 
-- `https://semantic-flow.github.io/sflo/ontology/releases/v0.1.1/ttl/semantic-flow-core-ontology.ttl`
-- `https://semantic-flow.github.io/sflo/ontology/shacl/releases/v0.1.1/ttl/semantic-flow-core-shacl.ttl`
-- `https://semantic-flow.github.io/sflo/config/releases/v0.1.1/ttl/semantic-flow-config-ontology.ttl`
+- `https://semantic-flow.github.io/sflo/ontology/releases/v0.2.0/ttl/semantic-flow-core-ontology.ttl`
+- `https://semantic-flow.github.io/sflo/ontology/shacl/releases/v0.2.0/ttl/semantic-flow-core-shacl.ttl`
+- `https://semantic-flow.github.io/sflo/config/releases/v0.2.0/ttl/semantic-flow-config-ontology.ttl`
 
 The job and provenance ontology source files remain tagged source vocabulary unless or until their non-`/sflo/` publication topology is settled.
 
+## Breaking Changes
+
+- The unpublished `v0.1.1` release plan is superseded by `v0.2.0`; no `v0.1.1` tag should be cut from this branch.
+- `ReferenceLink` no longer uses `referenceTarget`, `referenceTargetState`, or `referenceUriLiteral`. A `ReferenceLink` now points to exactly one `ReferenceSource` with `hasReferenceSource`, and that `ReferenceSource` uses the shared `ArtifactResolutionTarget` vocabulary to identify RDF reference-data bytes.
+- Extraction-scoped observed-source properties are removed from the live model: `hasObservedSourceState`, `hasObservedSourceManifestation`, `hasObservedSourceLocatedFile`, `observedSourceLocalRelativePath`, and `observedSourceDigest`. Observed resolution evidence now belongs in `ArtifactResolutionObservation` records linked from an artifact-resolution target with `hasResolutionObservation`.
+- The old `artifactResolutionMode_pinned` and `artifactResolutionMode_current` values remain retired. Active resolution mode vocabulary is now `artifactResolutionMode_working` and `artifactResolutionMode_latestState`, with exact requested state, located-file, manifestation, commit, or digest coordinates treated as exact by default.
+- ResourcePage presentation configuration now has explicit config and SHACL structure for templates, stylesheets, generated panel selection, panel ordering, inclusion policy, targeting, and data requirements. Older ad hoc assumptions about generated panels are not the modeled contract for this release.
+- Repository source modeling now distinguishes exact or ref-backed `RepositorySourceLocator` records from mutable working-source `RepositorySourceFloatingLocator` records. Floating locators deliberately omit branch/ref, commit, digest, and local checkout path evidence.
+
 ## Highlights
 
-- Core artifact resolution vocabulary now distinguishes `artifactResolutionMode_working` from `artifactResolutionMode_latestState`.
+- Core artifact resolution vocabulary distinguishes mutable working-byte resolution from latest settled-state resolution.
 - Exact requested target coordinates, such as a requested `HistoricalState`, `LocatedFile`, manifestation/distribution, commit, or digest, imply exact identity by default.
-- `artifactResolutionMode_pinned` and `artifactResolutionMode_current` are removed from the active model; they were too broad for the source-binding and release-publication cases now being modeled.
 - A requested `ArtifactHistory` without a requested state means "latest state in that history" by default.
+- `ReferenceSource`, `ImportSource`, and `IntegrationSource` join `ExtractionSource` and `ResourcePageSource` as shared `ArtifactResolutionTarget` subclasses.
+- `ArtifactResolutionObservation` records observed state, manifestation, located file, local path, digest, timestamp, and observer evidence only when an operation intentionally records resolution evidence.
 - Config vocabulary adds `PublicationProfile`, `publicationProfile_none`, `publicationProfile_githubPages`, and `hasPublicationProfile` so a mesh can persist its resolved static-publication host profile.
 - GitHub Pages profile semantics are intentionally narrow: the profile covers host controls such as `.nojekyll`; Weave and the ontology do not treat `CNAME` as managed publication state.
 - `hasNextHistorySegmentHint` and `hasNextStateSegmentHint` are now scoped to the relevant digital-artifact/history progression objects instead of generic config resources.
@@ -50,7 +60,7 @@ The job and provenance ontology source files remain tagged source vocabulary unl
 
 ## Version Metadata
 
-The actively released Turtle files align their release metadata on `0.1.1` and plural `releases/v0.1.1` paths:
+The actively released Turtle files align their release metadata on `0.2.0` and plural `releases/v0.2.0` paths:
 
 - `owl:versionInfo`
 - `dcterms:hasVersion`
@@ -62,10 +72,10 @@ The actively released Turtle files align their release metadata on `0.1.1` and p
 
 The release process handles the `owl:versionIRI` chicken-and-egg explicitly. `owl:versionIRI` points to immutable raw bytes for the final tag, while the tag itself is created only after the source metadata commit exists. The safe sequence is:
 
-1. Explicitly choose the release version, such as `0.1.1`.
-2. Mechanically update source metadata to deterministic `v0.1.1` tag URLs and `releases/v0.1.1` publication URLs.
+1. Explicitly choose the release version, such as `0.2.0`.
+2. Mechanically update source metadata to deterministic `v0.2.0` tag URLs and `releases/v0.2.0` publication URLs.
 3. Validate the Turtle and commit the source release.
-4. Create and push the `v0.1.1` tag at that exact commit.
+4. Create and push the `v0.2.0` tag at that exact commit.
 5. Regenerate the Pages publication from a detached source worktree checked out at the tag commit.
 6. Verify that the raw tag URLs and Pages release URLs fetch the expected bytes.
 
@@ -76,7 +86,9 @@ Automation should help with steps 2, 3, 5, and 6, but it should not silently inv
 The source release validation follows [[ont.dev.release-runbook]]:
 
 ```sh
-rg 'versionInfo|hasVersion|versionIRI|contentUrl|downloadURL|releases/v0\.1\.1' semantic-flow-*.ttl
+rg 'versionInfo|hasVersion|versionIRI|contentUrl|downloadURL|releases/v0\.2\.0' semantic-flow-*.ttl
+deno task release:validate -- --version 0.2.0
+deno task ci
 riot --validate semantic-flow-core-ontology.ttl semantic-flow-core-shacl.ttl semantic-flow-config-ontology.ttl semantic-flow-job-ontology.ttl semantic-flow-prov-ontology.ttl
 git diff --check
 ```