textus 0.55.1 → 0.56.0

data/README.md

@@ -1,4 +1,4 @@
-<!-- Generated from knowledge.readme.* fragments by the artifacts.docs.readme workflow. Edit the fragments under .textus/data/knowledge/readme/ and run `textus drain`. -->
+<!-- Generated from knowledge.intent.readme-* fragments by the artifacts.docs.readme workflow. Edit the fragments under .textus/data/knowledge/intent/ and run `textus drain`. -->
 <!-- This is a fragment of the README. Edit here; the README is composed from fragments by a workflow. -->
 <p align="center">
   <picture>
@@ -39,7 +39,7 @@ flowchart LR
     end
 
     human -->|author| knowledge["knowledge<br/>(canon)"]
-    agent -->|keep| notebook["notebook<br/>(workspace)"]
+    agent -->|keep| scratchpad["scratchpad<br/>(workspace)"]
     agent -->|propose| proposals["proposals<br/>(queue)"]
     automation -->|drain| artifacts["artifacts<br/>(machine)"]
     human -->|ingest| raw["raw<br/>(intake)"]
@@ -68,7 +68,7 @@ The point of those lanes is to **build context you can trust**. Place each lane
                        LOW TRUST                     HIGH TRUST
                       (unreviewed)                (authoritative)
               ┌──────────────────────────┬───────────────────────────────┐
-DURABLE       │  notebook                │  knowledge  ★ the goal        │
+DURABLE       │  scratchpad                │  knowledge  ★ the goal        │
 (kept)        │  agent's working truth   │  canon — a human authors      │
               │  durable, but low-trust  │  here · the context you ship  │
               ├──────────────────────────┼───────────────────────────────┤
@@ -84,12 +84,12 @@ Without coordination, they overwrite each other and nothing remembers why. textu
 
 ```
 knowledge/   author only            — who you are, what you decide, how you sound
-notebook/    keep only              — agent's own durable lane (bytes climb to knowledge only via propose→accept)
+scratchpad/    keep only              — agent's own durable lane (bytes climb to knowledge only via propose→accept)
 proposals/   propose (agent+human) — proposals waiting on a human accept
 artifacts/   converge only         — machine-maintained: computed outputs + external inputs
 ```
 
-An agent that tries to write directly into `knowledge/` gets `write_forbidden`. It writes to `proposals/` (to change authoritative content) or its own `notebook/` (for working memory). You accept the good proposals; textus promotes them, records the move, and audits both halves. Stable per-entry `uid:` means a reorganization doesn't break references. A monotonic audit cursor (`textus pulse --since=N`) means the next session — possibly a different agent, possibly a different model — picks up exactly where the last one left off.
+An agent that tries to write directly into `knowledge/` gets `write_forbidden`. It writes to `proposals/` (to change authoritative content) or its own `scratchpad/` (for working memory). You accept the good proposals; textus promotes them, records the move, and audits both halves. Stable per-entry `uid:` means a reorganization doesn't break references. A monotonic audit cursor (`textus pulse --since=N`) means the next session — possibly a different agent, possibly a different model — picks up exactly where the last one left off.
 
 That's the load-bearing claim: **coordination is a protocol invariant, not a library convenience.**
 
@@ -125,7 +125,7 @@ Try the gate the other way (`textus put knowledge.notes.X --as=agent`) and you g
 
 This Ruby gem is the reference implementation of **`textus/4`** — a wire format and storage convention any language can speak. The protocol owns the envelope shape, the role/lane gate, the audit log format, and the key grammar. The gem version (semver, see badge) and the protocol version (`textus/4`) move independently; envelopes carry the `protocol` field so consumers can pin to the contract, not the implementation.
 
-- Specification: [`SPEC.md`](SPEC.md)
+- Specification: the wire protocol spec (`textus get knowledge.specs.*`)
 - Architecture: [`docs/architecture/README.md`](docs/architecture/README.md)
 - Per-release notes: [`CHANGELOG.md`](CHANGELOG.md)
 
@@ -156,7 +156,7 @@ roles:
 
 lanes:
   - { name: knowledge, kind: canon }      # author   — canonical truth
-  - { name: notebook,  kind: workspace }  # keep     — agent's own durable lane
+  - { name: scratchpad,  kind: workspace }  # keep     — agent's own durable lane
   - { name: proposals, kind: queue }      # propose  — proposals awaiting accept
   - { name: artifacts, kind: machine }    # converge — computed outputs + external inputs
 ```
@@ -170,7 +170,7 @@ lanes:
   .gitignore             # generated — ignores .state/ and any tracked:false entries
   data/                  # one dir per lane; kinds + capabilities are in the manifest above
     knowledge/           # e.g. identity (knowledge.identity.*), voice, decisions, notes
-    notebook/
+    scratchpad/
     proposals/
     artifacts/           # machine lane: computed outputs + external inputs
   .state/                  # disposable runtime state — gitignored, safe to delete (ADR 0038)
@@ -201,20 +201,20 @@ For a worked store — knowledge entries, a staged proposal, schemas, ERB templa
 
 ## What's shipped
 
-- **Per-entry formats & publish.** `format: markdown|json|yaml|text` per entry; a typed `publish:` block (`to:` for file fan-out, `tree:` for a whole-subtree mirror) byte-copies derived files to their consumer paths. ([SPEC §5.2–5.3](SPEC.md))
+- **Per-entry formats & publish.** `format: markdown|json|yaml|text` per entry; a typed `publish:` block (`to:` for file fan-out, `tree:` for a whole-subtree mirror) byte-copies derived files to their consumer paths. (the wire protocol spec §5.2–5.3)
 - **Stable identity.** Auto-minted `uid:` survives writes and `textus key mv`; reorganising never breaks references.
-- **Capability × lane-kind gate.** Writes carry `--as=<role>`; a role may write a lane iff it holds the capability the lane's `kind:` requires (`canon`→`author`, `workspace`→`keep`, `machine`→`converge`, `queue`→`propose`). The wrong role gets `write_forbidden` naming the capability needed and the roles that hold it. ([SPEC §5](SPEC.md))
+- **Capability × lane-kind gate.** Writes carry `--as=<role>`; a role may write a lane iff it holds the capability the lane's `kind:` requires (`canon`→`author`, `workspace`→`keep`, `machine`→`converge`, `queue`→`propose`). The wrong role gets `write_forbidden` naming the capability needed and the roles that hold it. (the wire protocol spec §5)
 - **Agent loop.** `textus boot` orients a fresh session; `textus pulse --since=N` is the per-turn heartbeat (changed entries, pending proposals, index etag for catalog drift detection). ([docs/how-to/agents-mcp.md](docs/how-to/agents-mcp.md))
 - **MCP surface.** The official `mcp` Ruby SDK drives the stdio JSON-RPC server; protocol version auto-negotiated up to `2025-11-25`. Wire textus into Claude Code, Cursor, or any MCP host in one config block.
 - **`textus doctor`.** Health checks across schemas, workflow registrations, keys, sentinels, and the audit log.
-- **`raw` lane and `ingest` verb.** Write-once intake lane for external URL bookmarks, files, and binary assets. Three source kinds (`url`/`file`/`asset`); daily key derivation; notebook stub per ingest. See "Intake and ingest" section below.
+- **`raw` lane and `ingest` verb.** Write-once intake lane for external URL bookmarks, files, and binary assets. Three source kinds (`url`/`file`/`asset`); daily key derivation; scratchpad stub per ingest. See "Intake and ingest" section below.
 
 ## CLI and lanes
 
-Every command operates on one store, located in this order: `--root <path>` flag → **`TEXTUS_ROOT`** env → walk up from the working directory for a `.textus/` ([SPEC §3.1](SPEC.md)). Write verbs require `--as=<role>`, resolved as: `--as` flag → **`TEXTUS_ROLE`** env → `.textus/role` file → default `human` ([SPEC §5.1](SPEC.md)). Default roles: `human`, `agent`, `automation` (rename or add your own in the manifest's `roles:` block). All verbs accept `--output=json` and return the envelope defined in [SPEC §8](SPEC.md).
+Every command operates on one store, located in this order: `--root <path>` flag → **`TEXTUS_ROOT`** env → walk up from the working directory for a `.textus/` (the wire protocol spec §3.1). Write verbs require `--as=<role>`, resolved as: `--as` flag → **`TEXTUS_ROLE`** env → `.textus/role` file → default `human` (the wire protocol spec §5.1). Default roles: `human`, `agent`, `automation` (rename or add your own in the manifest's `roles:` block). All verbs accept `--output=json` and return the envelope defined in the wire protocol spec §8.
 
-- Full verb table — read, write, health, scaffolding — is in [SPEC §9](SPEC.md).
-- Lane semantics and the capability × lane-kind mapping live in [SPEC §5](SPEC.md), with the reference in [`docs/reference/lanes.md`](docs/reference/lanes.md).
+- Full verb table — read, write, health, scaffolding — is in the wire protocol spec §9.
+- Lane semantics and the capability × lane-kind mapping live in the wire protocol spec §5, with the reference in [`docs/reference/lanes.md`](docs/reference/lanes.md).
 
 `textus boot` prints the same information for the current store: lanes, entry families with schemas, registered workflows, write flows, and the verb catalog. Run it inside a store and you get the live picture; reach for the SPEC when you want the contract.
 
@@ -225,7 +225,7 @@ Produced entries (`kind: produced`) declare how they're acquired in one `source:
 - **`source: { from: external, command: "...", sources: [...] }`** — *externally managed*: an out-of-band command or workflow writes the file; textus tracks staleness via declared `sources`.
 - **`source: { from: external, command: "true", sources: [] }` + a workflow** — *workflow-driven*: a `Textus.workflow` block (in `.textus/workflows/`) acquires and shapes the data on `drain`.
 
-Publishing is one typed `publish:` block (ADR 0052/0094). Each target is either `{ to: path, template?: name }` for a single file (optionally rendered through an ERB template) or `{ tree: "dir" }` to mirror a whole stored subtree. Sentinels for every published file live under `.textus/.state/sentinels/` (git-ignored, regenerated on drain). See SPEC §5.2, §5.3, §5.12.
+Publishing is one typed `publish:` block (ADR 0052/0094). Each target is either `{ to: path, template?: name }` for a single file (optionally rendered through an ERB template) or `{ tree: "dir" }` to mirror a whole stored subtree. Sentinels for every published file live under `.textus/track/sentinels/` (git-ignored, regenerated on drain). See SPEC §5.2, §5.3, §5.12.
 
 Templates live in `.textus/templates/` as ERB files (`.erb`). The template receives the entry's `content` hash as local variables via `ERB#result_with_hash`. If `inject_boot: true`, a `boot` variable is also available with the live orientation context.
 
@@ -281,8 +281,8 @@ textus ingest url agentskills-io-brainstorming \
 # see what landed in the raw lane
 textus list --lane=raw
 
-# a notebook stub was created alongside — annotate it
-textus get notebook.notes.raw
+# a scratchpad stub was created alongside — annotate it
+textus get scratchpad.notes.raw
 ```
 
 Stale produced entries are re-materialised by `drain`, not by reads — `get` is a pure read (ADR 0089).
@@ -322,4 +322,3 @@ Lefthook hooks (`brew bundle install` then `lefthook install`) run rubocop on `p
 
 [MIT](LICENSE)
 
-

data/lib/textus/artifact.rb

@@ -0,0 +1,8 @@
+module Textus
+  module Artifact
+  end
+end
+
+require_relative "lanes/artifact/cache"
+require_relative "lanes/artifact/lifecycle"
+require_relative "lanes/artifact/handlers"

data/lib/textus/errors.rb

@@ -131,18 +131,6 @@ module Textus
     def initialize(m) = super("io_error", m, exit_code: 64)
   end
 
-  class BuildInProgress < Error
-    def initialize(holder)
-      super(
-        "build_in_progress",
-        "a textus maintenance pass is already running (#{holder})",
-        details: { "holder" => holder },
-        exit_code: 75,
-        hint: "wait for the running maintenance pass to finish, or check for a recursive hook trigger"
-      )
-    end
-  end
-
   class UsageError < Error
     def initialize(m, hint: nil) = super("usage", m, exit_code: 2, hint: hint)
   end
@@ -166,18 +154,6 @@ module Textus
     end
   end
 
-  class BadRender < Error
-    def initialize(m, format: nil)
-      hint =
-        if format
-          "the template rendered invalid #{format}; try rendering with mock data and parsing the output before re-running drain"
-        else
-          "the template rendered invalid content; try rendering with mock data and parsing the output before re-running drain"
-        end
-      super("bad_render", m, hint: hint)
-    end
-  end
-
   class PublishError < Error
     def initialize(m, target: nil)
       hint =
@@ -190,21 +166,6 @@ module Textus
     def initialize(m) = super("proposal_error", m)
   end
 
-  class GuardFailed < Error
-    def initialize(failed)
-      # failed: [[predicate_name, reason], ...]
-      rows = failed.map { |name, reason| { "predicate" => name, "reason" => reason } }
-      names = failed.map(&:first)
-      super(
-        "guard_failed",
-        "guard refused crossing: #{failed.map { |n, r| "#{n} (#{r})" }.join("; ")}",
-        details: { "failed" => rows },
-        hint: "run 'textus policy explain <key> --output=json' to see the full guard; " \
-              "unmet: #{names.join(", ")}",
-      )
-    end
-  end
-
   class ContractDrift < Error
     JSONRPC_CODE = -32_001
 
@@ -232,6 +193,8 @@ module Textus
   end
 
   class CursorExpired < Error
+    JSONRPC_CODE = -32_002
+
     attr_reader :requested, :min_available
 
     def initialize(requested:, min_available:)

data/lib/textus/human.rb

@@ -0,0 +1,7 @@
+module Textus
+  module Human
+  end
+end
+
+require_relative "lanes/knowledge/runner"
+require_relative "lanes/knowledge/freeform"

data/lib/textus/infra/adapters/concurrency_adapter.rb

@@ -0,0 +1,15 @@
+module Textus
+  module Infra
+    module Adapters
+      class ConcurrencyAdapter
+        def future(&)
+          Concurrent::Promises.future(&)
+        end
+
+        def zip_futures(*promises)
+          Concurrent::Promises.zip_futures(*promises)
+        end
+      end
+    end
+  end
+end

data/lib/textus/infra/clock.rb

@@ -0,0 +1,7 @@
+module Textus
+  module Infra
+    class Clock
+      def now = Time.now
+    end
+  end
+end

data/lib/textus/infra/database.rb

@@ -0,0 +1,127 @@
+require "sequel"
+require "fileutils"
+
+module Textus
+  module Infra
+    class Database
+      def initialize(layout:)
+        @layout = layout
+        @db = nil
+      end
+
+      def connection = @db
+
+      def setup!
+        path = @layout.db_path
+        FileUtils.mkdir_p(File.dirname(path))
+        @db = Sequel.sqlite(path)
+        @db.run("PRAGMA journal_mode=WAL")
+        @db.run("PRAGMA foreign_keys=ON")
+        create_tables
+        self
+      end
+
+      def transaction(&) = @db.transaction(&)
+      def close = @db.disconnect
+
+      private
+
+      def create_tables
+        @db.create_table?(:workflow_events) do
+          primary_key :id
+          String :event_type, null: false
+          String :workflow_type, null: false
+          String :key
+          String :lane
+          String :payload, text: true
+          DateTime :created_at, default: Sequel::CURRENT_TIMESTAMP
+          DateTime :scheduled_at
+          String :state, null: false, default: "pending"
+          Integer :retry_count, null: false, default: 0
+          Integer :max_attempts, null: false, default: 3
+          String :error, text: true
+          index %i[state scheduled_at], where: "state = 'pending'"
+        end
+
+        @db.create_table?(:entries) do
+          String :key, primary_key: true
+          String :lane, null: false
+          String :format, null: false
+          String :schema
+          String :content, text: true
+          DateTime :indexed_at, null: false
+        end
+
+        @db.create_table?(:link_edges) do
+          String :from_key, null: false
+          String :to_key, null: false
+          primary_key %i[from_key to_key]
+          index :to_key
+          index :from_key
+        end
+
+        @db.create_table?(:audit_events) do
+          primary_key :seq
+          String :ts, null: false
+          String :role, null: false
+          String :verb, null: false
+          String :key, null: false
+          String :etag_before
+          String :etag_after
+          String :correlation_id
+          index :key
+          index %i[role verb]
+          index :correlation_id
+        end
+
+        @db.create_table?(:cursors) do
+          String :role, primary_key: true
+          Integer :seq, null: false, default: 0
+          DateTime :updated_at, null: false, default: Sequel::CURRENT_TIMESTAMP
+        end
+
+        @db.create_table?(:loop_positions) do
+          String :role, primary_key: true
+          Integer :index, null: false, default: 0
+          DateTime :updated_at, null: false, default: Sequel::CURRENT_TIMESTAMP
+        end
+
+        create_entries_fts
+      end
+
+      def create_entries_fts
+        @db.run(<<~SQL)
+          CREATE VIRTUAL TABLE IF NOT EXISTS entries_fts USING fts5(
+            key, lane, schema, content,
+            content=entries, content_rowid=rowid
+          )
+        SQL
+
+        @db.run(<<~SQL)
+          CREATE TRIGGER IF NOT EXISTS entries_ai AFTER INSERT ON entries BEGIN
+            INSERT INTO entries_fts(rowid, key, lane, schema, content)
+            VALUES (new.rowid, new.key, new.lane, new.schema, new.content);
+          END
+        SQL
+
+        @db.run(<<~SQL)
+          CREATE TRIGGER IF NOT EXISTS entries_ad AFTER DELETE ON entries BEGIN
+            INSERT INTO entries_fts(entries_fts, rowid, key, lane, schema, content)
+            VALUES ('delete', old.rowid, old.key, old.lane, old.schema, old.content);
+          END
+        SQL
+
+        @db.run(<<~SQL)
+          CREATE TRIGGER IF NOT EXISTS entries_au AFTER UPDATE ON entries BEGIN
+            INSERT INTO entries_fts(entries_fts, rowid, key, lane, schema, content)
+            VALUES ('delete', old.rowid, old.key, old.lane, old.schema, old.content);
+            INSERT INTO entries_fts(rowid, key, lane, schema, content)
+            VALUES (new.rowid, new.key, new.lane, new.schema, new.content);
+          END
+        SQL
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/textus/infra/file_system.rb

@@ -0,0 +1,54 @@
+require "fileutils"
+
+module Textus
+  module Infra
+    class FileSystem
+      module Interface
+        def read(path) = raise NotImplementedError
+        def write(path, bytes) = raise NotImplementedError
+        def delete(path) = raise NotImplementedError
+        def exists?(path) = raise NotImplementedError
+        def mkdir_p(path) = raise NotImplementedError
+        def mv(from, to) = raise NotImplementedError
+        def copy(source, target) = raise NotImplementedError
+        def glob(pattern) = raise NotImplementedError
+        def etag(path) = raise NotImplementedError
+      end
+
+      include Interface
+
+      def read(path) = File.binread(path)
+
+      def write(path, bytes)
+        FileUtils.mkdir_p(File.dirname(path))
+        File.binwrite(path, bytes)
+      end
+
+      def delete(path) = File.delete(path)
+      def exists?(path) = File.exist?(path)
+      def size(path) = File.size(path)
+      def mkdir_p(path) = FileUtils.mkdir_p(path)
+      def rmdir(path) = Dir.rmdir(path)
+      def dir_empty?(dir) = Dir.empty?(dir)
+      def glob(pattern) = Dir.glob(pattern)
+      def mv(from, to) = File.rename(from, to)
+      def copy(source, target) = FileUtils.cp(source, target)
+      def symlink?(path) = File.symlink?(path)
+      def identical?(left, right) = FileUtils.identical?(left, right)
+      def mtime(path) = File.mtime(path)
+      def directory?(path) = File.directory?(path)
+
+      def etag(path)
+        Value::Etag.for_file(path)
+      end
+
+      def flock_exclusive(path, nonblock: false)
+        File.open(path, File::RDWR | File::CREAT, 0o644) do |f|
+          f.close_on_exec = true
+          f.flock(nonblock ? File::LOCK_EX | File::LOCK_NB : File::LOCK_EX)
+          yield f
+        end
+      end
+    end
+  end
+end

data/lib/textus/infra/locks.rb

@@ -0,0 +1,50 @@
+require "fileutils"
+require "socket"
+require "time"
+
+module Textus
+  module Infra
+    module Locks
+      class WatcherLock
+        def initialize(root, file_system: Infra::FileSystem.new)
+          @root = File.expand_path(root)
+          @file_system = file_system
+          @path = Textus::Protocol::Layout.new(@root).lock_path("watcher")
+          @file = nil
+          @file_system.mkdir_p(File.dirname(@path))
+        end
+
+        def self.running?(root, file_system: Infra::FileSystem.new)
+          path = Textus::Protocol::Layout.new(root).lock_path("watcher")
+          return false unless file_system.exists?(path)
+
+          File.open(path, "r+") do |file|
+            got = file.flock(File::LOCK_EX | File::LOCK_NB)
+            file.flock(File::LOCK_UN) if got
+            return !got
+          end
+        rescue Errno::ENOENT
+          false
+        end
+
+        def acquire
+          @file = File.open(@path, File::RDWR | File::CREAT, 0o644)
+          raise "watcher already running" unless @file.flock(File::LOCK_EX | File::LOCK_NB)
+
+          @file.write("pid=#{Process.pid} host=#{Socket.gethostname}\n")
+          @file.flush
+          self
+        end
+
+        def release
+          return unless @file
+
+          @file.flock(File::LOCK_UN)
+          @file.close
+          @file_system.delete(@path) if @file_system.exists?(@path)
+          @file = nil
+        end
+      end
+    end
+  end
+end

data/lib/textus/infra/port/clock.rb

@@ -0,0 +1,18 @@
+module Textus
+  module Infra
+    module Port
+      # The wall clock. An instantiable class (ADR 0109) — uniform with the other
+      # ports; `now` reads the system time. Callers that need a fixed time still
+      # pass it as data via `Call#now`.
+      class Clock
+        module Interface
+          def now = raise NotImplementedError
+        end
+
+        include Interface
+
+        def now = Time.now
+      end
+    end
+  end
+end

data/lib/textus/infra/port/publisher.rb

@@ -0,0 +1,71 @@
+module Textus
+  module Infra
+    module Port
+      # Publishes built artifacts from the store to repo-relative consumer paths.
+      # Publish = copy + sentinel. The in-store file is already the consumer-shaped
+      # artifact; no parsing or stripping.
+      #
+      # Sentinel I/O is delegated to Textus::Infra::Port::SentinelStore. Sentinels live
+      # under `<store_root>/track/sentinels/` (runtime, git-ignored — ADR 0070) and
+      # mirror the target's repo-relative layout so consumer directories aren't
+      # polluted with `.textus-managed.json` siblings.
+      #
+      # An instantiable class (ADR 0109).
+      class Publisher
+        module Interface
+          def publish(source:, target:, store_root:, provenance_source: nil) = raise NotImplementedError
+          def unpublish(target:, store_root:) = raise NotImplementedError
+        end
+        include Interface
+
+        def initialize(file_system: Infra::FileSystem.new)
+          @file_system = file_system
+        end
+
+        def publish(source:, target:, store_root:, provenance_source: source)
+          @file_system.mkdir_p(File.dirname(target))
+          guard_clobber(source, target, store_root)
+          @file_system.delete(target) if @file_system.symlink?(target)
+          @file_system.copy(source, target)
+          Textus::Infra::Port::SentinelStore.new(file_system: @file_system).write!(target: target, source: provenance_source,
+                                                                                   store_root: store_root)
+        end
+
+        # Removes a previously-published file and its sentinel. No-op unless the
+        # target is textus-managed — never deletes an unmanaged file.
+        def unpublish(target:, store_root:)
+          return unless managed?(target, store_root)
+
+          @file_system.delete(target)
+          sentinel = Textus::Infra::Port::SentinelStore.new(file_system: @file_system).sentinel_path(target, store_root)
+          @file_system.delete(sentinel)
+        end
+
+        private
+
+        # Refuse to clobber an unmanaged target — EXCEPT adopt one whose bytes
+        # already equal the source (ADR 0050: a migration copies files into the
+        # store and publishes them back to where they already live, so the target
+        # is byte-identical — nothing is at risk). Adoption writes no sentinel
+        # here; the normal publish path below does, and the cp is a content no-op.
+        # An unmanaged target whose content DIFFERS, or any unmanaged symlink, is
+        # still refused — that is the guard's real job.
+        def guard_clobber(source, target, store_root)
+          return unless @file_system.exists?(target) || @file_system.symlink?(target)
+          return if managed?(target, store_root)
+          return if adoptable?(source, target)
+
+          raise PublishError.new("refusing to clobber unmanaged file at #{target}", target: target)
+        end
+
+        def adoptable?(source, target)
+          !@file_system.symlink?(target) && File.file?(target) && @file_system.identical?(source, target)
+        end
+
+        def managed?(target, store_root)
+          @file_system.exists?(Textus::Infra::Port::SentinelStore.new(file_system: @file_system).sentinel_path(target, store_root))
+        end
+      end
+    end
+  end
+end

data/lib/textus/infra/port/sentinel.rb

@@ -0,0 +1,25 @@
+module Textus
+  module Infra
+    module Port
+      class Sentinel
+        attr_reader :target, :source, :sha256, :mode
+
+        def initialize(target:, source:, sha256:, mode:)
+          @target = target
+          @source = source
+          @sha256 = sha256
+          @mode = mode
+        end
+
+        def orphan?(file_stat) = @target.nil? || !file_stat.exists?(@target)
+
+        def drift?(file_stat)
+          return false if orphan?(file_stat)
+          return false if @sha256.nil?
+
+          Digest::SHA256.hexdigest(file_stat.read(@target)) != @sha256
+        end
+      end
+    end
+  end
+end

data/lib/textus/infra/port/sentinel_store.rb

@@ -0,0 +1,93 @@
+module Textus
+  module Infra
+    module Port
+      # Persistence adapter for sentinel files. Owns the on-disk JSON shape, the
+      # path layout (<store_root>/track/sentinels/<target-rel-to-repo>.textus-managed.json
+      # — runtime, git-ignored, ADR 0070), and all File/FileUtils I/O.
+      # Core::Sentinel is a pure value object that depends on this port for
+      # reads and writes.
+      class SentinelStore
+        module Interface
+          def write!(target:, source:, store_root:) = raise NotImplementedError
+          def load(path, repo_root) = raise NotImplementedError
+          def sentinel_path(target, store_root) = raise NotImplementedError
+          def targets_under(target_dir, store_root) = raise NotImplementedError
+        end
+        include Interface
+
+        SUFFIX = ".textus-managed.json".freeze
+
+        def initialize(file_system: Infra::FileSystem.new)
+          @file_system = file_system
+        end
+
+        def write!(target:, source:, store_root:)
+          path = sentinel_path(target, store_root)
+          @file_system.mkdir_p(File.dirname(path))
+          repo_root = File.dirname(store_root)
+          @file_system.write(path, JSON.generate(
+                                     "source" => rel_or_abs(source, repo_root),
+                                     "target" => rel_or_abs(target, repo_root),
+                                     "sha256" => Digest::SHA256.hexdigest(@file_system.read(target)),
+                                     "mode" => "copy",
+                                   ))
+        end
+
+        def load(path, repo_root)
+          raw = JSON.parse(@file_system.read(path))
+          Textus::Infra::Port::Sentinel.new(
+            target: absolutize(raw["target"], repo_root),
+            source: absolutize(raw["source"], repo_root),
+            sha256: raw["sha256"],
+            mode: raw["mode"],
+          )
+        rescue JSON::ParserError, Errno::ENOENT
+          nil
+        end
+
+        def sentinel_path(target, store_root)
+          repo_root = File.dirname(store_root)
+          rel = relative_to(target, repo_root) || File.basename(target)
+          File.join(Textus::Protocol::Layout.new(store_root).sentinels_root, rel + SUFFIX)
+        end
+
+        # Absolute target paths of every sentinel recorded under `target_dir`.
+        def targets_under(target_dir, store_root)
+          repo_root = File.dirname(store_root)
+          rel = relative_to(target_dir, repo_root) or return []
+          root = Textus::Protocol::Layout.new(store_root).sentinels_root
+          sdir = File.join(root, rel)
+          return [] unless @file_system.directory?(sdir)
+
+          prefix = root + "/"
+          @file_system.glob(File.join(sdir, "**", "*#{SUFFIX}")).map do |spath|
+            # strip the sentinel-store prefix and the .textus-managed.json suffix to recover the repo-relative target path
+            trel = spath.delete_prefix(prefix).delete_suffix(SUFFIX)
+            File.join(repo_root, trel)
+          end
+        end
+
+        private
+
+        def rel_or_abs(path, repo_root)
+          relative_to(path, repo_root) || File.expand_path(path)
+        end
+
+        def relative_to(path, repo_root)
+          path = File.expand_path(path)
+          base = File.expand_path(repo_root)
+          return nil unless path.start_with?(base + File::SEPARATOR)
+
+          path[(base.length + 1)..]
+        end
+
+        def absolutize(path, repo_root)
+          return path if path.nil?
+          return path if File.absolute_path?(path)
+
+          File.expand_path(path, repo_root)
+        end
+      end
+    end
+  end
+end