@zalom/plastic 1.0.0-beta.29 → 1.0.0-beta.30

package/PLASTIC.md

@@ -379,6 +379,22 @@ idempotent function with two entry points: the `plastic-lock` command (status, f
 release, reclaim, delegate) and `/plastic-intent-starting`, so boarding self-heals. This is
 mandatory, not a convention.
 
+The delivery lock arbitrates at the whole-intent grain: it decides who may work
+an intent at all. Underneath it, a per-artifact claim token (intent 111)
+arbitrates at the file grain: it decides who, among those already holding the
+delivery lock, is the one writer for one lifecycle file right now. A write to
+`spec.md`, `plan.md`, `checklist.md`, or the intent file must hold both the
+delivery lock and that file's claim. Claims live in `.claims/<artifact>.claim`
+inside the intent directory, one small JSON file per artifact, scoped strictly
+per-intent-per-artifact, never session-global. The claim gate is dormant
+(allows) when no claim file exists for an artifact, so ordinary single-owner
+work is unaffected; it engages, and denies, only when a second writer tries to
+take a fresh claim someone else already holds. A stale or corrupt claim fails
+open (the write proceeds, the claim yields) and the condition is surfaced in
+`plastic-lock status`, which lists any live claims alongside the delivery
+lock. See `plastic-lock claim`/`release-claim` and `docs/internals.md` for the
+full mechanism.
+
 Two locks share this schema (the two-lock doctrine): `delivery.lock` (exclusive, one owner
 plus delegates) and the future `maintenance.lock` (short TTL, structural move-and-record
 only). They are mutually exclusive in either direction; maintenance is allowed at any

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zalom/plastic",
-  "version": "1.0.0-beta.29",
+  "version": "1.0.0-beta.30",
   "description": "Intent-driven idea development system for AI coding agents",
   "type": "module",
   "bin": {

package/scripts/hook-lock-gate

@@ -28,6 +28,41 @@ begin
     rescue StandardError
       # ignore
     end
+
+    # Second, independent gate (intent 111 D7): the artifact-grain claim.
+    # Composes UNDER the delivery lock above; only reached once the delivery
+    # lock already allows. Dormant (nil) unless a claim file exists for this
+    # artifact, so AC7 (existing single-owner flows) is unaffected.
+    begin
+      dir = Bridge.intent_dir_for(file_path)
+      artifact = File.basename(file_path) if dir
+      if dir && artifact
+        claim_reason = Claim.claim_gate_reason(dir, artifact, session: session)
+        if claim_reason
+          print JSON.generate(
+            "hookSpecificOutput" => {
+              "hookEventName" => "PreToolUse",
+              "permissionDecision" => "deny",
+              "permissionDecisionReason" => claim_reason,
+            }
+          )
+          exit 0
+        end
+
+        # Fail-open surface (AC3): allow, but make the yielded/stale claim visible.
+        if Claim.fail_open?(dir, artifact)
+          $stderr.puts "plastic claim gate: unresolvable claim on #{artifact} in " \
+                       "intent #{Bridge.intent_id_from_dir(dir)} yielded; write " \
+                       "proceeds (see /plastic-lock status)"
+        end
+
+        # Heartbeat the session's own claim on the allow path (best-effort).
+        Claim.heartbeat(dir, artifact, session: session) rescue nil
+      end
+    rescue StandardError
+      # ignore: a claim-gate bug must never block a write (fail open)
+    end
+
     exit 0
   end
 

package/scripts/lib/lock.rb

@@ -191,3 +191,185 @@ module Lock
     File.write(path(intent_dir, type: type), JSON.pretty_generate(data))
   end
 end
+
+# Claim: the per-artifact claim-token layer (intent 111, D1/D7). Sits BENEATH
+# the session-keyed delivery lock: a lifecycle-file write must hold BOTH the
+# intent's delivery lock (Lock, unchanged) AND that specific artifact's claim.
+# Neither layer replaces the other.
+#
+# Storage: one small JSON file per artifact, sibling to delivery.lock, under
+# `.claims/<artifact>.claim` INSIDE the intent dir. Scope is strictly
+# per-intent-per-artifact (D4, hard constraint): a claim's on-disk path is
+# always `<intent_dir>/.claims/<artifact>.claim`, so a claim can never affect
+# any artifact but its own, nor any intent but its own. This is what stops a
+# stuck/stale claim from recreating the collision-90 failure mode.
+#
+# Exclusivity is O_EXCL at acquire, not session-equality (see plan.md): a
+# fresh claim is NEVER idempotently re-granted, even to the session that
+# holds it. This is what makes "exactly one writer" mechanical rather than a
+# convention: the second acquire against a live claim is rejected at the
+# filesystem, even when both callers share one CLAUDE_CODE_SESSION_ID.
+#
+# Fail open, always (D3): a stale or corrupt claim never blocks; it yields to
+# the current writer and the condition is surfaced (see Claim.fail_open?,
+# added in a later action, the named contract 112 gates on).
+#
+# Pure and dependency-injected: every function takes explicit paths plus ttl:
+# and now:; nothing here reads ENV or globals, and nothing shells out. Does
+# not touch any Lock function.
+module Claim
+  module_function
+
+  CLAIMS_DIR = ".claims"
+
+  def dir_path(intent_dir)
+    File.join(intent_dir, CLAIMS_DIR)
+  end
+
+  def path(intent_dir, artifact)
+    File.join(dir_path(intent_dir), "#{artifact}.claim")
+  end
+
+  # Parsed claim Hash, or nil when absent or corrupt (corrupt? distinguishes).
+  def read(intent_dir, artifact)
+    p = path(intent_dir, artifact)
+    return nil unless File.exist?(p)
+    data = JSON.parse(File.read(p)) rescue nil
+    data.is_a?(Hash) ? data : nil
+  end
+
+  def corrupt?(intent_dir, artifact)
+    File.exist?(path(intent_dir, artifact)) && read(intent_dir, artifact).nil?
+  end
+
+  # Lease freshness: the file mtime IS the heartbeat (mirrors Lock.fresh?).
+  def fresh?(intent_dir, artifact, ttl: Lock::TTL_SECONDS, now: Time.now)
+    p = path(intent_dir, artifact)
+    return false unless File.exist?(p)
+    (now - File.mtime(p)) <= ttl
+  end
+
+  def payload(session:, artifact:, now:, delegate: nil)
+    {
+      "artifact" => artifact,
+      "owner_session" => session.to_s,
+      "acquired_at" => now.utc.iso8601,
+      "delegate" => delegate,
+    }
+  end
+
+  # Atomic acquisition (O_EXCL). Returns a [status, data] pair:
+  #   [:acquired, claim]  created fresh
+  #   [:held, claim]      fresh claim (own or foreign): never idempotently
+  #                       re-granted; the caller backs off or waits
+  #   [:stale, claim]     expired claim: caller may take over (see plastic-lock)
+  #   [:corrupt, nil]     unparseable claim file: caller may repair
+  def acquire_claim(intent_dir, artifact, session:, delegate: nil,
+                     ttl: Lock::TTL_SECONDS, now: Time.now)
+    raise ArgumentError, "claim session must be present" if Lock.blank?(session)
+    raise ArgumentError, "claim artifact must be present" if Lock.blank?(artifact)
+
+    FileUtils.mkdir_p(dir_path(intent_dir))
+    return [:corrupt, nil] if corrupt?(intent_dir, artifact)
+
+    existing = read(intent_dir, artifact)
+    if existing
+      return [:held, existing] if fresh?(intent_dir, artifact, ttl: ttl, now: now)
+      return [:stale, existing]
+    end
+
+    data = payload(session: session, artifact: artifact, now: now, delegate: delegate)
+    File.open(path(intent_dir, artifact),
+              File::WRONLY | File::CREAT | File::EXCL) do |io|
+      io.write(JSON.pretty_generate(data))
+    end
+    [:acquired, data]
+  rescue Errno::EEXIST
+    [:held, read(intent_dir, artifact)] # lost the O_EXCL race
+  end
+
+  # session is the owner or the registered delegate on this claim. Stale-own
+  # still counts as holding (mirrors Lock.holds?): the claim is theirs until
+  # an explicit takeover replaces it; freshness only guards AGAINST others.
+  def holds_claim?(intent_dir, artifact, session:)
+    data = read(intent_dir, artifact)
+    return false unless data.is_a?(Hash)
+    return false if Lock.blank?(session)
+    data["owner_session"].to_s == session.to_s || data["delegate"].to_s == session.to_s
+  end
+
+  # Owner (or force:) releases the claim. Returns :none, :not_owner, or
+  # :released.
+  def release_claim(intent_dir, artifact, session:, force: false)
+    p = path(intent_dir, artifact)
+    return :none unless File.exist?(p)
+    unless force || holds_claim?(intent_dir, artifact, session: session)
+      return :not_owner
+    end
+    File.delete(p)
+    :released
+  end
+
+  # Owner/delegate heartbeat: touch the mtime, never rewrite content. False
+  # (no-op) when the session does not hold the claim.
+  def heartbeat(intent_dir, artifact, session:, now: Time.now)
+    return false unless holds_claim?(intent_dir, artifact, session: session)
+    FileUtils.touch(path(intent_dir, artifact), mtime: now)
+    true
+  end
+
+  # The named fail-open contract (intent 111 D6; intent 112 gates its Exec on
+  # this test and re-runs it as a regression check on every lock.rb edit it
+  # makes). True iff a claim FILE exists but is unresolvable (stale or
+  # corrupt): the write must PROCEED (yield the claim to the current writer)
+  # and surface the condition; it MUST NEVER block. Absence of a claim is not
+  # fail-open, that is plain dormancy (the gate is not engaged at all).
+  def fail_open?(intent_dir, artifact, ttl: Lock::TTL_SECONDS, now: Time.now)
+    return true if corrupt?(intent_dir, artifact)
+    !!(read(intent_dir, artifact) && !fresh?(intent_dir, artifact, ttl: ttl, now: now))
+  end
+
+  # The data behind `plastic-lock status` (AC5): every live claim under this
+  # intent, with enough to show who holds what since when, and whether it is
+  # still fresh. Returns [] when no artifact has ever been claimed.
+  def claims_status(intent_dir, ttl: Lock::TTL_SECONDS, now: Time.now)
+    return [] unless Dir.exist?(dir_path(intent_dir))
+    Dir.glob(File.join(dir_path(intent_dir), "*.claim")).sort.map do |file|
+      artifact = File.basename(file, ".claim")
+      data = begin
+        parsed = JSON.parse(File.read(file))
+        parsed.is_a?(Hash) ? parsed : nil
+      rescue JSON::ParserError
+        nil
+      end
+      {
+        "artifact" => (data && data["artifact"]) || artifact,
+        "owner_session" => data && data["owner_session"],
+        "delegate" => data && data["delegate"],
+        "acquired_at" => data && data["acquired_at"],
+        "fresh" => fresh?(intent_dir, artifact, ttl: ttl, now: now),
+        "corrupt" => data.nil?,
+      }
+    end
+  end
+
+  # Second, independent write gate at the artifact grain (intent 111 D7). Returns a
+  # deny reason String to BLOCK, or nil to ALLOW. Composes UNDER the delivery-lock
+  # gate: only reached after the session already holds the intent's delivery lock.
+  # ENGAGES only when a claim file exists (dormant otherwise, so single-owner flows
+  # and the existing suite stay green, AC7). Fails open on stale/corrupt via
+  # fail_open?, the named contract.
+  def claim_gate_reason(intent_dir, artifact, session:, ttl: Lock::TTL_SECONDS, now: Time.now)
+    return nil if Lock.blank?(artifact)
+    return nil unless File.exist?(path(intent_dir, artifact))   # dormant: no claim
+    return nil if holds_claim?(intent_dir, artifact, session: session)  # you hold it
+    return nil if fail_open?(intent_dir, artifact, ttl: ttl, now: now)  # stale/corrupt: yield
+    data = read(intent_dir, artifact)
+    holder = data && data["owner_session"]
+    since = data && data["acquired_at"]
+    "artifact #{artifact} is claimed by #{holder} since #{since}; another writer holds " \
+      "it. Back off or run /plastic-lock status. If you are a distinct delegate, the " \
+      "owner must register you: plastic-lock delegate --intent-dir #{intent_dir} " \
+      "--session <your-session-id>"
+  end
+end

package/scripts/plastic-lock

@@ -2,18 +2,24 @@
 # encoding: UTF-8
 # frozen_string_literal: true
 #
-# plastic-lock: inspect and repair the durable delivery lock (intent 108, D5).
+# plastic-lock: inspect and repair the durable delivery lock (intent 108, D5),
+# and take/free per-artifact claim tokens (intent 111 D1/D5).
 #
-# Usage: plastic-lock <status|fix|release|reclaim|delegate>
-#          [--intent-dir DIR] [--session SID] [--delegate SID]
+# Usage: plastic-lock <status|fix|release|reclaim|delegate|claim|release-claim>
+#          [--intent-dir DIR] [--session SID] [--delegate SID] [--artifact NAME]
 #
 # Verbs:
-#   status   report the lock file, the bridge cache, and their agreement
-#   fix      idempotent repair: rebuild lock + bridge from disk truth for the
-#            current session; never touches a fresh foreign lock
-#   release  owner clears the lock (End tail / abandoning a boarding)
-#   reclaim  explicit takeover of a stale lock, audited in savepoint.md
-#   delegate owner registers a subagent session under the lock (D4)
+#   status        report the lock file, the bridge cache, their agreement,
+#                 and any live per-artifact claims
+#   fix           idempotent repair: rebuild lock + bridge from disk truth for
+#                 the current session; never touches a fresh foreign lock
+#   release       owner clears the lock (End tail / abandoning a boarding)
+#   reclaim       explicit takeover of a stale lock, audited in savepoint.md
+#   delegate      owner registers a subagent session under the lock (D4)
+#   claim         acquire the named --artifact's claim token (intent 111);
+#                 rejected (exit 1) while a fresh claim is held by anyone,
+#                 including this same session; takes over a stale claim
+#   release-claim free the named --artifact's claim token
 #
 # Without --intent-dir the intent is resolved from this session's bridge.
 # Exit 0 on success/report; exit 1 when the verb is blocked (held elsewhere).
@@ -23,13 +29,13 @@ require_relative "lib/bridge"
 require_relative "lib/lock"
 
 def usage!
-  warn "usage: plastic-lock <status|fix|release|reclaim|delegate> " \
-       "[--intent-dir DIR] [--session SID] [--delegate SID]"
+  warn "usage: plastic-lock <status|fix|release|reclaim|delegate|claim|release-claim> " \
+       "[--intent-dir DIR] [--session SID] [--delegate SID] [--artifact NAME]"
   exit 1
 end
 
 verb = ARGV.shift
-usage! unless %w[status fix release reclaim delegate].include?(verb)
+usage! unless %w[status fix release reclaim delegate claim release-claim].include?(verb)
 
 opts = {}
 until ARGV.empty?
@@ -37,6 +43,7 @@ until ARGV.empty?
   when "--intent-dir" then opts[:dir] = ARGV.shift
   when "--session" then opts[:session] = ARGV.shift
   when "--delegate" then opts[:delegate] = ARGV.shift
+  when "--artifact" then opts[:artifact] = ARGV.shift
   else
     warn "unknown flag #{flag}"
     usage!
@@ -75,6 +82,7 @@ when "status"
     "bridge_present" => !bridge.nil?,
     "agreement" => (lock && bridge) ?
       (lock["owner_session"] == bridge.dig("lock", "owner_session")) : nil,
+    "claims" => Claim.claims_status(dir),
   }
   puts JSON.pretty_generate(report)
 when "fix"
@@ -117,4 +125,40 @@ when "delegate"
     exit 1
   end
   puts "delegated #{opts[:delegate]} under #{key}"
+when "claim"
+  usage! if opts[:artifact].nil?
+  status, data = Claim.acquire_claim(dir, opts[:artifact], session: key,
+                                     delegate: opts[:delegate])
+  case status
+  when :acquired
+    puts "claimed #{opts[:artifact]} under #{key}"
+  when :held
+    warn "plastic-lock: #{opts[:artifact]} is claimed by " \
+         "#{data['owner_session']} since #{data['acquired_at']}; back off"
+    exit 1
+  when :stale
+    old = data && data["owner_session"]
+    Claim.release_claim(dir, opts[:artifact], session: key, force: true)
+    status2, = Claim.acquire_claim(dir, opts[:artifact], session: key,
+                                   delegate: opts[:delegate])
+    if status2 == :acquired
+      warn "plastic-lock: took over stale claim on #{opts[:artifact]} from #{old}"
+      puts "claimed #{opts[:artifact]} under #{key}"
+    else
+      warn "plastic-lock: could not take over #{opts[:artifact]} (#{status2})"
+      exit 1
+    end
+  when :corrupt
+    Claim.release_claim(dir, opts[:artifact], session: key, force: true)
+    Claim.acquire_claim(dir, opts[:artifact], session: key, delegate: opts[:delegate])
+    puts "claimed #{opts[:artifact]} under #{key} (repaired corrupt claim)"
+  end
+when "release-claim"
+  usage! if opts[:artifact].nil?
+  result = Claim.release_claim(dir, opts[:artifact], session: key)
+  if result == :not_owner
+    warn "plastic-lock: not the claim owner; run plastic-lock status"
+    exit 1
+  end
+  puts "released-claim #{opts[:artifact]} (#{result})"
 end