pinaxclient

package
v0.3.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 31, 2026 License: MIT Imports: 26 Imported by: 0

Documentation

Index

Constants

View Source
const (
	CodeInvalidConfig           = "invalid_config"
	CodeRequestInvalid          = "request_invalid"
	CodeRequestFailed           = "request_failed"
	CodeRedirectRejected        = "redirect_rejected"
	CodeResponseTooLarge        = "response_too_large"
	CodeTokenFileInvalid        = "token_file_invalid"
	CodeTokenFileTooLarge       = "token_file_too_large"
	CodeTokenFileUnsafe         = "token_file_unsafe"
	CodeTokenFileUnreadable     = "token_file_unreadable"
	CodeUpstreamInvalidResponse = "upstream_invalid_response"
	CodeMutationOutcomeUnknown  = "mutation_outcome_unknown"
	CodeReconcileRequired       = "reconcile_required"
)
View Source
const (
	ReaderSourceSchemaV1Alpha1        = catalogschema.ReaderSourceV1Alpha1
	ReaderDocumentSchemaV1Alpha1      = catalogschema.ReaderDocumentV1Alpha1
	ReaderNoteListSchemaV1Alpha1      = catalogschema.ReaderNoteListV1Alpha1
	ReaderSearchResultsSchemaV1Alpha1 = catalogschema.ReaderSearchResultsV1Alpha1
	ReaderLinkPageSchemaV1Alpha1      = catalogschema.ReaderLinkPageV1Alpha1
	ReaderAssetRefSchemaV1Alpha1      = catalogschema.ReaderAssetRefV1Alpha1
	ReaderSourceExportSchemaV1Alpha1  = catalogschema.ReaderSourceExportV1Alpha1
)
View Source
const (
	ReaderTagsSchemaV1Alpha1  = catalogschema.ReaderTagsV1Alpha1
	ReaderGraphSchemaV1Alpha1 = catalogschema.ReaderGraphV1Alpha1
	ReaderDailySchemaV1Alpha1 = catalogschema.ReaderDailyV1Alpha1
)
View Source
const (
	ProjectionSpecVersion       = "1.0"
	TransportManifestSchemaV1   = "pinax.transport_manifest.v1"
	ConnectionReadinessSchemaV1 = "pinax.connection_readiness.v1"
	OperationSchemaV1           = "pinax.operation.v1"

	ReadinessLayerContract         = "contract"
	ReadinessLayerTransport        = "transport"
	ReadinessLayerAuth             = "auth"
	ReadinessLayerOwner            = "owner"
	ReadinessLayerMutationRecovery = "mutation_recovery"
	ReadinessLayerProduction       = "production"
)
View Source
const (
	WriterProposalPreviewSchemaV1Alpha1      = catalogschema.WriterProposalPreviewV1Alpha1
	WriterApplyReceiptSchemaV1Alpha1         = catalogschema.WriterApplyReceiptV1Alpha1
	WriterCaptureReceiptSchemaV1Alpha1       = catalogschema.WriterCaptureReceiptV1Alpha1
	WriterOrganizePlanSchemaV1Alpha1         = catalogschema.WriterOrganizePlanV1Alpha1
	WriterOrganizeApplyReceiptSchemaV1Alpha1 = catalogschema.WriterOrganizeApplyReceiptV1Alpha1
)
View Source
const WriterDailyProposalSchemaV1Alpha1 = catalogschema.WriterDailyProposalV1Alpha1
View Source
const WriterEditorSourceSchemaV1Alpha1 = catalogschema.WriterEditorSourceV1Alpha1

Variables

This section is empty.

Functions

func LoadTokenFile

func LoadTokenFile(tokenPath string) (string, error)

LoadTokenFile reads one plaintext bearer token from an owner-only file. The path must be absolute, every path component must be non-symlink, and the platform-specific owner/access policy must pass before any bytes are returned. Errors intentionally omit both the path and file contents.

func ReadinessLayerNames

func ReadinessLayerNames() []string

ReadinessLayerNames returns the required v1 layer names without exposing mutable package state.

Types

type Action

type Action struct {
	Name    string `json:"name"`
	Command string `json:"command"`
}

type Client

type Client struct {
	// contains filtered or unexported fields
}

func New

func New(config Config) (*Client, error)

func (*Client) CallMutationRPC

func (c *Client) CallMutationRPC(ctx context.Context, request RPCRequest, identity MutationIdentity) (Projection, error)

CallMutationRPC executes one recovery-enabled RPC mutation. Ambiguous transport outcomes are resolved through the durable operation first; the original request is retried at most once and only when the owner reports a terminal failed operation that is both retryable and replay-safe.

func (*Client) CallRPC

func (c *Client) CallRPC(ctx context.Context, request RPCRequest) (Projection, error)

func (*Client) Capabilities

func (c *Client) Capabilities(ctx context.Context) (Projection, error)

Capabilities reads the legacy capabilities projection. The authoritative transport inventory remains Manifest; this method is retained for clients that still consume the additive legacy capability fields.

func (*Client) FolderRename added in v0.3.1

func (c *Client) FolderRename(ctx context.Context, request FolderRenameRequest, identity MutationIdentity) (Projection, error)

FolderRename executes Pinax.Folder.Rename through the recovery-aware RPC path. It never falls back to a local filesystem mutation.

func (*Client) InboxCapture added in v0.3.1

func (c *Client) InboxCapture(ctx context.Context, request InboxCaptureRequest, identity MutationIdentity) (Projection, error)

InboxCapture executes Pinax.Inbox.Capture through the recovery-aware RPC path. The same identity must be retained if the transport result is ambiguous.

func (*Client) Manifest

func (c *Client) Manifest(ctx context.Context) (Manifest, error)

func (*Client) Operation

func (c *Client) Operation(ctx context.Context, operationID string) (Operation, error)

func (*Client) OperationGet added in v0.3.1

func (c *Client) OperationGet(ctx context.Context, operationID string) (Operation, error)

OperationGet is the explicit typed SDK name for the remote operation.show recovery surface. Operation remains as a backwards-compatible shorthand.

func (*Client) OperationReconcile added in v0.3.1

func (c *Client) OperationReconcile(ctx context.Context, operationID string) (Operation, error)

OperationReconcile is the explicit typed SDK name for the remote operation.reconcile recovery surface. ReconcileOperation remains as a backwards-compatible shorthand.

func (*Client) Ping

func (c *Client) Ping(ctx context.Context) (Projection, error)

Ping reads the owner root projection.

func (*Client) ReaderAsset

func (c *Client) ReaderAsset(ctx context.Context, assetRef, noteID, noteRevision string) (ReaderAssetContent, error)

ReaderAsset reads one bounded asset body bound to a note revision. Use ReaderAssetRange for content above the per-request byte window.

func (*Client) ReaderAssetRange

func (c *Client) ReaderAssetRange(ctx context.Context, assetRef, noteID, noteRevision string, rng ReaderByteRange) (ReaderAssetContent, error)

ReaderAssetRange reads one explicit byte window of an asset (206) or, with an empty range, the whole body when it fits the window budget (200).

func (*Client) ReaderComposedDocument added in v0.3.1

func (c *Client) ReaderComposedDocument(ctx context.Context, req ReaderDocumentRequest) (ReaderComposedDocumentPage, error)

ReaderComposedDocument returns inert, provenance-bound page data. It does not grant asset access, execute annotations or reconstruct writable source.

func (*Client) ReaderDaily added in v0.3.1

func (c *Client) ReaderDaily(ctx context.Context, date, timezone string) (ReaderDaily, error)

ReaderDaily locates a date; this method never creates a journal.

func (*Client) ReaderDailyDocument added in v0.3.1

func (c *Client) ReaderDailyDocument(ctx context.Context, req ReaderDailyDocumentRequest) (ReaderDocumentPage, error)

func (*Client) ReaderDocument

func (c *Client) ReaderDocument(ctx context.Context, request ReaderDocumentRequest) (ReaderDocumentPage, error)

ReaderDocument reads one bounded document page.

func (*Client) ReaderGraph added in v0.3.1

func (c *Client) ReaderGraph(ctx context.Context, req ReaderGraphRequest) (ReaderGraphPage, error)

ReaderGraph returns a closed graph page: both endpoints of every edge are present. Merge repeated nodes across pages by binding_id and object_id.

func (c *Client) ReaderLinks(ctx context.Context, objectID, revision, direction string, query ReaderPageQuery) (ReaderLinkPage, error)

ReaderLinks lists authorized relation edges for one pinned revision.

func (*Client) ReaderNotes

func (c *Client) ReaderNotes(ctx context.Context, query ReaderPageQuery) (ReaderNoteList, error)

ReaderNotes lists note cards for the authorized session.

func (*Client) ReaderRecoveryLookup added in v0.3.1

func (c *Client) ReaderRecoveryLookup(ctx context.Context, original ReaderRecoveryHandle) (Operation, error)

ReaderRecoveryLookup reads original evidence without retrying, applying or reconciling. A failed read does not establish that a mutation never happened. Result and Receipt remain inert bounded JSON, not executable instructions.

func (*Client) ReaderRichDocument added in v0.3.1

func (c *Client) ReaderRichDocument(ctx context.Context, req ReaderDocumentRequest) (ReaderRichDocumentPage, error)

ReaderRichDocument returns inert data only. Callers must not execute source, inject it as HTML or treat a Mermaid/TeX link as permission to fetch a URL.

func (*Client) ReaderSearch

func (c *Client) ReaderSearch(ctx context.Context, queryText string, query ReaderPageQuery) (ReaderSearchResults, error)

ReaderSearch runs keyword search; the query never leaves this call.

func (*Client) ReaderSource

func (c *Client) ReaderSource(ctx context.Context) (ReaderSourceDescriptor, error)

ReaderSource reads the authorized source descriptor.

func (*Client) ReaderSourceExport

func (c *Client) ReaderSourceExport(ctx context.Context, objectID, revision string) (ReaderSourceExportDescriptor, []byte, error)

ReaderSourceExport downloads the markdown source of a pinned revision. Content above the per-request window must be fetched via ReaderSourceExportRange windows; unknown total sizes can be discovered from the first range reply's Content-Range total.

func (*Client) ReaderSourceExportRange

func (c *Client) ReaderSourceExportRange(ctx context.Context, objectID, revision string, rng ReaderByteRange) (ReaderSourceExportDescriptor, []byte, error)

ReaderSourceExportRange downloads one explicit byte window of the source (206) or, with an empty range, the whole body when it fits (200).

func (*Client) ReaderTags added in v0.3.1

func (c *Client) ReaderTags(ctx context.Context, limit int, cursor string) (ReaderTagsPage, error)

ReaderTags lists one page of the authorized, counted taxonomy projection.

func (*Client) Readiness

func (c *Client) Readiness(ctx context.Context) (ConnectionReadiness, error)

func (*Client) ReconcileOperation

func (c *Client) ReconcileOperation(ctx context.Context, operationID string) (Operation, error)

func (*Client) SyncConflictsDiff added in v0.3.1

func (c *Client) SyncConflictsDiff(ctx context.Context, file string) (Projection, error)

func (*Client) SyncConflictsList added in v0.3.1

func (c *Client) SyncConflictsList(ctx context.Context) (Projection, error)

func (*Client) SyncConflictsResolve added in v0.3.1

func (c *Client) SyncConflictsResolve(ctx context.Context, request SyncConflictRequest) (Projection, error)

func (*Client) SyncDiff added in v0.3.1

func (c *Client) SyncDiff(ctx context.Context, request SyncRequest) (Projection, error)

func (*Client) SyncPull added in v0.3.1

func (c *Client) SyncPull(ctx context.Context, request SyncRequest) (Projection, error)

func (*Client) SyncPush added in v0.3.1

func (c *Client) SyncPush(ctx context.Context, request SyncRequest) (Projection, error)

func (*Client) SyncStatus added in v0.3.1

func (c *Client) SyncStatus(ctx context.Context) (Projection, error)

func (*Client) WriterApply

func (c *Client) WriterApply(ctx context.Context, request WriterApplyRequest) (WriterApplyReceipt, error)

WriterApply saves an unchanged preview. The operation identity is the change's operation id: an ambiguous failure is recovered by re-issuing the SAME apply (the ledger replays), never a fresh identity.

func (*Client) WriterAwaitApply

func (c *Client) WriterAwaitApply(ctx context.Context, request WriterApplyRequest, attempts int, interval time.Duration) (WriterApplyReceipt, error)

WriterAwaitApply polls the SAME apply identity until a terminal receipt, the attempt budget is exhausted, or the context is cancelled. Polling never fabricates a fresh identity. A non-terminal receipt (accepted / applying) keeps polling under the SAME identity until it reaches a terminal status, the budget is exhausted, or the context is cancelled.

func (*Client) WriterCapture

func (c *Client) WriterCapture(ctx context.Context, request WriterCaptureRequest, identity WriterOperationIdentity) (WriterCaptureReceipt, error)

WriterCapture captures a note under a durable identity. On an ambiguous transport failure the SAME identity is re-issued once — the operation ledger replays the original receipt instead of writing twice.

func (*Client) WriterDailyApply added in v0.3.1

func (c *Client) WriterDailyApply(ctx context.Context, preview WriterDailyProposal, authorization string) (WriterApplyReceipt, error)

WriterDailyApply never retries automatically. Preserve the exact preview and original operation after a transport failure; only explicit same-identity replay can recover it in this supervised session.

func (*Client) WriterDailyEditApply added in v0.3.1

func (c *Client) WriterDailyEditApply(ctx context.Context, p WriterDailyEditProposal, authorization string) (WriterApplyReceipt, error)

Apply never automatically retries. Preserve the exact proposal and original operation on unknown outcomes; a new session cannot reuse the old HMAC.

func (*Client) WriterDailyEditPropose added in v0.3.1

func (c *Client) WriterDailyEditPropose(ctx context.Context, req WriterDailyEditRequest) (WriterDailyEditProposal, error)

func (*Client) WriterDailyEditorSource added in v0.3.1

func (c *Client) WriterDailyEditorSource(ctx context.Context, date, timezone, objectID, revision string) (WriterEditorSource, error)

func (*Client) WriterDailyPropose added in v0.3.1

func (c *Client) WriterDailyPropose(ctx context.Context, date, timezone, operationID string) (WriterDailyProposal, error)

func (*Client) WriterEditorSource added in v0.3.1

func (c *Client) WriterEditorSource(ctx context.Context, objectID, revision string) (WriterEditorSource, error)

WriterEditorSource fetches one exact live revision; no export, AST rewrite, mutation, implicit retry or access to owner-local storage is involved.

func (*Client) WriterOrganizeApply

func (c *Client) WriterOrganizeApply(ctx context.Context, request WriterOrganizeApplyRequest) (WriterOrganizeApplyReceipt, error)

WriterOrganizeApply applies a saved plan id as-is. Organize plans are consumed by apply, so an ambiguous outcome is NOT auto-retried: the receipt/error tells the host to inspect the plan id instead.

func (*Client) WriterOrganizePlan

func (c *Client) WriterOrganizePlan(ctx context.Context, noteRefs []string) (WriterOrganizePlan, error)

WriterOrganizePlan generates a saved organize plan; noteRefs scopes the plan to exactly those objects, empty means the whole vault.

func (*Client) WriterPropose

func (c *Client) WriterPropose(ctx context.Context, change WriterChange) (WriterProposalPreview, error)

WriterPropose prepares an edit proposal without writing.

func (*Client) WriterTagsApply added in v0.3.1

func (c *Client) WriterTagsApply(ctx context.Context, plan WriterTagsPlan, authorization string) (WriterTagsReceipt, error)

Apply never retries. Ambiguous outcomes preserve the parent operation ID; recover with WriterTagsLookup rather than automatically resubmitting.

func (*Client) WriterTagsLookup added in v0.3.1

func (c *Client) WriterTagsLookup(ctx context.Context, operationID string) (WriterTagsReceipt, error)

func (*Client) WriterTagsPlan added in v0.3.1

func (c *Client) WriterTagsPlan(ctx context.Context, req WriterTagsPlanRequest) (WriterTagsPlan, error)

type CommandError

type CommandError struct {
	Code    string `json:"code"`
	Message string `json:"message"`
	Hint    string `json:"hint,omitempty"`
}

type Config

type Config struct {
	BaseURL          string
	Token            string
	TokenFile        string
	HTTPClient       *http.Client
	Timeout          time.Duration
	MaxRequestBytes  int64
	MaxResponseBytes int64
}

type ConnectionReadiness

type ConnectionReadiness struct {
	SchemaVersion string               `json:"schema_version"`
	Overall       Readiness            `json:"overall"`
	Layers        map[string]Readiness `json:"layers"`
}

type Error

type Error struct {
	Code              string `json:"code"`
	Message           string `json:"message"`
	HTTPStatus        int    `json:"http_status,omitempty"`
	Retryable         bool   `json:"retryable"`
	RequiredAction    string `json:"required_action,omitempty"`
	RequestID         string `json:"request_id,omitempty"`
	OperationRef      string `json:"operation_ref,omitempty"`
	ReconcileRequired bool   `json:"reconcile_required"`
	// Facts and Actions carry the machine-recoverable recovery contract
	// (e.g. the fixed revision, source size and source-export action of a
	// 413 document budget error) so consumers can follow it programmatically.
	Facts   map[string]string `json:"facts,omitempty"`
	Actions []Action          `json:"actions,omitempty"`
	// contains filtered or unexported fields
}

func (*Error) Error

func (e *Error) Error() string

func (*Error) Unwrap

func (e *Error) Unwrap() error

type FolderRenameRequest added in v0.3.1

type FolderRenameRequest struct {
	Path             string
	TargetPath       string
	ExpectedRevision string
	DryRun           bool
	Yes              bool
	OperationID      string
	IdempotencyKey   string
}

FolderRenameRequest is the revision-bound remote folder rename payload.

type InboxCaptureRequest added in v0.3.1

type InboxCaptureRequest struct {
	Title          string
	Body           string
	Tags           []string
	Slug           string
	DryRun         bool
	Yes            bool
	OperationID    string
	IdempotencyKey string
}

InboxCaptureRequest is the bounded remote inbox capture payload. The owner still enforces write mode, approval and operation identity at the API.

type Manifest

type Manifest struct {
	SchemaVersion string               `json:"schema_version"`
	Digest        string               `json:"digest"`
	Capabilities  []ManifestCapability `json:"capabilities"`
}

type ManifestCapability

type ManifestCapability struct {
	ID                  string             `json:"id"`
	Command             string             `json:"command"`
	ReleaseCore         bool               `json:"release_core"`
	Readonly            bool               `json:"readonly"`
	BodyAllowed         bool               `json:"body_allowed"`
	ApprovalRequired    bool               `json:"approval_required"`
	SnapshotRequired    bool               `json:"snapshot_required"`
	UIGroup             string             `json:"ui_group,omitempty"`
	BodyExposureDefault string             `json:"body_exposure_default,omitempty"`
	WriteGate           string             `json:"write_gate,omitempty"`
	CopyCommand         string             `json:"copy_command,omitempty"`
	LocalOnlyReason     string             `json:"local_only_reason,omitempty"`
	ExecutionLocation   string             `json:"execution_location,omitempty"`
	WriteStrategy       string             `json:"write_strategy,omitempty"`
	Recovery            *RecoveryContract  `json:"recovery,omitempty"`
	OwnerAction         *OwnerAction       `json:"owner_action,omitempty"`
	RequestSchema       string             `json:"request_schema"`
	ResponseSchema      string             `json:"response_schema"`
	Errors              []string           `json:"errors,omitempty"`
	Stability           string             `json:"stability"`
	DeclaredSurfaces    []string           `json:"declared_surfaces,omitempty"`
	AvailableSurfaces   []string           `json:"available_surfaces,omitempty"`
	Bindings            []TransportBinding `json:"bindings,omitempty"`
}

type MutationIdentity

type MutationIdentity struct {
	OperationID    string `json:"operation_id"`
	IdempotencyKey string `json:"idempotency_key"`
}

func NewMutationIdentity

func NewMutationIdentity() (MutationIdentity, error)

NewMutationIdentity creates the stable pair a client must retain across retries of one logical mutation. The owner binds both values to the request digest and authenticated owner scope.

type Operation

type Operation struct {
	SchemaVersion     string          `json:"schema_version"`
	OperationID       string          `json:"operation_id"`
	CapabilityID      string          `json:"capability_id"`
	BindingID         string          `json:"binding_id"`
	IdempotencyKey    string          `json:"idempotency_key,omitempty"`
	RequestDigest     string          `json:"request_digest,omitempty"`
	Status            string          `json:"status"`
	Retryable         bool            `json:"retryable"`
	ReplaySafe        bool            `json:"replay_safe"`
	ReconcileRequired bool            `json:"reconcile_required"`
	RequiredAction    string          `json:"required_action,omitempty"`
	Result            json.RawMessage `json:"result,omitempty"`
	Receipt           json.RawMessage `json:"receipt,omitempty"`
	ReceiptRef        string          `json:"receipt_ref,omitempty"`
	ResourceRef       string          `json:"resource_ref,omitempty"`
	RevisionBefore    string          `json:"revision_before,omitempty"`
	RevisionAfter     string          `json:"revision_after,omitempty"`
	Error             *CommandError   `json:"error,omitempty"`
	CreatedAt         string          `json:"created_at"`
	UpdatedAt         string          `json:"updated_at"`
	AcceptedAt        string          `json:"accepted_at"`
	ApplyingAt        string          `json:"applying_at,omitempty"`
	CompletedAt       string          `json:"completed_at,omitempty"`
}

type OwnerAction added in v0.3.1

type OwnerAction struct {
	ExecutionLocation string `json:"execution_location"`
	Command           string `json:"command,omitempty"`
	Reason            string `json:"reason,omitempty"`
}

type Projection

type Projection struct {
	SpecVersion string            `json:"spec_version"`
	Mode        string            `json:"mode,omitempty"`
	Command     string            `json:"command"`
	Status      string            `json:"status"`
	Summary     string            `json:"summary,omitempty"`
	Facts       map[string]string `json:"facts,omitempty"`
	Actions     []Action          `json:"actions,omitempty"`
	Evidence    []string          `json:"evidence,omitempty"`
	Data        json.RawMessage   `json:"data,omitempty"`
	Warnings    []Warning         `json:"warnings,omitempty"`
	Error       *CommandError     `json:"error,omitempty"`
	Interaction json.RawMessage   `json:"interaction,omitempty"`
}

type RPCRequest

type RPCRequest struct {
	Method string         `json:"method"`
	Params map[string]any `json:"params,omitempty"`
}

type ReaderAssetContent

type ReaderAssetContent struct {
	Descriptor   ReaderAssetRef
	Body         []byte
	ContentRange string
}

ReaderAssetContent is the resolved asset bytes plus its descriptor. For ranged reads ContentRange carries the server's bytes a-b/total reply.

type ReaderAssetRef

type ReaderAssetRef struct {
	AssetRef     string `json:"asset_ref"`
	Mime         string `json:"mime"`
	SizeBytes    int64  `json:"size_bytes"`
	Digest       string `json:"digest"`
	Availability string `json:"availability"`
}

type ReaderByteRange

type ReaderByteRange struct {
	Start int64
	End   int64
	Set   bool
}

ReaderByteRange selects one inclusive byte window for ranged reads. The zero value (Set=false) means "no Range header": the whole body is requested and must fit the per-request window. Set=true sends the explicit window as-is — including the legal one-byte window {0, 0} (bytes=0-0) — and an out-of-order or negative window fails the call safely instead of silently degrading to a full-body download.

type ReaderComposedDocumentPage added in v0.3.1

type ReaderComposedDocumentPage struct {
	SchemaVersion string                 `json:"schema_version"`
	RichDocument  ReaderRichDocumentPage `json:"rich_document"`
	Embeds        []ReaderEmbed          `json:"embeds"`
	Origins       []ReaderNodeOrigin     `json:"origins"`
}

type ReaderDaily added in v0.3.1

type ReaderDaily struct {
	SchemaVersion string                `json:"schema_version"`
	BindingID     string                `json:"binding_id"`
	Date          string                `json:"date"`
	Timezone      string                `json:"timezone"`
	Status        string                `json:"status"`
	Note          *ReaderNavigationNote `json:"note"`
	Watermark     string                `json:"watermark"`
	ObservedAt    string                `json:"observed_at"`
}

type ReaderDailyDocumentRequest added in v0.3.1

type ReaderDailyDocumentRequest struct {
	Date     string
	Timezone string
	Document ReaderDocumentRequest
}

type ReaderDocumentNode

type ReaderDocumentNode struct {
	Type          string               `json:"type"`
	Anchor        string               `json:"anchor"`
	Text          string               `json:"text,omitempty"`
	Children      []ReaderDocumentNode `json:"children,omitempty"`
	Ref           string               `json:"ref,omitempty"`
	Language      string               `json:"language,omitempty"`
	Alt           string               `json:"alt,omitempty"`
	BlockAnchor   string               `json:"block_anchor,omitempty"`
	FragmentIndex int                  `json:"fragment_index,omitempty"`
	LastFragment  bool                 `json:"last_fragment,omitempty"`
	OriginalType  string               `json:"original_type,omitempty"`
	Header        []string             `json:"header,omitempty"`
	// Fence semantics (owner-registered read-only handlers): the fence
	// name, its bounded payload, and explicit failure diagnostics.
	Fence      string          `json:"fence,omitempty"`
	Payload    json.RawMessage `json:"payload,omitempty"`
	ErrorCode  string          `json:"error_code,omitempty"`
	NextAction string          `json:"next_action,omitempty"`
}

type ReaderDocumentPage

type ReaderDocumentPage struct {
	SchemaVersion   string                  `json:"schema_version"`
	ObjectID        string                  `json:"object_id"`
	Revision        string                  `json:"revision"`
	CurrentRevision string                  `json:"current_revision"`
	URI             string                  `json:"uri"`
	Nodes           []ReaderDocumentNode    `json:"nodes"`
	Outline         []ReaderOutlineEntry    `json:"outline"`
	OutlineCursor   string                  `json:"outline_cursor,omitempty"`
	NextCursor      string                  `json:"next_cursor,omitempty"`
	Complete        bool                    `json:"complete"`
	ContentBytes    int                     `json:"content_bytes"`
	ObservedAt      string                  `json:"observed_at"`
	Warnings        []ReaderDocumentWarning `json:"warnings,omitempty"`
}

type ReaderDocumentRequest

type ReaderDocumentRequest struct {
	ObjectID      string
	Revision      string
	Cursor        string
	Anchor        string
	OutlineCursor string
}

ReaderDocumentRequest selects one page of the human reading projection.

type ReaderDocumentWarning

type ReaderDocumentWarning struct {
	Code    string `json:"code"`
	Message string `json:"message"`
	Hint    string `json:"hint,omitempty"`
}

type ReaderEmbed added in v0.3.1

type ReaderEmbed struct {
	EmbedID       string             `json:"embed_id"`
	ParentEmbedID string             `json:"parent_embed_id"`
	SourceAnchor  string             `json:"source_anchor"`
	PageAnchors   []string           `json:"page_anchors"`
	Depth         int                `json:"depth"`
	Status        string             `json:"status"`
	Target        *ReaderEmbedTarget `json:"target,omitempty"`
}

type ReaderEmbedTarget added in v0.3.1

type ReaderEmbedTarget struct {
	ObjectID string `json:"object_id"`
	Revision string `json:"revision"`
	Anchor   string `json:"anchor,omitempty"`
}

type ReaderGraphEdge added in v0.3.1

type ReaderGraphEdge struct {
	SourceID string `json:"source_id"`
	TargetID string `json:"target_id"`
}

type ReaderGraphPage added in v0.3.1

type ReaderGraphPage struct {
	SchemaVersion string                   `json:"schema_version"`
	BindingID     string                   `json:"binding_id"`
	Mode          string                   `json:"mode"`
	ObjectID      string                   `json:"object_id"`
	Revision      string                   `json:"revision"`
	Hops          int                      `json:"hops"`
	Nodes         []ReaderNavigationNote   `json:"nodes"`
	Edges         []ReaderGraphEdge        `json:"edges"`
	NextCursor    string                   `json:"next_cursor,omitempty"`
	Watermark     string                   `json:"watermark"`
	ObservedAt    string                   `json:"observed_at"`
	TotalNodes    int                      `json:"total_nodes"`
	TotalEdges    int                      `json:"total_edges"`
	Coverage      ReaderNavigationCoverage `json:"coverage"`
}

type ReaderGraphRequest added in v0.3.1

type ReaderGraphRequest struct {
	Mode     string
	ObjectID string
	Revision string
	Hops     int
	Limit    int
	Cursor   string
}

type ReaderIndexState

type ReaderIndexState struct {
	Status     string `json:"status"`
	Watermark  string `json:"watermark"`
	Generation int64  `json:"generation"`
}

type ReaderLimits

type ReaderLimits struct {
	ListDefaultLimit          int `json:"list_default_limit"`
	ListMaxLimit              int `json:"list_max_limit"`
	SnippetMaxChars           int `json:"snippet_max_chars"`
	OutlinePageMaxEntries     int `json:"outline_page_max_entries"`
	DocumentPageMaxTextBytes  int `json:"document_page_max_text_bytes"`
	DocumentPageMaxNodes      int `json:"document_page_max_nodes"`
	DocumentResponseMaxBytes  int `json:"document_response_max_bytes"`
	DocumentSourceMaxBytes    int `json:"document_source_max_bytes"`
	DocumentTotalMaxNodes     int `json:"document_total_max_nodes"`
	AssetRangeMaxBytes        int `json:"asset_range_max_bytes"`
	SourceExportRangeMaxBytes int `json:"source_export_range_max_bytes"`
}

ReaderLimits mirrors the frozen budget block of the source descriptor.

type ReaderLinkItem

type ReaderLinkItem struct {
	ObjectID string `json:"object_id"`
	Revision string `json:"revision,omitempty"`
	Anchor   string `json:"anchor,omitempty"`
}

type ReaderLinkPage

type ReaderLinkPage struct {
	ObjectID           string           `json:"object_id"`
	Revision           string           `json:"revision"`
	Direction          string           `json:"direction"`
	Items              []ReaderLinkItem `json:"items"`
	NextCursor         string           `json:"next_cursor,omitempty"`
	RelationsWatermark string           `json:"relations_watermark"`
	ObservedAt         string           `json:"observed_at"`
}

type ReaderNavigationCoverage added in v0.3.1

type ReaderNavigationCoverage struct {
	PageComplete   bool `json:"page_complete"`
	CorpusComplete bool `json:"corpus_complete"`
}

type ReaderNavigationNote added in v0.3.1

type ReaderNavigationNote struct {
	ObjectID string `json:"object_id"`
	Revision string `json:"revision"`
	Title    string `json:"title"`
}

type ReaderNodeOrigin added in v0.3.1

type ReaderNodeOrigin struct {
	PageAnchor   string `json:"page_anchor"`
	EmbedID      string `json:"embed_id"`
	SourceAnchor string `json:"source_anchor"`
}

type ReaderNoteCard

type ReaderNoteCard struct {
	ObjectID   string   `json:"object_id"`
	Title      string   `json:"title"`
	TitleState string   `json:"title_state,omitempty"`
	Revision   string   `json:"revision"`
	URI        string   `json:"uri"`
	Status     string   `json:"status"`
	ProjectID  *string  `json:"project_id"`
	Tags       []string `json:"tags"`
	UpdatedAt  string   `json:"updated_at"`
}

type ReaderNoteList

type ReaderNoteList struct {
	Items          []ReaderNoteCard `json:"items"`
	NextCursor     string           `json:"next_cursor,omitempty"`
	ObservedAt     string           `json:"observed_at"`
	IndexWatermark string           `json:"index_watermark"`
	IndexState     ReaderIndexState `json:"index_state"`
}

type ReaderOutlineEntry

type ReaderOutlineEntry struct {
	Anchor string `json:"anchor"`
	Title  string `json:"title"`
	Level  int    `json:"level"`
}

type ReaderPageQuery

type ReaderPageQuery struct {
	ProjectID string
	Tags      []string
	Status    string
	Sort      string
	Limit     int
	Cursor    string
}

ReaderPageQuery carries shared pagination controls for typed calls.

type ReaderRecoveryHandle added in v0.3.1

type ReaderRecoveryHandle struct {
	OperationID   string
	CapabilityID  string
	BindingID     string
	RequestDigest string
}

ReaderRecoveryHandle is the original operation identity retained by the caller, not authority to read it. Only OperationID goes over HTTP. Private host approval, current session authentication and grant expiry stay owner-side.

type ReaderRichAnnotation added in v0.3.1

type ReaderRichAnnotation struct {
	Anchor      string   `json:"anchor"`
	PageAnchors []string `json:"page_anchors"`
	Kind        string   `json:"kind"`
	Source      string   `json:"source,omitempty"`
	CalloutKind string   `json:"callout_kind,omitempty"`
	Title       string   `json:"title,omitempty"`
	Fold        string   `json:"fold,omitempty"`
}

type ReaderRichDocumentPage added in v0.3.1

type ReaderRichDocumentPage struct {
	SchemaVersion string                 `json:"schema_version"`
	Document      ReaderDocumentPage     `json:"document"`
	Annotations   []ReaderRichAnnotation `json:"annotations"`
}

type ReaderSearchResults

type ReaderSearchResults struct {
	Items          []ReaderNoteCard      `json:"items"`
	Snippets       []ReaderSearchSnippet `json:"snippets"`
	NextCursor     string                `json:"next_cursor,omitempty"`
	ObservedAt     string                `json:"observed_at"`
	IndexWatermark string                `json:"index_watermark"`
	IndexState     ReaderIndexState      `json:"index_state"`
}

type ReaderSearchSnippet

type ReaderSearchSnippet struct {
	ObjectID string `json:"object_id"`
	Snippet  string `json:"snippet"`
}

type ReaderSourceDescriptor

type ReaderSourceDescriptor struct {
	SchemaVersion string           `json:"schema_version"`
	SessionID     string           `json:"session_id"`
	BindingID     string           `json:"binding_id"`
	DisplayName   string           `json:"display_name"`
	Capabilities  []string         `json:"capabilities"`
	Limits        ReaderLimits     `json:"limits"`
	IndexState    ReaderIndexState `json:"index_state"`
	ObservedAt    string           `json:"observed_at"`
}

type ReaderSourceExportDescriptor

type ReaderSourceExportDescriptor struct {
	ObjectID     string `json:"object_id"`
	Revision     string `json:"revision"`
	MediaType    string `json:"media_type"`
	SizeBytes    int64  `json:"size_bytes"`
	Digest       string `json:"digest"`
	ContentRange string `json:"-"`
}

type ReaderTag added in v0.3.1

type ReaderTag struct {
	TagID           string `json:"tag_id"`
	Path            string `json:"path"`
	ParentID        string `json:"parent_id"`
	Virtual         bool   `json:"virtual"`
	DirectCount     int    `json:"direct_count"`
	DescendantCount int    `json:"descendant_count"`
}

type ReaderTagsPage added in v0.3.1

type ReaderTagsPage struct {
	SchemaVersion string                   `json:"schema_version"`
	BindingID     string                   `json:"binding_id"`
	Items         []ReaderTag              `json:"items"`
	NextCursor    string                   `json:"next_cursor,omitempty"`
	Watermark     string                   `json:"watermark"`
	ObservedAt    string                   `json:"observed_at"`
	TotalTags     int                      `json:"total_tags"`
	Coverage      ReaderNavigationCoverage `json:"coverage"`
}

type Readiness

type Readiness struct {
	Status       string   `json:"status"`
	Maturity     string   `json:"maturity"`
	Blockers     []string `json:"blockers,omitempty"`
	NextActions  []string `json:"next_actions,omitempty"`
	EvidenceRefs []string `json:"evidence_refs,omitempty"`
}

func (Readiness) IsReady

func (r Readiness) IsReady() bool

IsReady returns true only for the stable ready status. Unknown future status values remain available in Status but are deliberately treated as non-ready.

func (Readiness) StatusKnown

func (r Readiness) StatusKnown() bool

type RecoveryContract added in v0.3.1

type RecoveryContract struct {
	IdentityRequired bool   `json:"identity_required,omitempty"`
	StatusCommand    string `json:"status_command,omitempty"`
	ReconcileCommand string `json:"reconcile_command,omitempty"`
}

type SyncConflictRequest added in v0.3.1

type SyncConflictRequest struct {
	Identity   MutationIdentity
	File       string
	KeepLocal  bool
	KeepRemote bool
	MergedPath string
	Yes        bool
}

type SyncRequest added in v0.3.1

type SyncRequest struct {
	Identity       MutationIdentity
	Target         string
	Yes            bool
	DryRun         bool
	BaseRevision   string
	RemoteRevision string
	ContentDiff    bool
}

SyncRequest is the bounded control input shared by the supervised DriveBridge sync panel and the Pinax RPC surface. It contains no vault path, credential, or provider payload.

type TransportBinding

type TransportBinding struct {
	ID                string     `json:"id"`
	CapabilityID      string     `json:"capability_id"`
	Transport         string     `json:"transport"`
	Availability      string     `json:"availability"`
	BackingRef        string     `json:"backing_ref,omitempty"`
	Method            string     `json:"method,omitempty"`
	Path              string     `json:"path,omitempty"`
	ProtocolName      string     `json:"protocol_name,omitempty"`
	Readonly          bool       `json:"readonly"`
	WriteGate         string     `json:"write_gate,omitempty"`
	ExecutionLocation string     `json:"execution_location,omitempty"`
	RequestSchema     string     `json:"request_schema"`
	ResponseSchema    string     `json:"response_schema"`
	Blockers          []string   `json:"blockers,omitempty"`
	Readiness         *Readiness `json:"readiness,omitempty"`
}

type Warning

type Warning struct {
	Code    string `json:"code"`
	Message string `json:"message"`
	Hint    string `json:"hint,omitempty"`
}

type WriterApplyReceipt

type WriterApplyReceipt struct {
	SchemaVersion     string              `json:"schema_version"`
	OperationID       string              `json:"operation_id"`
	CapabilityID      string              `json:"capability_id"`
	BindingID         string              `json:"binding_id"`
	RequestDigest     string              `json:"request_digest,omitempty"`
	Status            string              `json:"status"`
	Retryable         bool                `json:"retryable"`
	ReplaySafe        bool                `json:"replay_safe"`
	ReconcileRequired bool                `json:"reconcile_required"`
	RequiredAction    string              `json:"required_action,omitempty"`
	Result            json.RawMessage     `json:"result,omitempty"`
	Receipt           json.RawMessage     `json:"receipt,omitempty"`
	ReceiptRef        string              `json:"receipt_ref,omitempty"`
	ResourceRef       string              `json:"resource_ref,omitempty"`
	RevisionBefore    string              `json:"revision_before,omitempty"`
	RevisionAfter     string              `json:"revision_after,omitempty"`
	Error             *WriterReceiptError `json:"error,omitempty"`
	CreatedAt         string              `json:"created_at"`
	UpdatedAt         string              `json:"updated_at"`
	AcceptedAt        string              `json:"accepted_at"`
	ApplyingAt        string              `json:"applying_at,omitempty"`
	CompletedAt       string              `json:"completed_at,omitempty"`
}

WriterApplyReceipt is the frozen apply receipt (operation view shape).

func (WriterApplyReceipt) Terminal

func (r WriterApplyReceipt) Terminal() bool

Terminal reports whether the receipt reached a terminal status.

type WriterApplyRequest

type WriterApplyRequest struct {
	Change        WriterChange
	PreviewDigest string
	Authorization string
}

WriterApplyRequest is the apply payload: the resolved change, its unchanged preview digest, and the caller-asserted authorization.

type WriterCaptureReceipt

type WriterCaptureReceipt struct {
	SchemaVersion     string              `json:"schema_version"`
	OperationID       string              `json:"operation_id"`
	CapabilityID      string              `json:"capability_id"`
	BindingID         string              `json:"binding_id"`
	Status            string              `json:"status"`
	Retryable         bool                `json:"retryable"`
	ReplaySafe        bool                `json:"replay_safe"`
	ReconcileRequired bool                `json:"reconcile_required"`
	NoteID            string              `json:"note_id,omitempty"`
	Path              string              `json:"path,omitempty"`
	RecordEventID     string              `json:"record_event_id,omitempty"`
	RevisionAfter     string              `json:"revision_after,omitempty"`
	ResourceRef       string              `json:"resource_ref,omitempty"`
	Error             *WriterReceiptError `json:"error,omitempty"`
	CreatedAt         string              `json:"created_at"`
	UpdatedAt         string              `json:"updated_at"`
	AcceptedAt        string              `json:"accepted_at"`
}

WriterCaptureReceipt is the frozen capture receipt.

type WriterCaptureRequest

type WriterCaptureRequest struct {
	Title string
	Body  string
	Tags  []string
	Slug  string
	Dir   string
}

WriterCaptureRequest is the bounded capture payload.

type WriterChange

type WriterChange struct {
	OperationID      string   `json:"operation_id,omitempty"`
	Action           string   `json:"action"`
	NoteRef          string   `json:"note_ref,omitempty"`
	ExpectedRevision string   `json:"expected_revision,omitempty"`
	Title            string   `json:"title,omitempty"`
	Body             string   `json:"body,omitempty"`
	Dir              string   `json:"dir,omitempty"`
	TargetPath       string   `json:"target_path,omitempty"`
	Tags             []string `json:"tags,omitempty"`
	TagOperation     string   `json:"tag_operation,omitempty"`
	Status           string   `json:"status,omitempty"`
}

WriterChange mirrors the frozen writer change object exactly.

type WriterDailyEditPreview added in v0.3.1

type WriterDailyEditPreview struct {
	Change        WriterChange `json:"change"`
	PreviewDigest string       `json:"preview_digest"`
	Path          string       `json:"path"`
	Before        string       `json:"before"`
	After         string       `json:"after"`
	State         string       `json:"state"`
}

type WriterDailyEditProposal added in v0.3.1

type WriterDailyEditProposal struct {
	SchemaVersion string                 `json:"schema_version"`
	Date          string                 `json:"date"`
	Timezone      string                 `json:"timezone"`
	ObjectID      string                 `json:"object_id"`
	Preview       WriterDailyEditPreview `json:"preview"`
	PreviewDigest string                 `json:"preview_digest"`
}

type WriterDailyEditRequest added in v0.3.1

type WriterDailyEditRequest struct{ Date, Timezone, ObjectID, Revision, OperationID, Body string }

type WriterDailyProposal added in v0.3.1

type WriterDailyProposal struct {
	SchemaVersion        string `json:"schema_version"`
	OperationID          string `json:"operation_id"`
	Date                 string `json:"date"`
	Timezone             string `json:"timezone"`
	ObjectID             string `json:"object_id"`
	Path                 string `json:"path"`
	Title                string `json:"title"`
	Before               string `json:"before"`
	After                string `json:"after"`
	TemplateDigest       string `json:"template_digest"`
	PreviewDigest        string `json:"preview_digest"`
	CreatedAt            string `json:"created_at"`
	BindingID            string `json:"binding_id"`
	FrontmatterProtected bool   `json:"frontmatter_protected"`
}

type WriterEditorBudget added in v0.3.1

type WriterEditorBudget struct {
	MaxSourceBytes int `json:"max_source_bytes"`
	MaxBodyBytes   int `json:"max_body_bytes"`
	SourceBytes    int `json:"source_bytes"`
	BodyBytes      int `json:"body_bytes"`
}

type WriterEditorMetadata added in v0.3.1

type WriterEditorMetadata struct {
	NoteID string   `json:"note_id"`
	Title  string   `json:"title"`
	Tags   []string `json:"tags"`
	Status string   `json:"status"`
	Kind   string   `json:"kind"`
}

type WriterEditorSource added in v0.3.1

type WriterEditorSource struct {
	SchemaVersion        string               `json:"schema_version"`
	ObjectID             string               `json:"object_id"`
	Revision             string               `json:"revision"`
	Body                 string               `json:"body"`
	BodyDigest           string               `json:"body_digest"`
	Editable             bool                 `json:"editable"`
	ReadonlyReason       string               `json:"readonly_reason"`
	FrontmatterProtected bool                 `json:"frontmatter_protected"`
	ProtectedMetadata    WriterEditorMetadata `json:"protected_metadata"`
	Budget               WriterEditorBudget   `json:"budget"`
}

WriterEditorSource is exact Markdown body plus protected metadata. Metadata is never writable through the body; only a confirmed proposal may apply it.

type WriterOperationIdentity

type WriterOperationIdentity struct {
	OperationID    string
	IdempotencyKey string
}

WriterOperationIdentity is the durable capture identity: re-issuing the same identity replays the original receipt instead of writing twice.

func NewWriterOperationIdentity

func NewWriterOperationIdentity(operationID, idempotencyKey string) (WriterOperationIdentity, error)

NewWriterOperationIdentity validates the identity shape before any HTTP traffic: an invalid identity fails locally, never half-way through a write.

type WriterOrganizeApplyReceipt

type WriterOrganizeApplyReceipt struct {
	SchemaVersion     string `json:"schema_version"`
	OperationID       string `json:"operation_id"`
	PlanID            string `json:"plan_id"`
	CapabilityID      string `json:"capability_id"`
	BindingID         string `json:"binding_id"`
	Status            string `json:"status"`
	Retryable         bool   `json:"retryable"`
	ReplaySafe        bool   `json:"replay_safe"`
	ReconcileRequired bool   `json:"reconcile_required"`
	SnapshotID        string `json:"snapshot_id,omitempty"`
	CreatedAt         string `json:"created_at"`
	UpdatedAt         string `json:"updated_at"`
	AcceptedAt        string `json:"accepted_at"`
}

WriterOrganizeApplyReceipt is the frozen organize apply receipt; the plan id doubles as the recovery identity.

type WriterOrganizeApplyRequest

type WriterOrganizeApplyRequest struct {
	PlanID          string
	SnapshotMessage string
	AllowStale      bool
}

WriterOrganizeApplyRequest applies a saved plan id as-is.

type WriterOrganizeOperation

type WriterOrganizeOperation struct {
	OperationID string `json:"operation_id"`
	ObjectID    string `json:"object_id,omitempty"`
	Kind        string `json:"kind"`
	Mode        string `json:"mode"`
	Risk        string `json:"risk"`
	Path        string `json:"path,omitempty"`
}

WriterOrganizeOperation is one planned organize operation.

type WriterOrganizePlan

type WriterOrganizePlan struct {
	SchemaVersion  string                    `json:"schema_version"`
	PlanID         string                    `json:"plan_id"`
	Status         string                    `json:"status"`
	CreatedAt      string                    `json:"created_at"`
	ExpiresAt      string                    `json:"expires_at"`
	OperationCount int                       `json:"operation_count"`
	Operations     []WriterOrganizeOperation `json:"operations"`
}

WriterOrganizePlan is the frozen saved-plan summary.

type WriterProposalPreview

type WriterProposalPreview struct {
	SchemaVersion string       `json:"schema_version"`
	Change        WriterChange `json:"change"`
	PreviewDigest string       `json:"preview_digest"`
	Path          string       `json:"path"`
	Before        string       `json:"before"`
	After         string       `json:"after"`
	State         string       `json:"state"`
}

WriterProposalPreview is the exact before/after preview plus the digest apply must echo unchanged.

type WriterReceiptError

type WriterReceiptError struct {
	Code    string `json:"code"`
	Message string `json:"message"`
	Hint    string `json:"hint,omitempty"`
}

WriterReceiptError mirrors the bounded receipt error block.

type WriterTagItemResult added in v0.3.1

type WriterTagItemResult struct {
	ObjectID      string `json:"object_id"`
	OperationID   string `json:"operation_id"`
	Status        string `json:"status"`
	RevisionAfter string `json:"revision_after,omitempty"`
}

type WriterTagPlanItem added in v0.3.1

type WriterTagPlanItem struct {
	ObjectID string   `json:"object_id"`
	Revision string   `json:"revision"`
	Path     string   `json:"path"`
	Before   []string `json:"before"`
	After    []string `json:"after"`
}

type WriterTagTarget added in v0.3.1

type WriterTagTarget struct {
	ObjectID string `json:"object_id"`
	Revision string `json:"revision"`
}

type WriterTagsPlan added in v0.3.1

type WriterTagsPlan struct {
	SchemaVersion string              `json:"schema_version"`
	OperationID   string              `json:"operation_id"`
	Operation     string              `json:"operation"`
	OldTag        string              `json:"old_tag"`
	OldTagID      string              `json:"old_tag_id"`
	NewTag        string              `json:"new_tag"`
	NewTagID      string              `json:"new_tag_id"`
	Items         []WriterTagPlanItem `json:"items"`
	PreviewDigest string              `json:"preview_digest"`
}

type WriterTagsPlanRequest added in v0.3.1

type WriterTagsPlanRequest struct {
	OperationID string            `json:"operation_id"`
	Operation   string            `json:"operation"`
	OldTag      string            `json:"old_tag"`
	NewTag      string            `json:"new_tag"`
	Targets     []WriterTagTarget `json:"targets"`
}

type WriterTagsReceipt added in v0.3.1

type WriterTagsReceipt struct{ WriterApplyReceipt }

Raw receipt fields remain closed by the dedicated tag schema, not the wider legacy apply schema. Result and Receipt decode as WriterTagsResult.

type WriterTagsResult added in v0.3.1

type WriterTagsResult struct {
	Items []WriterTagItemResult `json:"items"`
}

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL