@chenmiao8563/dsh-token-ledger 0.1.0

package/lib/session-log.js

@@ -0,0 +1,142 @@
+/**
+ * Offline reader for DSH session logs.
+ *
+ * A DSH session log is a concatenation of independent Zstandard frames, each
+ * frame holding a chunk of newline-delimited JSON. Node's zstd entry points
+ * stop after the first frame, so the frames must be delimited explicitly
+ * before decompression.
+ *
+ * This module walks the frame structure described by RFC 8878 (magic number,
+ * frame header, block headers, optional content checksum) instead of scanning
+ * for the magic byte sequence, because a magic scan can match bytes inside
+ * compressed block payloads and silently split a frame in half.
+ *
+ * Every function here is synchronous, dependency-free, and read-only.
+ *
+ * @module dsh-token-ledger/session-log
+ */
+
+import { readFileSync } from 'node:fs'
+import { zstdDecompressSync } from 'node:zlib'
+
+/** Zstandard frame magic number, stored little-endian: 0xFD2FB528. */
+const ZSTD_MAGIC = 0xfd2fb528
+
+/** A Zstandard frame can be at most 128 KiB of header plus blocks; this bounds a walk. */
+const MAX_DICTIONARY_ID_BYTES = [0, 1, 2, 4]
+
+/**
+ * Read the length of the frame starting at `start`.
+ *
+ * @param {Buffer} buffer - the whole file.
+ * @param {number} start - offset of the frame's magic number.
+ * @returns {number} the frame length in bytes.
+ * @throws {Error} when the frame is truncated or structurally invalid.
+ */
+export function frameLengthAt(buffer, start) {
+  if (start + 4 > buffer.length) throw new Error(`truncated frame magic at offset ${start}`)
+  if (buffer.readUInt32LE(start) !== ZSTD_MAGIC) {
+    throw new Error(`no zstd magic at offset ${start}`)
+  }
+
+  let cursor = start + 4
+  if (cursor + 1 > buffer.length) throw new Error(`truncated frame header at offset ${start}`)
+  const descriptor = buffer.readUInt8(cursor)
+  cursor += 1
+
+  const contentSizeFlag = (descriptor >> 6) & 0x3
+  const singleSegment = (descriptor >> 5) & 0x1
+  const checksumFlag = (descriptor >> 2) & 0x1
+  const dictionaryIdFlag = descriptor & 0x3
+
+  // Window_Descriptor is present only when Single_Segment_flag is clear.
+  if (singleSegment === 0) cursor += 1
+  cursor += MAX_DICTIONARY_ID_BYTES[dictionaryIdFlag]
+
+  // 0 bytes when the flag is 0 and a single segment is declared is not allowed;
+  // the spec maps flag 0 to 1 byte in that case.
+  const contentSizeBytes = contentSizeFlag === 0 ? (singleSegment === 1 ? 1 : 0) : 1 << contentSizeFlag
+  cursor += contentSizeBytes
+
+  if (cursor > buffer.length) throw new Error(`truncated frame header at offset ${start}`)
+
+  // Walk the block sequence to find where this frame ends.
+  for (;;) {
+    if (cursor + 3 > buffer.length) throw new Error(`truncated block header at offset ${cursor}`)
+    const header = buffer.readUInt8(cursor) | (buffer.readUInt8(cursor + 1) << 8) | (buffer.readUInt8(cursor + 2) << 16)
+    const lastBlock = (header & 0x1) === 1
+    const blockType = (header >> 1) & 0x3
+    const blockSize = header >> 3
+    cursor += 3
+    if (blockType === 3) throw new Error(`reserved block type at offset ${cursor - 3}`)
+    cursor += blockType === 1 ? 1 : blockSize
+    if (cursor > buffer.length) throw new Error(`truncated block payload at offset ${start}`)
+    if (lastBlock) break
+  }
+
+  if (checksumFlag === 1) cursor += 4
+  if (cursor > buffer.length) throw new Error(`truncated content checksum at offset ${start}`)
+  return cursor - start
+}
+
+/**
+ * Delimit every Zstandard frame in a buffer.
+ *
+ * @param {Buffer} buffer - a DSH session log's raw bytes.
+ * @returns {{ offset: number, length: number }[]} frames in file order.
+ */
+export function splitZstdFrames(buffer) {
+  const frames = []
+  let offset = 0
+  while (offset < buffer.length) {
+    const length = frameLengthAt(buffer, offset)
+    frames.push({ offset, length })
+    offset += length
+  }
+  return frames
+}
+
+/**
+ * Decode a buffer of concatenated Zstandard frames into its raw text and then
+ * into JSON events.
+ *
+ * @param {Buffer} buffer - a DSH session log's raw bytes.
+ * @returns {object[]} every parseable JSON record, in order. Unparseable lines
+ *   are skipped rather than failing the whole log.
+ */
+export function decodeSessionLogBuffer(buffer) {
+  const parts = []
+  for (const frame of splitZstdFrames(buffer)) {
+    parts.push(zstdDecompressSync(buffer.subarray(frame.offset, frame.offset + frame.length)))
+  }
+  return parseJsonLines(Buffer.concat(parts).toString('utf8'))
+}
+
+/**
+ * Split newline-delimited JSON into records, skipping lines that do not parse.
+ *
+ * @param {string} text - the decompressed log text.
+ * @returns {object[]} the parsed records.
+ */
+export function parseJsonLines(text) {
+  const events = []
+  for (const line of text.split('\n')) {
+    if (line.trim() === '') continue
+    try {
+      events.push(JSON.parse(line))
+    } catch {
+      // A torn trailing line is normal for a log whose writer was killed.
+    }
+  }
+  return events
+}
+
+/**
+ * Read and decode one DSH session log file.
+ *
+ * @param {string} path - path to a `session.jsonl.zstd` file.
+ * @returns {object[]} every JSON event in the log, in order.
+ */
+export function readSessionLog(path) {
+  return decodeSessionLogBuffer(readFileSync(path))
+}

package/lib/store.js

@@ -0,0 +1,101 @@
+/**
+ * Ledger persistence: where the ledger lives and how it is written.
+ *
+ * Both the host plugin and the CLI use these helpers, so the file the plugin
+ * writes is exactly the file the CLI audits. Writes are atomic (temporary file
+ * plus rename) because a half-written ledger would silently lose history.
+ *
+ * @module dsh-token-ledger/store
+ */
+
+import { mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join, resolve } from 'node:path'
+
+/** Directory name created inside the DSH home for this plugin's state. */
+export const STATE_DIRNAME = 'token-ledger'
+
+/** The ledger file's name inside {@link STATE_DIRNAME}. */
+export const LEDGER_FILENAME = 'ledger.json'
+
+/**
+ * Resolve the DSH home directory the way the host process does.
+ *
+ * @param {string} [explicit] - an explicit home, e.g. a CLI `--home` flag.
+ * @param {NodeJS.ProcessEnv} [env] - environment to consult.
+ * @returns {string} an absolute path to the DSH home.
+ */
+export function resolveHome(explicit, env = process.env) {
+  if (typeof explicit === 'string' && explicit.trim() !== '') return resolve(explicit)
+  if (typeof env.DSH_HOME === 'string' && env.DSH_HOME.trim() !== '') return resolve(env.DSH_HOME)
+  return join(homedir(), '.dsh')
+}
+
+/**
+ * The paths this plugin reads and writes inside a DSH home.
+ *
+ * @param {string} [home] - an explicit DSH home.
+ * @param {NodeJS.ProcessEnv} [env] - environment to consult.
+ * @returns {{ home: string, dir: string, ledger: string, exportsDir: string, sessionsDir: string }} the layout.
+ */
+export function ledgerPaths(home, env = process.env) {
+  const resolved = resolveHome(home, env)
+  const dir = join(resolved, STATE_DIRNAME)
+  return {
+    home: resolved,
+    dir,
+    ledger: join(dir, LEDGER_FILENAME),
+    exportsDir: join(dir, 'exports'),
+    sessionsDir: join(resolved, 'sessions'),
+  }
+}
+
+/**
+ * Read a stored ledger.
+ *
+ * @param {string} path - the ledger file path.
+ * @returns {object|undefined} the snapshot, or `undefined` when absent or
+ *   unreadable. A corrupt ledger is treated as "start fresh" rather than fatal.
+ */
+export function loadLedger(path) {
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'))
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Write a file atomically, creating parent directories as needed.
+ *
+ * @param {string} path - the destination path.
+ * @param {string} text - the content to write.
+ * @returns {string} the destination path.
+ */
+export function writeFileAtomic(path, text) {
+  mkdirSync(dirname(path), { recursive: true })
+  const temporary = `${path}.tmp-${process.pid}`
+  writeFileSync(temporary, text, 'utf8')
+  try {
+    renameSync(temporary, path)
+  } catch (error) {
+    try {
+      unlinkSync(temporary)
+    } catch {
+      // The rename failure matters more than the cleanup failure.
+    }
+    throw error
+  }
+  return path
+}
+
+/**
+ * Persist a ledger snapshot atomically.
+ *
+ * @param {string} path - the ledger file path.
+ * @param {object} snapshot - a value from `UsageLedger#snapshot`.
+ * @returns {string} the destination path.
+ */
+export function saveLedger(path, snapshot) {
+  return writeFileAtomic(path, `${JSON.stringify(snapshot, null, 2)}\n`)
+}

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "@chenmiao8563/dsh-token-ledger",
+  "version": "0.1.0",
+  "description": "Transparent, auditable token accounting for DeepSeek Harness: a restart-safe ledger over the durable session log, plus a CLI that recomputes it from raw logs and diffs the result.",
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek",
+    "deepseek-harness",
+    "cordis",
+    "token-usage",
+    "token-accounting",
+    "usage-stats",
+    "cost-tracking",
+    "ledger",
+    "audit",
+    "llm-observability"
+  ],
+  "license": "MIT",
+  "author": "chenmiao8563 <1420647373@qq.com>",
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./cli": "./lib/cli.js",
+    "./ledger": "./lib/ledger.js",
+    "./session-log": "./lib/session-log.js",
+    "./store": "./lib/store.js",
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "dsh-token-ledger": "bin/dsh-token-ledger.mjs"
+  },
+  "files": [
+    "lib/",
+    "bin/",
+    "docs/",
+    "cordis.patch.yml",
+    "README.md",
+    "README.zh.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22.15.0"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs",
+    "test:single-process": "node --test --experimental-test-isolation=none test/*.test.mjs",
+    "verify": "node scripts/verify-package.mjs",
+    "prepublishOnly": "npm run verify && npm test"
+  },
+  "dsh": {
+    "pluginType": "feature",
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "compatibility": {
+      "dsh": ">=0.1.2-alpha.1"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chenmiao8563/dsh-token-ledger.git"
+  },
+  "bugs": {
+    "url": "https://github.com/chenmiao8563/dsh-token-ledger/issues"
+  },
+  "homepage": "https://github.com/chenmiao8563/dsh-token-ledger#readme",
+  "publishConfig": {
+    "access": "public"
+  }
+}