read_library_entry

{
  "name": "read_library_entry",
  "resource": "library",
  "tier": "observe",
  "access": "anonymous",
  "summary": "One published entry: its file list with a hash and a size per file, or one named file's content, whole or, with `offset`, `limit`, and `stamp`, in chunks on the served context's paging, the stamp the file's hash and a stale one refused context_changed. Answers anonymously, like the inventory beside it — the recommendation moment precedes the account. Latest only: a publish replaces what is served, and a consumer keeps its own copy of what it holds.",
  "annotations": {
    "readOnlyHint": true,
    "destructiveHint": false,
    "openWorldHint": false,
    "idempotentHint": true
  }
}

{
  "name": "read_library_entry",
  "tier": "observe",
  "scenario": "API-L0-14",
  "summary": "Read one published library entry: its file list with a hash and size per file, or, with `file`, one file's content. The list holds a package's compiled runtime modules under `lib/`, never its source and tests. A package's import name is the `name` in its served `package.json`, which resolves to `lib/index.js`, the re-export of the package's runtime modules; its `testing` subpath holds the test double, which only an application's tests import. A large file reads in chunks: pass `limit`, then each answer's `next_offset` as `offset` with its `stamp` until it is null, and check the joined content, decoded where `encoding` is `base64`, against `sha256`. To take the entry, run the entry answer's `download.command`, or `download.command_windows` on Windows, at the project's root, then do what `download.next` says. Any signed-in connection reads it.\n\nThe entry answer also carries its previously published versions with the times each was published and superseded, which `list_library` does not. It reads the version `list_library` lists, since each publication replaces the library whole: no call reads an earlier version's files, and `previous_versions` gives each one's number and dates, never its files.",
  "owners": [
    "API-L0-15",
    "LC-02",
    "LC-05",
    "CTX-07"
  ]
}

{
  "request": {
    "type": "object",
    "required": [
      "name"
    ],
    "properties": {
      "name": {
        "type": "string",
        "description": "The entry's name, as `list_library` answers it."
      },
      "file": {
        "type": "string",
        "description": "One file's path within the entry, to read its content; omitted, the file list."
      },
      "offset": {
        "type": "integer",
        "minimum": 0,
        "maximum": 9007199254740991,
        "description": "With `file`: a zero-based Unicode code-point offset in the file's content as the answer encodes it; defaults to 0. Pass the previous chunk's next_offset to continue. A nonzero offset requires its stamp."
      },
      "limit": {
        "type": "integer",
        "minimum": 1,
        "maximum": 16000,
        "description": "With `file`: the most Unicode code points of content this chunk returns, 1 through 16000, default 8000. Naming offset, limit, or stamp reads the file in chunks; naming none reads it whole."
      },
      "stamp": {
        "type": "string",
        "pattern": "^[a-f0-9]{64}$",
        "description": "With `file`: the stamp the previous chunk returned, which is the file's SHA-256. Required with a nonzero offset. A publish that changed the file returns context_changed; restart at offset 0 without a stamp."
      }
    },
    "additionalProperties": false
  },
  "response": {
    "type": "object",
    "required": [
      "contract_version"
    ],
    "properties": {
      "contract_version": {
        "const": 1
      },
      "entry": {
        "type": "object",
        "required": [
          "name",
          "files"
        ],
        "properties": {
          "name": {
            "type": "string"
          },
          "kind": {
            "type": "string"
          },
          "path": {
            "type": "string"
          },
          "version": {
            "type": [
              "string",
              "null"
            ]
          },
          "closure_hash": {
            "type": "string"
          },
          "summary": {
            "type": [
              "string",
              "null"
            ]
          },
          "supersedes": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "published_at": {
            "type": "string"
          },
          "previous_versions": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "version",
                "published_at",
                "superseded_at"
              ],
              "properties": {
                "version": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "published_at": {
                  "type": "string"
                },
                "superseded_at": {
                  "type": [
                    "string",
                    "null"
                  ]
                }
              },
              "additionalProperties": false
            },
            "description": "Each previously published version of this entry with the times it was published and superseded, oldest first. `list_library` does not carry them. A versionless entry gains none. Each gives an earlier version's number and dates, never its files: no call reads an earlier version's files."
          },
          "files": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "path",
                "sha256",
                "size"
              ],
              "properties": {
                "path": {
                  "type": "string"
                },
                "sha256": {
                  "type": "string"
                },
                "size": {
                  "type": "integer"
                }
              },
              "additionalProperties": false
            }
          }
        },
        "additionalProperties": false
      },
      "file": {
        "type": "object",
        "required": [
          "path",
          "encoding",
          "content",
          "sha256"
        ],
        "properties": {
          "path": {
            "type": "string"
          },
          "encoding": {
            "enum": [
              "utf8",
              "base64"
            ]
          },
          "content": {
            "type": "string"
          },
          "sha256": {
            "type": "string"
          },
          "stamp": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$",
            "description": "On a chunked read: the stamp to pass with the next chunk, the file's SHA-256."
          },
          "offset": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "On a chunked read: this chunk's code-point offset in the file's content."
          },
          "total": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "On a chunked read: the content's length in code points."
          },
          "next_offset": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "On a chunked read: the next chunk's offset, null at the last chunk. Join the chunks' content in order, decode it where the encoding is base64, and check its SHA-256 against the file's."
          }
        },
        "additionalProperties": false
      },
      "download": {
        "type": "object",
        "description": "With the entry answer, on the MCP surface alone. `command` is the one line that takes the entry with the turnzero-cloud command's `library take`, on the answering platform's origin. `command_windows` is the same line for Windows. Run at the project's root, the line checks every listed file against its SHA-256 and the entry's closure hash before it writes anything. It then writes the entry's row in the library folder's `manifest.json` and replaces the entry's folder there whole. For an entry with compiled modules, it copies `package.json` and `lib/` into the application's folder and runs `npm install`. Its `next` says where to run the line and what remains: the commit, the rows it prints for the application manifest's `packages` member, and, where the project holds the registrar, the proof and a package's pin in its instance file. An entry whose name the line cannot carry is answered `next` alone, saying so.",
        "required": [
          "next"
        ],
        "properties": {
          "command": {
            "type": "string",
            "description": "One line, for macOS and Linux: `npx -y <origin>/packages/turnzero-cloud-<version>.tgz library take --entry <name>`, then `--origin <origin>` off `https://turnzero.ai`. Run it once, as given, at the project's root. It ends 0 where the entry was taken, 1 where its install failed, and 3 where nothing was written."
          },
          "command_windows": {
            "type": "string",
            "description": "Present with `command`: the same line for every Windows shell, with `npx.cmd` where its head says `npx`. On Windows, run this one in `command`'s place, as given."
          },
          "next": {
            "type": "string"
          }
        },
        "additionalProperties": false
      },
      "source_commit": {
        "description": "The library commit this publish was read at. LC-07 requires a project's folder manifest to record, per entry, the commit it was published from; the fact lives on the catalog rather than on any row, so it is answered here or it is unreachable. Absent before the first publish.",
        "type": "string"
      },
      "published_at": {
        "description": "When this publish ran, ISO 8601. Distinct from an entry's own published_at, which is when that entry last changed. Absent before the first publish.",
        "type": "string"
      }
    },
    "additionalProperties": false
  }
}