Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Ask the project in SPARQL

Two agents in one repository used next to find work for each agent. Other project questions, such as how much of each change is left or which requirements have open work, can be answered by queries over the graphs gonk holds. A query you keep is a script: published at a name, versioned by its content, and run by reading that name. None of this chapter needs a model.

Catch up

Start in a new empty directory, as in Start a project; this chapter regenerates the sample and seeds a fresh ledger. gonk.http.ledger lets a signed-out browser on this machine read the project’s ledger; without it, only default is readable that way. If the gonk from the previous chapter is still running, stop it first, since this one takes the same port. Keep gonk running in one terminal and run the remaining commands in another, from the same directory.

$ mkdir -p .config/ikigai
$ printf 'gonk.http.ledger = "library"\n' > .config/ikigai/config.toml
$ ikigai-gonk --config-home "$PWD/.config/ikigai" --data-home "$PWD/.ikigai" --port 1070 --no-quic --no-backup 2>&1 | tee gonk.log
ikigai-gonk 0.1.1 — holding the store at …/.ikigai/store
  instance … — new at every start; open pages compare it
  http    http://localhost:1070/ — loopback (127.0.0.1:1070); anonymous read: library; …
…
$ git clone --quiet https://github.com/ikigai-rs/ikigai-gonk-starter starter
$ git -C starter checkout --quiet 2a5f08cdeec2535d0addb03fcb5b6b62bb870e4a
$ (cd starter && python3 tools/new.py ../library --process solo,spec > /dev/null)
$ git -C library init -q -b main
$ (cd library && python3 tools/gonk.py init --ledger library --socket ../.ikigai/gonk.sock --holder ada | tail -1)
ready.
$ git -C library add -A
$ git -C library -c user.name=Ada -c user.email=ada@example.com commit -q -m 'Generate the library sample'
$ (cd library && python3 tools/gonk.py seed | tail -1)
seed: 8 filed, 0 already filed, 0 checked off (not filed), 6 order link(s) added

The queries you already have

init published what .gonk/queries/ and .gonk/scripts/ hold, each under the ledger’s name, so one gonk can hold many repositories’ scripts. A file says LEDGER where it names its graph, and init fills that in.

$ ikigai --mount "urn:gk:=$PWD/.ikigai/gonk.sock" -c 'source urn:gk:script:catalog'
urn:script:library-next-for-artifact  published  sha256:…
urn:script:library-open-items-for-artifact  published  sha256:…
urn:script:library-open-work-by-change  published  sha256:…
urn:script:library-requirements-with-open-work  published  sha256:…
[uncacheable]
$ cat library/.gonk/queries/open-work-by-change.rq
# How much of each change in flight is still open: open and closed items per change.
# `seed` labels every item `change:<id>` for the OpenSpec change its task belongs to.
PREFIX ledger: <https://ikigai-rs.dev/ns/ledger#>
SELECT ?change (SUM(?isOpen) AS ?open) (COUNT(?item) AS ?items) WHERE {
  GRAPH <urn:iki:ledger:graph:LEDGER> {
    ?item a ledger:Item ; ledger:status ?status ; ledger:label ?label .
    FILTER(STRSTARTS(?label, 'change:'))
  }
  BIND(STRAFTER(?label, 'change:') AS ?change)
  BIND(IF(?status = ledger:open, 1, 0) AS ?isOpen)
}
GROUP BY ?change
ORDER BY DESC(?open) ?change
$ ikigai --mount "urn:gk:=$PWD/.ikigai/gonk.sock" -c 'source urn:gk:script:library-open-work-by-change:result as=text/csv'
change,open,items
add-holds,6,6
cap-late-fees,2,2
[uncacheable]

Reading :result runs it, and as=text/csv picks a plain face of the answer. A parameter is declared in the file’s leading comment (# @param artifact xsd:string) and passed as an argument:

$ ikigai --mount "urn:gk:=$PWD/.ikigai/gonk.sock" -c 'source urn:gk:script:library-open-items-for-artifact:result artifact=cli as=text/csv'
number,title,priority,holder
1,add-holds 1.1: Accept a hold on a title whose copies are all out,,
2,add-holds 1.2: Keep a returned copy for the first holder,,
3,add-holds 1.3: Refuse a renewal while a hold waits,,
4,add-holds 1.4: Add a vector to openspec/vectors.json for every new scenario,,
5,add-holds 2.1: Add `library.py hold MEMBER ISBN`,,
6,add-holds 2.2: Show who a kept copy waits for in `library.py copy`,,
[uncacheable]

Write your own, keep it in the repository

Which open tasks in one change are unclaimed, and which of them are blocked? A query is a file in .gonk/queries/, so it is reviewed, versioned and shared like code. The parameter is declared the same way:

# The open, unclaimed items of one change, and whether another open item blocks each.
# @param change xsd:string -- a change's id, such as add-holds
PREFIX ledger: <https://ikigai-rs.dev/ns/ledger#>
PREFIX dcterms: <http://purl.org/dc/terms/>
SELECT ?number ?title ?blocked WHERE {
  GRAPH <urn:iki:ledger:graph:LEDGER> {
    ?item a ledger:Item ;
          ledger:status ledger:open ;
          ledger:number ?number ;
          dcterms:title ?title ;
          ledger:label ?label .
    FILTER(?label = CONCAT('change:', ?change))
    FILTER NOT EXISTS { ?item ledger:claimedBy ?holder }
    BIND(EXISTS { ?other ledger:blocks ?item ; ledger:status ledger:open } AS ?blocked)
  }
}
ORDER BY ?number

Running init again publishes every file under those directories, and says so:

$ (cd library && python3 tools/gonk.py init | grep 'scripts   published')
  ok       scripts   published 5: urn:script:library-open-items-for-artifact, urn:script:library-open-work-by-change, urn:script:library-requirements-with-open-work, urn:script:library-unclaimed-in-change, urn:script:library-next-for-artifact
$ (cd library && python3 tools/gonk.py claim 7)
library#7 claimed by ada at epoch 1 until …
gonk.py: item 7 is held at epoch 1
$ ikigai --mount "urn:gk:=$PWD/.ikigai/gonk.sock" -c 'source urn:gk:script:library-unclaimed-in-change:result change=cap-late-fees as=text/csv'
number,title,blocked
8,cap-late-fees 1.2: Add a vector for the capped return to openspec/vectors.json,true
[uncacheable]

Item 7 is claimed, so it is gone, and item 8 is still waiting behind it. The answer stays right as the ledger changes, because gonk keeps an answer only until something it read is written.

A page anyone on this machine can open

A published script runs for whoever holds a grant for its name. To let a signed-out browser on this machine run it, mark it public. This republishes the script’s own text with public=true:

$ curl -s 'http://localhost:1070/script/library-open-work-by-change/result?as=text/csv'
denied: capability does not grant `urn:cap:script:run:library-*` (declared by `urn:script:library-open-work-by-change:result`; any grant under `urn:cap:script:run:library-` satisfies it)
$ ikigai --mount "urn:gk:=$PWD/.ikigai/gonk.sock" -c 'source urn:gk:script:library-open-work-by-change | sink urn:gk:script:library-open-work-by-change language=sparql state=published public=true'
urn:script:library-open-work-by-change:version:sha256:…
[2 uncacheable]
$ curl -s 'http://localhost:1070/script/library-open-work-by-change/result?as=text/csv'
change,open,items
add-holds,6,6
cap-late-fees,2,2

The spec graph

The ledger is one graph. The tree can be others, and that is what about was for: an item names the requirement it implements by IRI, so the two join. The sample’s third query does exactly that, and at first it answers nothing:

$ ikigai --mount "urn:gk:=$PWD/.ikigai/gonk.sock" -c 'source urn:gk:script:library-requirements-with-open-work:result as=text/csv'
capability,requirement,open
[uncacheable]

The spec files have not been turned into RDF graphs yet. That conversion is a lift, and gonk does not provide it (In gonk, and not in this page). The full lift uses ikigai-markdown and the mapping in a host of your own, which is what crates/openspec-ledger runs. For this page, a few lines of Python write just what the query reads, using the same IRIs seed derives:

import re
import sys
from pathlib import Path

OS = "http://example.org/openspec#"


def slug(name):
    return re.sub(r"[^a-z0-9]+", "-", name.lower()).strip("-")


capability = sys.argv[1]
print(f'<urn:openspec:spec:{capability}> <{OS}name> "{capability}" .')
tree = Path("library/openspec")
specs = [tree / "specs" / capability / "spec.md", *tree.glob(f"changes/*/specs/{capability}/spec.md")]
for spec in specs:
    if spec.exists():
        for name in re.findall(r"^### Requirement: (.+)$", spec.read_text(), re.MULTILINE):
            iri = f"<urn:openspec:spec:{capability}:requirement:{slug(name)}>"
            print(f"{iri} a <{OS}Requirement> .")
            print(f'{iri} <{OS}name> "{name}" .')
            print(f"{iri} <{OS}capability> <urn:openspec:spec:{capability}> .")

The owner loads one named graph per capability, over the socket:

$ python3 lift.py overdue | ikigai --mount "urn:gk:=$PWD/.ikigai/gonk.sock" -c 'sink urn:gk:iki:store:load graph=urn:openspec:graph:overdue format=text/turtle'
loaded text/turtle: … quads
[uncacheable]
$ python3 lift.py holds | ikigai --mount "urn:gk:=$PWD/.ikigai/gonk.sock" -c 'sink urn:gk:iki:store:load graph=urn:openspec:graph:holds format=text/turtle'
loaded text/turtle: … quads
[uncacheable]
$ python3 lift.py renewals | ikigai --mount "urn:gk:=$PWD/.ikigai/gonk.sock" -c 'sink urn:gk:iki:store:load graph=urn:openspec:graph:renewals format=text/turtle'
loaded text/turtle: … quads
[uncacheable]
$ ikigai --mount "urn:gk:=$PWD/.ikigai/gonk.sock" -c 'source urn:gk:iki:store:graphs'
urn:iki:ledger:graph:library
urn:openspec:graph:holds
urn:openspec:graph:overdue
urn:openspec:graph:renewals
[uncacheable]

Ask the published script again, and it still answers nothing:

$ ikigai --mount "urn:gk:=$PWD/.ikigai/gonk.sock" -c 'source urn:gk:script:library-requirements-with-open-work:result as=text/csv'
capability,requirement,open
[uncacheable]

That is gonk’s script ceiling. Every run here is held to the ledgers’ reads, whoever runs it, even the owner, so a script cannot reach a graph outside them. It sees no spec graph, so it matches no row; it is not an error, and an empty answer is not evidence that there is no open work.

So ask the store directly. graph-select reads exactly the graphs it names, under the caller’s own grants, and the owner holds them all. The same query text, on one line, for the shell:

$ grep -v '^#' library/.gonk/queries/requirements-with-open-work.rq | sed 's/LEDGER/library/' | tr '\n' ' ' > join.rq
$ ikigai --mount "urn:gk:=$PWD/.ikigai/gonk.sock" -c "source urn:gk:iki:store:graph-select graph=\"urn:openspec:graph:overdue urn:openspec:graph:holds urn:openspec:graph:renewals urn:iki:ledger:graph:library\" as=text/csv query=\"$(cat join.rq)\""
capability,requirement,open
holds,A member may hold a title with no copy on the shelf,2
holds,A returned copy of a held title waits for the first holder,2
overdue,A late return owes a fee,2
renewals,A loan of a held title is not renewed,1
[uncacheable]

Each row is a requirement, from the tree, with a count of open items, from the ledger. That join is what one store buys. Two things follow if you keep this up:

  • Spec graphs go stale. Nothing reloads the graphs when the tree changes. A host that lifts on every commit does (Changes and tasks as ledger items).
  • The join belongs to whoever holds the graphs. graph-select needs a read grant for every graph it names, and a published script still cannot read them here.

What you have now

Questions kept as files, published under the project’s name, and run by reading a name: over a socket, over QUIC by anyone granted, and as a page. The next chapter goes from questions to workflow.