Module: Textus::Lanes::Scratchpad::Handlers

Defined in:
lib/textus/lanes/scratchpad/handlers.rb

Constant Summary collapse

PROPOSALS_PARENT_KEY = 
"scratchpad.proposals"
SESSION_PARENT_KEY = 
"scratchpad.sessions"

Class Method Summary collapse

Class Method Details

.accept(pending_key:, ctx:, call:, dry_run: false) ⇒ Object

Raises:



46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
 
# File 'lib/textus/lanes/scratchpad/handlers.rb', line 46

def accept(pending_key:, ctx:, call:, dry_run: false)
  env = ctx.read(key: pending_key)
  proposal = env&.meta&.dig("proposal")
  raise Textus::ProposalError.new("entry has no proposal block: #{pending_key}") unless proposal

  target = proposal["target_key"]
  raise Textus::ProposalError.new("proposal missing target_key") unless target

  action = proposal["action"] || "put"

  if dry_run
    target_env = ctx.read(key: target)
    body_diff = Textus::Protocol::Diff.body(target_env&.body, env.body)
    meta_diff = Textus::Protocol::Diff.meta(target_env&.meta&.dig("_meta") || {}, env.meta&.dig("_meta") || {})
    result = { "dry_run" => true, "pending_key" => pending_key, "target_key" => target, "action" => action }
    result["body"] = body_diff if body_diff
    result["meta"] = meta_diff if meta_diff
    result["summary"] = Textus::Protocol::Diff.summary(result)
    return result
  end

  case action
  when "put"
    target_meta = env.meta.to_h.except("proposal")

    # Parse body frontmatter to extract schema-relevant meta fields
    resolution = ctx.manifest.resolver.resolve(target)
    if env.body && !env.body.empty?
      parsed = Textus::Protocol::Format.for(resolution.entry.format).parse(env.body)
      body_meta = parsed["_meta"] || {}
      target_meta = body_meta.merge(target_meta)
    end

    # Re-validate constraints at promotion time
    payload = Textus::Value::Payload.new(meta: target_meta, body: env.body, content: env.content)
    Textus::Protocol::EntryConstraint.validate_naming!(target, resolution.entry)
    Textus::Protocol::EntryConstraint.validate_schema!(payload, resolution.entry, schemas: ctx.schemas)
    Textus::Protocol::EntryConstraint.validate_format!(payload, resolution.entry)

    ctx.put(key: target, meta: target_meta, body: env.body, content: env.content, call:)
  when "delete"
    ctx.delete(key: target, call:)
  else
    raise Textus::ProposalError.new("unknown action: #{action}")
  end

  ctx.delete(key: pending_key, call:)
  { "protocol" => Textus::PROTOCOL, "accepted" => pending_key,
    "target_key" => target, "action" => action, "cascade_key" => target }
end

.diff(pending_key:, ctx:, call:) ⇒ Object

Raises:



109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
 
# File 'lib/textus/lanes/scratchpad/handlers.rb', line 109

def diff(pending_key:, ctx:, call:)
  env = ctx.read(key: pending_key)
  proposal = env&.meta&.dig("proposal")
  raise Textus::ProposalError.new("entry has no proposal block: #{pending_key}") unless proposal

  target_key = proposal["target_key"]
  raise Textus::ProposalError.new("proposal missing target_key") unless target_key

  target_env = ctx.read(key: target_key)

  body_diff = Textus::Protocol::Diff.body(target_env&.body, env.body)
  meta_diff = Textus::Protocol::Diff.meta(target_env&.meta&.dig("_meta") || {}, env.meta&.dig("_meta") || {})

  entry = ctx.manifest.data.entries.find { |e| e.key == target_key }
  target_schema = entry&.schema_ref
  proposal_schema = env&.meta&.dig("_meta", "schema")
  schema_diff = nil
  if proposal_schema && target_schema != proposal_schema
    schema_diff = Textus::Protocol::Diff.schema({ "schema" => target_schema }, { "schema" => proposal_schema })
  end

  result = { "pending_key" => pending_key, "target_key" => target_key }
  result["body"] = body_diff if body_diff
  result["meta"] = meta_diff if meta_diff
  result["schema"] = schema_diff if schema_diff
  result["summary"] = Textus::Protocol::Diff.summary(result)
  result
end

.parent_mentry(ctx) ⇒ Object 



28
29
30
 
# File 'lib/textus/lanes/scratchpad/handlers.rb', line 28

def parent_mentry(ctx)
  ctx.manifest.data.entries.find { |e| e.key == SESSION_PARENT_KEY }
end

.propose(key:, ctx:, call:, meta: nil, data: nil) ⇒ Object 



32
33
34
35
36
37
38
39
40
41
42
43
44
 
# File 'lib/textus/lanes/scratchpad/handlers.rb', line 32

def propose(key:, ctx:, call:, meta: nil, data: nil)
  body, content = data.is_a?(Hash) ? [nil, data] : [data, nil]

  target_key = meta&.dig("proposal", "target_key")
  if target_key
    resolution = ctx.manifest.resolver.resolve(target_key)
    Textus::Protocol::EntryConstraint.validate_naming!(target_key, resolution.entry)
  end

  full_key = "#{PROPOSALS_PARENT_KEY}.#{key}"
  env = ctx.put(key: full_key, meta: meta || {}, body:, content:, call:)
  env.to_h_for_wire
end

.reject(pending_key:, ctx:, call:, reason: nil) ⇒ Object

Raises:



97
98
99
100
101
102
103
104
105
106
107
 
# File 'lib/textus/lanes/scratchpad/handlers.rb', line 97

def reject(pending_key:, ctx:, call:, reason: nil)
  env = ctx.read(key: pending_key)
  proposal = env&.meta&.dig("proposal")
  raise Textus::ProposalError.new("entry has no proposal block: #{pending_key}") unless proposal

  target_key = proposal["target_key"]
  ctx.delete(key: pending_key, call:)
  result = { "protocol" => Textus::PROTOCOL, "rejected" => pending_key, "target_key" => target_key }
  result["reason"] = reason if reason
  result
end

.session_close(session_id:, ctx:, call:, nodes_checked: nil) ⇒ Object

Raises:



138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
 
# File 'lib/textus/lanes/scratchpad/handlers.rb', line 138

def session_close(session_id:, ctx:, call:, nodes_checked: nil)
  key = "scratchpad.sessions.#{session_id}.session"
  env = ctx.read(key:)
  raise Textus::UsageError.new("session not found: #{session_id}") unless env

  current = JSON.parse(env.body || "{}")
  content = current.merge("status" => "sealed", "closed_at" => Time.now.utc.iso8601)
  ctx.put(key:, meta: {}, body: JSON.generate(content), content: nil, call:)

  feedback_key = "scratchpad.sessions.#{session_id}.feedback"
  duration = current["created_at"] ? "#{((Time.now.utc - Time.parse(current["created_at"])) / 60).round}m" : "unknown"
  feedback = {
    "node" => "feedback",
    "confidence" => "medium",
    "signal" => "session_closed",
    "summary" => "Session #{session_id[0..8]} sealed after #{duration}. " \
                 "Created at #{current["created_at"]}, closed at #{Time.now.utc.iso8601}.",
  }
  feedback["nodes_checked"] = nodes_checked if nodes_checked
  ctx.put(key: feedback_key, meta: {}, body: JSON.generate(feedback), content: nil, call:)

  { "session_id" => session_id, "status" => "sealed", "feedback_key" => feedback_key }
end

.session_open(ctx:, call:) ⇒ Object 



11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
 
# File 'lib/textus/lanes/scratchpad/handlers.rb', line 11

def session_open(ctx:, call:)
  uuid = SecureRandom.uuid
  key = "scratchpad.sessions.#{uuid}.session"

  content = { "session_id" => uuid, "created_at" => Time.now.utc.iso8601, "status" => "active" }
  ctx.put(key:, meta: {}, body: JSON.generate(content), content: nil, call:)

  boot = begin
    Textus::Protocol::Boot.build(container: ctx.container)
  rescue StandardError
    nil
  end
  result = { "session_id" => uuid, "status" => "active" }
  result["boot"] = boot if boot
  result
end