@weiliang0121/capix-transcript 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 wei.liang (https://github.com/weiliang0121)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,22 @@
-# Temporary Holding Version
+# @weiliang0121/capix-transcript
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Append-only conversation messages and resource contracts for CAPiX.
+
+The public root owns `Message`, `MessageLocator`, `TranscriptRangeLocator`, `TranscriptSnapshot`, and `TranscriptEvent`. Locators identify fixed positions without retaining an entity; snapshots and events describe one source revision, including segment changes. Transport framing and wire acceptance belong to the protocol adapter and are not entity recovery authority.
+
+ES modules and TypeScript declarations. Requires Node.js 22.23.2 or newer.
+
+```sh
+npm install @weiliang0121/capix-transcript
+```
+
+## Public entry points
+
+- `@weiliang0121/capix-transcript`
+- `@weiliang0121/capix-transcript/presets`
+
+This package is part of CAPiX. The npm distribution contains compiled JavaScript, type declarations, and this package's MIT license. Reference services and client applications are not included in this package or the initial npm release.
+
+## License
+
+MIT. Copyright (c) 2026 wei.liang. See [LICENSE](LICENSE).

package/dist/append.d.ts

@@ -0,0 +1,25 @@
+import type { Message } from './types.js';
+export interface TranscriptAppendOperation {
+    readonly parentContextId: string;
+    readonly childContextId: string;
+    readonly position: string;
+}
+export interface TranscriptFixedAppend {
+    readonly contract: {
+        readonly key: 'transcript.append';
+        readonly version: 1;
+    };
+    readonly operation: TranscriptAppendOperation;
+    readonly transcriptId: string;
+    readonly messages: readonly Readonly<Message>[];
+}
+export interface TranscriptAppendReceipt {
+    readonly transcriptId: string;
+    readonly start: number;
+    readonly count: number;
+    readonly revision: number;
+}
+export interface TranscriptAppendState {
+    readonly request: TranscriptFixedAppend;
+    readonly receipt: TranscriptAppendReceipt;
+}

package/dist/append.js

@@ -0,0 +1 @@
+/*! MIT License | Copyright (c) 2026 wei.liang | See LICENSE */

package/dist/event.d.ts

@@ -0,0 +1,40 @@
+import { FactType } from '@weiliang0121/capix-changes';
+import type { InvocationOrigin } from '@weiliang0121/capix-contracts';
+import type { Message } from './types.js';
+export type TranscriptEvent = Readonly<{
+    type: 'transcript';
+    transcriptId: string;
+    revision: number;
+    occurredAt: string;
+    origin?: InvocationOrigin;
+    change: Readonly<{
+        kind: 'messages-appended';
+        start: number;
+        messages: readonly Readonly<Message>[];
+    }> | Readonly<{
+        kind: 'segment-started';
+        previousStart: number;
+        start: number;
+        end: number;
+    }>;
+}>;
+export declare const TranscriptFacts: FactType<Readonly<{
+    type: "transcript";
+    transcriptId: string;
+    revision: number;
+    occurredAt: string;
+    origin?: InvocationOrigin;
+    change: Readonly<{
+        kind: "messages-appended";
+        start: number;
+        messages: readonly Readonly<Message>[];
+    }> | Readonly<{
+        kind: "segment-started";
+        previousStart: number;
+        start: number;
+        end: number;
+    }>;
+}>>;
+export declare function createTranscriptEvent(transcriptId: string, revision: number, change: TranscriptEvent['change'], origin?: {
+    readonly contextId: string;
+}): TranscriptEvent;

package/dist/event.js

@@ -0,0 +1,2 @@
+/*! MIT License | Copyright (c) 2026 wei.liang | See LICENSE */
+var __defProp=Object.defineProperty;var __name=(target,value)=>__defProp(target,"name",{value,configurable:!0});import{FactType}from"@weiliang0121/capix-changes";const TranscriptFacts=new FactType("transcript");function createTranscriptEvent(transcriptId,revision,change,origin){const body=change.kind==="messages-appended"?Object.freeze({...change,messages:Object.freeze([...change.messages])}):Object.freeze({...change});return Object.freeze({type:"transcript",transcriptId,revision,occurredAt:new Date().toISOString(),...origin?{origin:Object.freeze({...origin})}:{},change:body})}__name(createTranscriptEvent,"createTranscriptEvent");export{TranscriptFacts,createTranscriptEvent};

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { Transcript, type TranscriptOptions, type TranscriptAppendOptions } from './transcript.js';
+export { MessageRef, TranscriptRangeRef } from './ref.js';
+export type { TranscriptAppendOperation, TranscriptFixedAppend, TranscriptAppendReceipt, TranscriptAppendState } from './append.js';
+export type { TranscriptState, TranscriptCommit, TranscriptPersistence } from './persistence.js';
+export type { TranscriptAppendProgress } from './progress.js';
+export { TranscriptFacts, type TranscriptEvent } from './event.js';
+export { TranscriptResource, TranscriptRangeReader, type TranscriptAppendSource } from './resource.js';
+export { TranscriptViewSource, type TranscriptViewSummary } from './view.js';
+export type { Message, MessageLocator, TranscriptRangeLocator, TranscriptSnapshot } from './types.js';

package/dist/index.js

@@ -0,0 +1,2 @@
+/*! MIT License | Copyright (c) 2026 wei.liang | See LICENSE */
+import{Transcript}from"./transcript.js";import{MessageRef,TranscriptRangeRef}from"./ref.js";import{TranscriptFacts}from"./event.js";import{TranscriptResource,TranscriptRangeReader}from"./resource.js";import{TranscriptViewSource}from"./view.js";export{MessageRef,Transcript,TranscriptFacts,TranscriptRangeReader,TranscriptRangeRef,TranscriptResource,TranscriptViewSource};

package/dist/persistence.d.ts

@@ -0,0 +1,25 @@
+import type { Message } from './types.js';
+import type { TranscriptAppendState } from './append.js';
+export interface TranscriptState {
+    readonly id: string;
+    readonly revision: number;
+    readonly starts: readonly number[];
+    readonly messages: readonly Readonly<Message>[];
+    readonly appends?: readonly TranscriptAppendState[];
+}
+export type TranscriptCommit = {
+    readonly transcriptId: string;
+    readonly expectedRevision: number;
+    readonly revision: number;
+} & ({
+    readonly kind: 'append';
+    readonly start: number;
+    readonly messages: readonly Readonly<Message>[];
+    readonly fixed?: TranscriptAppendState;
+} | {
+    readonly kind: 'start-segment';
+    readonly start: number;
+});
+export interface TranscriptPersistence {
+    commit(change: TranscriptCommit): undefined;
+}

package/dist/persistence.js

@@ -0,0 +1 @@
+/*! MIT License | Copyright (c) 2026 wei.liang | See LICENSE */

package/dist/presets.d.ts

@@ -0,0 +1,7 @@
+import type { Message } from './types.js';
+export interface IndexedMessage {
+    readonly index: number;
+    readonly message: Readonly<Message>;
+}
+export type AdjacentMessageGroup = readonly [IndexedMessage] | readonly [IndexedMessage, IndexedMessage];
+export declare function groupAdjacentPairs(messages: readonly IndexedMessage[]): readonly AdjacentMessageGroup[];

package/dist/presets.js

@@ -0,0 +1,2 @@
+/*! MIT License | Copyright (c) 2026 wei.liang | See LICENSE */
+var __defProp=Object.defineProperty;var __name=(target,value)=>__defProp(target,"name",{value,configurable:!0});function groupAdjacentPairs(messages){if(!Array.isArray(messages))throw new TypeError("Message grouping requires indexed messages");let previous=-1;const entries=Array.from(messages,entry=>{const index=entry?.index,message=entry?.message;if(!Number.isSafeInteger(index)||index<=previous)throw new RangeError("Message grouping requires strictly increasing nonnegative indexes");if(message?.role!=="user"&&message?.role!=="assistant")throw new TypeError("Message grouping requires user or assistant messages");return previous=index,Object.freeze({index,message})}),groups=[];for(let position=0;position<entries.length;position++){const current=entries[position],next=entries[position+1];current.message.role==="user"&&next?.message.role==="assistant"&&next.index===current.index+1?(groups.push(Object.freeze([current,next])),position++):groups.push(Object.freeze([current]))}return Object.freeze(groups)}__name(groupAdjacentPairs,"groupAdjacentPairs");export{groupAdjacentPairs};

package/dist/progress.d.ts

@@ -0,0 +1,3 @@
+import type { TranscriptRangeLocator } from './types.js';
+export interface TranscriptAppendProgress extends TranscriptRangeLocator {
+}

package/dist/progress.js

@@ -0,0 +1 @@
+/*! MIT License | Copyright (c) 2026 wei.liang | See LICENSE */

package/dist/ref.d.ts

@@ -0,0 +1,17 @@
+import type { Transcript } from './transcript.js';
+export declare class MessageRef {
+    readonly transcript: Transcript;
+    readonly index: number;
+    constructor(transcript: Transcript, index: number);
+    read(): Readonly<import("./types.js").Message>;
+}
+export declare class TranscriptRangeRef {
+    readonly transcript: Transcript;
+    readonly start: number;
+    readonly end: number;
+    constructor(transcript: Transcript, start: number, end: number);
+    get length(): number;
+    ref(index: number): MessageRef;
+    read(index: number): Readonly<import("./types.js").Message>;
+    refs(): readonly MessageRef[];
+}

package/dist/ref.js

@@ -0,0 +1,2 @@
+/*! MIT License | Copyright (c) 2026 wei.liang | See LICENSE */
+var __defProp=Object.defineProperty;var __name=(target,value)=>__defProp(target,"name",{value,configurable:!0});import{isSafeInteger}from"es-toolkit/compat";class MessageRef{static{__name(this,"MessageRef")}transcript;index;constructor(transcript,index){if(this.transcript=transcript,this.index=index,!isSafeInteger(index)||index<0||!transcript.get(index))throw new RangeError("Message index does not exist");Object.freeze(this)}read(){return this.transcript.get(this.index)}}class TranscriptRangeRef{static{__name(this,"TranscriptRangeRef")}transcript;start;end;constructor(transcript,start,end){if(this.transcript=transcript,this.start=start,this.end=end,!isSafeInteger(start)||!isSafeInteger(end)||start<0||end<start||end>transcript.length)throw new RangeError("Transcript range does not exist");Object.freeze(this)}get length(){return this.end-this.start}ref(index){if(index<this.start||index>=this.end)throw new RangeError("Message is outside the fixed history range");return new MessageRef(this.transcript,index)}read(index){if(!isSafeInteger(index)||index<this.start||index>=this.end)throw new RangeError("Message is outside the fixed history range");return this.transcript.get(index)}refs(){return Array.from({length:this.length},(_,offset)=>this.ref(this.start+offset))}}export{MessageRef,TranscriptRangeRef};

package/dist/resource.d.ts

@@ -0,0 +1,48 @@
+import { Transcript } from './transcript.js';
+import type { Message, TranscriptRangeLocator } from './types.js';
+import { ResourceOffer } from '@weiliang0121/capix-resources';
+import type { ResourceEndpointActivity } from '@weiliang0121/capix-resources';
+import { TranscriptRangeRef } from './ref.js';
+import { type ProgressReceiver } from '@weiliang0121/capix-changes';
+import type { TranscriptAppendProgress } from './progress.js';
+export interface TranscriptAppendSource {
+    readonly transcript: Transcript;
+    readonly progress?: ProgressReceiver<TranscriptAppendProgress>;
+}
+export declare class TranscriptRangeReader {
+    #private;
+    readonly start: number;
+    readonly end: number;
+    readonly transcriptId: string;
+    readonly revision: number;
+    constructor(range: TranscriptRangeRef, activity?: ResourceEndpointActivity, revision?: number);
+    get length(): number;
+    locate(): TranscriptRangeLocator;
+    read(index: number): Readonly<Message>;
+    slice(start: number, end?: number): TranscriptRangeReader;
+    entries(): readonly Readonly<{
+        index: number;
+        message: Readonly<Message>;
+    }>[];
+}
+export declare const TranscriptResource: Readonly<{
+    append: ResourceOffer<Transcript | TranscriptAppendSource, Readonly<{
+        applyFixed(input: {
+            readonly position: string;
+            readonly messages: readonly Message[];
+        }): unknown;
+        append(messages: readonly Message[]): readonly Readonly<{
+            transcriptId: string;
+            index: number;
+            message: Readonly<Message>;
+        }>[];
+    }>, Transcript | TranscriptAppendSource, never>;
+    segmentation: ResourceOffer<Transcript, Readonly<{
+        current: () => TranscriptRangeReader;
+        start: (index: number) => void;
+    }>, Transcript, never>;
+    fixedRange: ResourceOffer<TranscriptRangeRef, TranscriptRangeReader, {
+        range: TranscriptRangeRef;
+        revision: number;
+    }, never>;
+}>;

package/dist/resource.js

@@ -0,0 +1,2 @@
+/*! MIT License | Copyright (c) 2026 wei.liang | See LICENSE */
+var __defProp=Object.defineProperty;var __name=(target,value)=>__defProp(target,"name",{value,configurable:!0});import{TranscriptFacts}from"./event.js";import{Transcript}from"./transcript.js";import{ResourceOffer}from"@weiliang0121/capix-resources";import{TranscriptRangeRef}from"./ref.js";import{ProgressChannel}from"@weiliang0121/capix-changes";class TranscriptRangeReader{static{__name(this,"TranscriptRangeReader")}#range;#activity;start;end;transcriptId;revision;constructor(range,activity,revision=range.transcript.revision){this.#range=range,this.#activity=activity,this.start=range.start,this.end=range.end,this.transcriptId=range.transcript.id,this.revision=revision,Object.freeze(this)}get length(){return this.end-this.start}locate(){return Object.freeze({transcriptId:this.transcriptId,start:this.start,end:this.end,revision:this.revision})}read(index){const read=__name(()=>this.#range.read(index),"read");return this.#activity?this.#activity.runSync("read",{input:__name(()=>({transcriptId:this.transcriptId,index}),"input"),output:__name(()=>({transcriptId:this.transcriptId,index}),"output")},read):read()}slice(start,end=this.end){if(this.#activity?.validate(),start<this.start||end>this.end)throw new RangeError("Requested range exceeds available messages");return new TranscriptRangeReader(new TranscriptRangeRef(this.#range.transcript,start,end),this.#activity,this.revision)}entries(){const read=__name(()=>Object.freeze(Array.from({length:this.length},(_,offset)=>{const index=this.start+offset;return Object.freeze({index,message:this.#range.read(index)})})),"read");return this.#activity?this.#activity.runSync("entries",{input:__name(()=>this.locate(),"input"),output:__name(()=>this.locate(),"output")},read):read()}}const TranscriptResource=Object.freeze({append:new ResourceOffer({name:"transcript.append",expose:__name((source,activity)=>{const transcript=source instanceof Transcript?source:source.transcript,progress=source instanceof Transcript||!source.progress?void 0:new ProgressChannel(source.progress);return Object.freeze({applyFixed(input){return activity.runSync("applyFixed",{input:__name(()=>({position:input.position,count:input.messages.length}),"input"),output:__name(receipt=>receipt,"output")},operation=>transcript.applyFixed({contract:{key:"transcript.append",version:1},operation:{...activity.reception(),position:input.position},transcriptId:transcript.id,messages:input.messages},{origin:operation.origin,observation:operation.facts(TranscriptFacts),progress}))},append(messages){return activity.runSync("append",{input:__name(()=>({count:messages.length}),"input"),output:__name(result=>({transcriptId:transcript.id,indexes:result.map(item=>item.index),revision:transcript.revision}),"output")},operation=>{const start=transcript.length;return transcript.appendFrom(messages,{origin:operation.origin,observation:operation.facts(TranscriptFacts),progress}),Object.freeze(messages.map((_,offset)=>Object.freeze({transcriptId:transcript.id,index:start+offset,message:transcript.get(start+offset)})))})}})},"expose"),timing:"access",describe:__name(source=>({transcriptId:(source instanceof Transcript?source:source.transcript).id}),"describe")}),segmentation:new ResourceOffer({name:"transcript.segmentation",expose:__name((transcript,activity)=>Object.freeze({current:__name(()=>activity.runSync("current",{output:__name(reader=>reader.locate(),"output")},()=>new TranscriptRangeReader(new TranscriptRangeRef(transcript,transcript.activeStart,transcript.length),activity)),"current"),start:__name(index=>activity.runSync("start",{input:__name(()=>({start:index}),"input"),output:__name(()=>({transcriptId:transcript.id,start:transcript.activeStart,end:transcript.length,revision:transcript.revision}),"output")},operation=>transcript.startSegment(index,{origin:operation.origin,observation:operation.facts(TranscriptFacts)})),"start")}),"expose"),timing:"access",describe:__name(transcript=>({transcriptId:transcript.id}),"describe")}),fixedRange:new ResourceOffer({name:"transcript.fixedRange",expose:__name((captured,activity)=>new TranscriptRangeReader(captured.range,activity,captured.revision),"expose"),timing:"binding",capture:__name(range=>({range,revision:range.transcript.revision}),"capture"),describe:__name(({range,revision})=>({transcriptId:range.transcript.id,start:range.start,end:range.end,revision}),"describe")})});export{TranscriptRangeReader,TranscriptResource};

package/dist/transcript.d.ts

@@ -0,0 +1,47 @@
+import { type ChangeProvenance } from '@weiliang0121/capix-changes';
+import type { EventConsumer } from '@weiliang0121/capix-changes';
+import { MessageRef, TranscriptRangeRef } from './ref.js';
+import type { Message } from './types.js';
+import type { ChangeCapture } from '@weiliang0121/capix-changes';
+import { type TranscriptEvent } from './event.js';
+import type { ProgressChannel } from '@weiliang0121/capix-changes';
+import type { TranscriptAppendProgress } from './progress.js';
+import type { TranscriptPersistence, TranscriptState } from './persistence.js';
+import type { TranscriptAppendReceipt, TranscriptFixedAppend } from './append.js';
+export interface TranscriptOptions {
+    observation?: EventConsumer<TranscriptEvent>;
+    changes?: ChangeCapture<TranscriptEvent>;
+    persistence?: TranscriptPersistence;
+}
+export interface TranscriptAppendOptions extends ChangeProvenance<TranscriptEvent> {
+    readonly progress?: ProgressChannel<TranscriptAppendProgress>;
+}
+export declare class Transcript {
+    #private;
+    constructor(messages?: readonly Message[], options?: TranscriptOptions);
+    get id(): string;
+    static restore(state: TranscriptState, options?: TranscriptOptions): Transcript;
+    exportState(): TranscriptState;
+    get length(): number;
+    get revision(): number;
+    get activeStart(): number;
+    segments(): readonly TranscriptRangeRef[];
+    startSegment(start: number, provenance?: ChangeProvenance<TranscriptEvent>): void;
+    append(...messages: readonly Message[]): void;
+    appendFrom(messages: readonly Message[], provenance?: TranscriptAppendOptions): void;
+    confirmFixed(value: TranscriptFixedAppend): TranscriptAppendReceipt | undefined;
+    applyFixed(value: TranscriptFixedAppend, provenance?: TranscriptAppendOptions): TranscriptAppendReceipt;
+    private appendAccepted;
+    private acceptFixed;
+    private confirmAccepted;
+    private matchesMessages;
+    private capture;
+    private enterMutation;
+    private nextRevision;
+    private commit;
+    current(role: Message['role']): Readonly<Message> | undefined;
+    get(index: number): Readonly<Message> | undefined;
+    ref(index: number): MessageRef;
+    snapshot(end?: number): readonly Readonly<Message>[];
+    private static accept;
+}

package/dist/transcript.js

@@ -0,0 +1,2 @@
+/*! MIT License | Copyright (c) 2026 wei.liang | See LICENSE */
+var __defProp=Object.defineProperty;var __name=(target,value)=>__defProp(target,"name",{value,configurable:!0});import{publishFact}from"@weiliang0121/capix-changes";import{randomUUID}from"node:crypto";import{isArray,isSafeInteger}from"es-toolkit/compat";import{isNonBlankString}from"./validation.js";import{isObject}from"./validation.js";import{MessageRef,TranscriptRangeRef}from"./ref.js";import{createTranscriptEvent}from"./event.js";import{RuntimeError}from"@weiliang0121/capix-contracts";import{PersistenceError}from"@weiliang0121/capix-diagnostics";class Transcript{static{__name(this,"Transcript")}#id=randomUUID();#observation;#mutating=!1;#changes;#persistence;#revision=0;#messages=[];#starts=[0];#appends=new Map;constructor(messages=[],options={}){if(this.#observation=options.observation,this.#changes=options.changes,this.#persistence=options.persistence,!isArray(messages))throw new TypeError("\u6D88\u606F\u96C6\u5408\u5FC5\u987B\u662F\u6570\u7EC4\u3002");this.append(...messages)}get id(){return this.#id}static restore(state,options={}){if(!isObject(state)||!isNonBlankString(state.id)||!isArray(state.messages)||!isArray(state.starts))throw new TypeError("Invalid persisted transcript");const messages=Array.from(state.messages,message=>Transcript.accept(message)),starts=Array.from(state.starts);if(!starts.length||starts[0]!==0||starts.some((start,index)=>!isSafeInteger(start)||start<0||index>0&&(start<=starts[index-1]||start>=messages.length)))throw new TypeError("Invalid persisted transcript segments");const minimumRevision=messages.length?starts.length:0,maximumRevision=messages.length+starts.length-1;if(!isSafeInteger(state.revision)||state.revision<minimumRevision||state.revision>maximumRevision)throw new TypeError("Invalid persisted transcript revision");const transcript=new Transcript([],options);transcript.#id=state.id,transcript.#revision=state.revision,transcript.#starts.length=0;for(const start of starts)transcript.#starts.push(start);for(const message of messages)transcript.#messages.push(message);if(state.appends!==void 0){if(!isArray(state.appends))throw new TypeError("Invalid persisted transcript append operations");let previousEnd=0,previousRevision=0;for(const saved of state.appends){if(!isObject(saved)||!isObject(saved.receipt))throw new TypeError("Invalid persisted transcript append receipt");const request=transcript.acceptFixed(saved.request),value=saved.receipt;if(value.transcriptId!==transcript.id||!isSafeInteger(value.start)||value.start<previousEnd||!isSafeInteger(value.count)||value.count!==request.messages.length||value.start+value.count>messages.length||!isSafeInteger(value.revision)||value.revision<=previousRevision||value.revision>state.revision)throw new TypeError("Invalid persisted transcript append receipt");if(!transcript.matchesMessages(value.start,request.messages))throw new TypeError("Persisted transcript append does not match messages");const key=operationKey(request.operation);if(transcript.#appends.has(key))throw new TypeError("Duplicate persisted transcript append operation");const receipt=Object.freeze({transcriptId:transcript.id,start:value.start,count:value.count,revision:value.revision});transcript.#appends.set(key,Object.freeze({request,receipt})),previousEnd=value.start+value.count,previousRevision=value.revision}}return transcript}exportState(){return Object.freeze({id:this.id,revision:this.#revision,starts:Object.freeze([...this.#starts]),messages:Object.freeze([...this.#messages]),...this.#appends.size?{appends:Object.freeze([...this.#appends.values()])}:{}})}get length(){return this.#messages.length}get revision(){return this.#revision}get activeStart(){return this.#starts.at(-1)}segments(){return this.#starts.map((start,index)=>new TranscriptRangeRef(this,start,this.#starts[index+1]??this.length))}startSegment(start,provenance={}){this.enterMutation();try{if(!isSafeInteger(start)||start<=this.activeStart||start>=this.length)throw new RangeError("New segment must start inside the active range");const previousStart=this.activeStart,end=this.length,event=createTranscriptEvent(this.id,this.nextRevision(),{kind:"segment-started",previousStart,start,end},provenance.origin);this.commit(Object.freeze({kind:"start-segment",transcriptId:this.id,expectedRevision:this.#revision,revision:event.revision,start})),this.#starts.push(start),this.#revision=event.revision,this.capture(event,provenance.observation)}finally{this.#mutating=!1}}append(...messages){this.appendFrom(messages)}appendFrom(messages,provenance={}){this.enterMutation();try{if(!isArray(messages))throw new TypeError("\u6D88\u606F\u96C6\u5408\u5FC5\u987B\u662F\u6570\u7EC4\u3002");const accepted=Object.freeze(Array.from(messages,message=>Transcript.accept(message)));if(!accepted.length)return;this.appendAccepted(accepted,provenance)}finally{this.#mutating=!1}}confirmFixed(value){const request=this.acceptFixed(value);return this.confirmAccepted(request)}applyFixed(value,provenance={}){this.enterMutation();try{const request=this.acceptFixed(value);return this.confirmAccepted(request)??this.appendAccepted(request.messages,provenance,request)}finally{this.#mutating=!1}}appendAccepted(messages,provenance,request){const start=this.length,event=createTranscriptEvent(this.id,this.nextRevision(),{kind:"messages-appended",start,messages},provenance.origin),receipt=Object.freeze({transcriptId:this.id,start,count:messages.length,revision:event.revision}),fixed=request?Object.freeze({request,receipt}):void 0;this.commit(Object.freeze({kind:"append",transcriptId:this.id,expectedRevision:this.#revision,revision:event.revision,start,messages,...fixed?{fixed}:{}}));for(const message of messages)this.#messages.push(message);return this.#revision=event.revision,fixed&&this.#appends.set(operationKey(fixed.request.operation),fixed),this.capture(event,provenance.observation,provenance.progress),receipt}acceptFixed(value){if(!isObject(value)||!isObject(value.operation)||!isNonBlankString(value.operation.parentContextId)||!isNonBlankString(value.operation.childContextId)||!isNonBlankString(value.operation.position)||!isObject(value.contract)||!isArray(value.messages)||!value.messages.length)throw new TypeError("Invalid fixed transcript append request");if(value.transcriptId!==this.id||value.contract.key!=="transcript.append"||value.contract.version!==1)throw appendConflict();const operation=Object.freeze({parentContextId:value.operation.parentContextId,childContextId:value.operation.childContextId,position:value.operation.position}),messages=Object.freeze(Array.from(value.messages,message=>Transcript.accept(message)));return Object.freeze({contract:Object.freeze({key:"transcript.append",version:1}),operation,transcriptId:this.id,messages})}confirmAccepted(request){const saved=this.#appends.get(operationKey(request.operation));if(saved){if(saved.request.messages.length!==request.messages.length||!this.matchesMessages(saved.receipt.start,request.messages))throw appendConflict();return saved.receipt}}matchesMessages(start,messages){return messages.every((message,offset)=>this.#messages[start+offset]?.role===message.role&&this.#messages[start+offset]?.content===message.content)}capture(event,observation=this.#observation,progress){event.change.kind==="messages-appended"&&progress?.publish(Object.freeze({transcriptId:this.id,start:event.change.start,end:event.change.start+event.change.messages.length,revision:event.revision})),publishFact(event,this.#changes,observation)}enterMutation(){if(this.#mutating)throw new Error("Transcript persistence or change publication cannot reenter mutation");this.#mutating=!0}nextRevision(){if(!isSafeInteger(this.#revision+1))throw new RangeError("Transcript revision is exhausted");return this.#revision+1}commit(change){try{const result=this.#persistence?.commit(change);if(result!==void 0)throw Promise.resolve(result).catch(()=>{}),new TypeError("Transcript persistence must complete synchronously and return undefined")}catch(cause){throw cause instanceof PersistenceError?cause:new PersistenceError("transcript.commit",cause)}}current(role){return this.#messages.findLast(message2=>message2.role===role)}get(index){return this.#messages[index]}ref(index){return new MessageRef(this,index)}snapshot(end=this.length){if(!isSafeInteger(end)||end<0||end>this.length)throw new RangeError("Transcript boundary does not exist");return this.#messages.slice(0,end)}static accept(value){if(!isObject(value))throw new TypeError("\u6D88\u606F\u5FC5\u987B\u662F\u5305\u542B role \u548C content \u7684\u5BF9\u8C61\u3002");const message=value;if(message.role!=="user"&&message.role!=="assistant")throw new TypeError("\u6D88\u606F\u89D2\u8272\u5FC5\u987B\u662F user \u6216 assistant\u3002");if(!isNonBlankString(message.content))throw new TypeError("\u6D88\u606F\u5185\u5BB9\u5FC5\u987B\u662F\u975E\u7A7A\u5B57\u7B26\u4E32\u3002");return Object.freeze({role:message.role,content:message.content})}}function operationKey(operation){return JSON.stringify([operation.parentContextId,operation.childContextId,operation.position])}__name(operationKey,"operationKey");function appendConflict(){return new RuntimeError("TRANSCRIPT_APPEND_CONFLICT","\u56FA\u5B9A\u6D88\u606F\u8FFD\u52A0\u7684\u76EE\u6807\u3001\u5951\u7EA6\u6216\u5185\u5BB9\u4E0E\u539F\u64CD\u4F5C\u4E0D\u4E00\u81F4\u3002")}__name(appendConflict,"appendConflict");export{Transcript};

package/dist/types.d.ts

@@ -0,0 +1,22 @@
+export interface Message {
+    role: 'user' | 'assistant';
+    content: string;
+}
+export interface MessageLocator {
+    readonly transcriptId: string;
+    readonly index: number;
+}
+export interface TranscriptRangeLocator {
+    readonly transcriptId: string;
+    readonly start: number;
+    readonly end: number;
+    readonly revision?: number;
+}
+export interface TranscriptSnapshot {
+    readonly id: string;
+    readonly revision: number;
+    readonly start: 0;
+    readonly end: number;
+    readonly starts: readonly number[];
+    readonly messages: readonly Readonly<Message>[];
+}

package/dist/types.js

@@ -0,0 +1 @@
+/*! MIT License | Copyright (c) 2026 wei.liang | See LICENSE */

package/dist/validation.d.ts

@@ -0,0 +1,2 @@
+export declare function isObject(value: unknown): value is Record<string, unknown>;
+export declare function isNonBlankString(value: unknown): value is string;

package/dist/validation.js

@@ -0,0 +1,2 @@
+/*! MIT License | Copyright (c) 2026 wei.liang | See LICENSE */
+var __defProp=Object.defineProperty;var __name=(target,value)=>__defProp(target,"name",{value,configurable:!0});import{isArray,isObjectLike}from"es-toolkit/compat";import{isString}from"es-toolkit/predicate";function isObject(value){return isObjectLike(value)&&!isArray(value)}__name(isObject,"isObject");function isNonBlankString(value){return isString(value)&&/\S/.test(value)}__name(isNonBlankString,"isNonBlankString");export{isNonBlankString,isObject};

package/dist/view.d.ts

@@ -0,0 +1,23 @@
+import type { Message } from './types.js';
+import type { SyncViewSource } from '@weiliang0121/capix-view';
+import type { Transcript } from './transcript.js';
+export interface TranscriptViewSummary {
+    readonly role: Message['role'];
+}
+type TranscriptViewContract = SyncViewSource<number, TranscriptViewSummary, Readonly<Message>>;
+type SourceStamp = Parameters<TranscriptViewContract['read']>[1];
+export declare class TranscriptViewSource implements TranscriptViewContract {
+    #private;
+    readonly id: string;
+    readonly scope: string;
+    constructor(transcript: Transcript, keys?: readonly number[]);
+    index(): ReturnType<TranscriptViewContract['index']>;
+    inspect(keys: readonly number[]): ReturnType<TranscriptViewContract['inspect']>;
+    read(keys: readonly number[], expected: SourceStamp): ReturnType<TranscriptViewContract['read']>;
+    check(expected: SourceStamp): boolean;
+    private stamp;
+    private requireCurrent;
+    private acceptKeys;
+    private requireMessage;
+}
+export {};

package/dist/view.js

@@ -0,0 +1,2 @@
+/*! MIT License | Copyright (c) 2026 wei.liang | See LICENSE */
+var __defProp=Object.defineProperty;var __name=(target,value)=>__defProp(target,"name",{value,configurable:!0});import{RuntimeError}from"@weiliang0121/capix-contracts";class TranscriptViewSource{static{__name(this,"TranscriptViewSource")}id;scope;#transcript;#keys;#allowed;constructor(transcript,keys){if(this.#transcript=transcript,this.id=transcript.id,keys!==void 0){this.#keys=this.acceptKeys(keys);for(const key of this.#keys)this.requireMessage(key);this.#allowed=new Set(this.#keys)}this.scope=this.#keys===void 0?"whole":`keys:${JSON.stringify(this.#keys)}`,Object.freeze(this)}index(){const stamp=this.stamp(),keys=this.#keys??Array.from({length:this.#transcript.length},(_,index)=>index),entries=Object.freeze(keys.map(key=>Object.freeze({key,summary:Object.freeze({role:this.requireMessage(key).role})})));return this.requireCurrent(stamp),Object.freeze({stamp,entries})}inspect(keys){const stamp=this.stamp(),selected=this.acceptKeys(keys),entries=Object.freeze(selected.map(key=>{if(this.#allowed&&!this.#allowed.has(key))throw new RangeError("Message is outside the view source scope");return Object.freeze({key,summary:Object.freeze({role:this.requireMessage(key).role})})}));return this.requireCurrent(stamp),Object.freeze({stamp,entries})}read(keys,expected){const basis=Object.freeze({id:expected.id,scope:expected.scope,version:expected.version});this.requireCurrent(basis);const selected=this.acceptKeys(keys),entries=Object.freeze(selected.map(key=>{if(this.#allowed&&!this.#allowed.has(key))throw new RangeError("Message is outside the view source scope");return Object.freeze({key,value:this.requireMessage(key)})}));return this.requireCurrent(basis),Object.freeze({stamp:this.stamp(),entries})}check(expected){return expected?.id===this.id&&expected.scope===this.scope&&expected.version===String(this.#transcript.revision)}stamp(){return Object.freeze({id:this.id,scope:this.scope,version:String(this.#transcript.revision)})}requireCurrent(expected){if(!this.check(expected))throw new RuntimeError("VIEW_SOURCE_CONFLICT","Transcript view source has changed")}acceptKeys(keys){if(!Array.isArray(keys))throw new TypeError("Transcript view keys must be an array");const accepted=Array.from(keys);if(accepted.some(key=>!Number.isSafeInteger(key)||key<0)||new Set(accepted).size!==accepted.length)throw new TypeError("Transcript view requires unique nonnegative integer keys");return Object.freeze(accepted)}requireMessage(key){const message=this.#transcript.get(key);if(!message)throw new RangeError("Transcript view message does not exist");return message}}export{TranscriptViewSource};

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "@weiliang0121/capix-transcript",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "private": false,
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./presets": {
+      "types": "./dist/presets.d.ts",
+      "import": "./dist/presets.js"
+    }
+  },
+  "dependencies": {
+    "es-toolkit": "1.52.0",
+    "@weiliang0121/capix-contracts": "0.2.0",
+    "@weiliang0121/capix-diagnostics": "0.2.0",
+    "@weiliang0121/capix-resources": "0.2.0",
+    "@weiliang0121/capix-changes": "0.2.0",
+    "@weiliang0121/capix-view": "0.2.0"
+  },
+  "description": "Append-only conversation messages and resource contracts for CAPiX.",
+  "license": "MIT",
+  "author": "wei.liang (https://github.com/weiliang0121)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/weiliang0121/capix.git",
+    "directory": "packages/transcript"
+  },
+  "engines": {
+    "node": ">=22.23.2"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "LICENSE",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node ../../scripts/test/run.mjs --package ."
+  }
 }