tegwick
49b7458dfe
Adds the governing intent, the R-1 contract and descriptor, the adapter's connector contract, the observation and redaction configuration, a runbook, and the seed evidence for the first experiment: a measured pressure record and two competing hypotheses about how a long hall entry should reach a reader. The interface is declared at FLUID-2 deliberately. It publishes under HelixForge's name to an audience that did not consent to being experimented on carelessly, and the cost of a bad post is reputational rather than recoverable. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014KmVxhJ35tCo7rE7UnLwWu Assistant: claude-code Assistant-Model: opus Assistant-Process: 1116572@bnt-lap001 Assistant-Session: 8ba9bb93-a72a-4883-b189-2499cce5c400
103 lines
3.3 KiB
YAML
103 lines
3.3 KiB
YAML
openapi: "3.1.0"
|
|
info:
|
|
title: HelixForge Telegram Publishing
|
|
version: "R-1"
|
|
description: |
|
|
Publishes hall-of-helix entries to a Telegram channel.
|
|
|
|
The interface takes an entry as it was written and is responsible for
|
|
everything about how it becomes a Telegram post. A caller should never need
|
|
to know Telegram's constraints.
|
|
|
|
Publication is idempotent on entry_id: publishing the same entry twice
|
|
yields one publication. This matters because the caller is usually
|
|
automation that may be retried.
|
|
|
|
paths:
|
|
/v1/hall-entries:
|
|
post:
|
|
operationId: publishEntry
|
|
summary: Publish a hall-of-helix entry
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required: [entry_id, title, body]
|
|
additionalProperties: false
|
|
properties:
|
|
entry_id:
|
|
type: string
|
|
minLength: 1
|
|
maxLength: 128
|
|
description: |
|
|
The hall entry's own id, from its frontmatter. Publication
|
|
is idempotent on this value.
|
|
title:
|
|
type: string
|
|
minLength: 1
|
|
maxLength: 256
|
|
body:
|
|
type: string
|
|
minLength: 1
|
|
description: |
|
|
The entry body as Markdown, frontmatter removed.
|
|
|
|
Deliberately unbounded. Telegram's 4096-character message
|
|
limit is this interface's problem, not the caller's, and a
|
|
maxLength here would push it back onto them.
|
|
display_name:
|
|
type: string
|
|
maxLength: 128
|
|
worker_kind:
|
|
type: string
|
|
enum: [human, agent-session]
|
|
recorded_at:
|
|
type: string
|
|
format: date
|
|
source_url:
|
|
type: string
|
|
description: Canonical location of the entry in hall-of-helix.
|
|
responses:
|
|
"201":
|
|
description: Published
|
|
"200":
|
|
description: Already published; the existing publication is returned
|
|
"400":
|
|
description: The entry cannot be published faithfully
|
|
"502":
|
|
description: Telegram was unreachable or refused the message
|
|
|
|
get:
|
|
operationId: listPublications
|
|
summary: List publications, newest first
|
|
parameters:
|
|
- name: limit
|
|
in: query
|
|
required: false
|
|
schema: {type: integer, minimum: 1, maximum: 100}
|
|
- name: state
|
|
in: query
|
|
required: false
|
|
schema:
|
|
type: string
|
|
enum: [pending, published, failed, superseded]
|
|
responses:
|
|
"200":
|
|
description: Publications
|
|
|
|
/v1/hall-entries/{entry_id}:
|
|
get:
|
|
operationId: getPublication
|
|
summary: Publication state for one entry
|
|
parameters:
|
|
- name: entry_id
|
|
in: path
|
|
required: true
|
|
schema: {type: string, minLength: 1}
|
|
responses:
|
|
"200":
|
|
description: Publication state
|
|
"404":
|
|
description: This entry has not been published
|