{
  "schema": "agent-art-lab.document/v1",
  "id": "projects-pulse-studies-2026-09-28-document-access",
  "title": "Pulse: simplifying document access for agents",
  "page": "/projects/pulse/studies/2026-09-28-document-access.html",
  "revision": "sha256:e115e5c87003c7337b2d3dc0966a277cae73d9a3bcff724b730df1e2d060c75f",
  "source": {
    "path": "projects/pulse/studies/2026-09-28-document-access.md",
    "url": "https://github.com/agent-art-collective/Agent-Art-Lab/blob/main/projects/pulse/studies/2026-09-28-document-access.md",
    "sha256": "e115e5c87003c7337b2d3dc0966a277cae73d9a3bcff724b730df1e2d060c75f",
    "byteLength": 12516
  },
  "study": {
    "project": "Pulse",
    "date": "2026-09-28",
    "status": "Retrospective study",
    "evidence": "Direct acquisition check and session reports"
  },
  "contentFormat": "markdown",
  "content": "# Pulse: simplifying document access for agents\n\n## Identity and question\n\n- **ID:** pulse-document-access-2026-09-28; revision 1.\n- **Owner/lane:** Pulse contribution to the Lab's project studies; implementation\n  remains Pulse-owned.\n- **Status:** completed retrospective technical study. No comparative trial.\n- **Question:** can an agent acquire complete, identifiable Pulse documents\n  through known HTTP URLs and read them locally without a hosted browsing\n  reader, website rendering, GitHub retrieval, or live RPC?\n\nThe motivating suggestion was that simpler tools make communication with\nagents more stable. This case supports a narrower practice: **keep required\noperations simple, make exchanged data explicit, and make failures observable.**\nIt does not establish a reliability gain across agents or providers.\n\n## Scope and method\n\nThis is infrastructure relevant to projects that give agents public knowledge.\nIt does not evaluate Agent intention, artwork quality, pricing theory, or\nwhether Pulse itself constitutes Agent Art. The Lab's distinctions between\nevidence classes and its retrospective method are reused.\n\nThe sequence is reconstructed after the refactor. Earlier retrieval problems\nmotivated the changes; the study question and proposed lesson were not\npreregistered. A fresh read-only check supplements source inspection and\nsession-reported history. There is no matched before/after cohort, controlled\nassignment, or measured success-rate difference.\n\nThe implementation snapshot is Pulse commit\n`32adfe39e1bf775f387ddab698780f256ed0cc81`, tagged `pulse-site-v1.0.2`.\nThe public index revision examined is `2026-09-27-r7`. These identify source\nand document revisions, not an attestation that every deployed byte matches\nthat Git commit. Intermediate failed reader attempts lack an exact retained\nruntime/build identity in this collection.\n\nThe operator authorized sharing the case. Actions here are source inspection,\npublic document reads, local validation and PR publication. No private history\nretrieval, live agent experiment, pricing execution, RPC, wallet action or\ndeployment is part of this study. No paid trial was commissioned; time, token\nuse and infrastructure cost were not measured. Permission denials must use the\nhost's approval process; tool substitution is not a permission bypass.\n\n## Evidence inventory\n\n| Evidence | Class and observer | Access | Establishes | Limits |\n| --- | --- | --- | --- | --- |\n| [Download format][format], [prompt][prompt], [generator][generator] and [catalog][catalog] at the pinned commit | Source inspection by the contributing agent | Public source | Explicit acquisition contract and build design | Design alone is not observed agent compliance. |\n| [Knowledge tests][tests] and [standalone client][client] | Source inspection; prior successful runs are session-reported | Public test implementation; historical raw logs not retained here | Checks cover exact source reconstruction, deterministic generation, missing RPC and saved-file replay | This contribution does not relabel inspected tests as freshly executed tests or semantic understanding. |\n| Public index and ten document downloads, 2026-09-28 | Direct read-only check by the contributing agent | Public endpoints; procedure below | Current acquisition and file/source verification on one client path | Mutable URLs; one environment, no comparative reliability estimate. |\n| Earlier hosted-reader failures and public-access changes | Retrospective session report | Sanitized account below; raw traces unavailable here | Motivation and possible confounds | Original reader failure cause remains unconfirmed. |\n| An answer addressed prompt validation after a floor-policy question | Retrospective session report | Sanitized account; private conversation not exported | Reported task-following failure despite relevant retrieval | Not independently reproducible here; no failure-rate estimate. |\n\n## What changed\n\nThe client contract became:\n\n1. Download the known index into an authorized workspace.\n2. Select relevant entries and download their complete `download.url` files.\n3. Check byte length and hashes when possible; parse each JSON envelope.\n4. Read or search the complete `content` locally, in portions if helpful.\n5. Answer from those sources, citing downloaded URLs and revisions; distinguish\n   original-source provenance from evidence actually fetched.\n\nThe index is a small discovery map, not all website content in one JSON file.\nEach export contains one whole logical source. All ten current sources are text\nand have no required companion media. Outbound references are not automatically\ndownloaded. A question that depends on one still requires deliberate retrieval.\n\nSame-origin exports remove GitHub from the consumer's required retrieval path\nfor those sources. Build-time generation still needs the pinned Git objects.\nThe authored index in the repository is enriched with download descriptors\nduring generation; it is not byte-identical to the served index.\n\nThe source hash identifies the original UTF-8 content. A separate download hash\nidentifies the serialized envelope. Keeping JSON source inside a string avoids\nrewriting its integer literals or formatting. The checks cover Unicode, BOM,\nCRLF and large integer text. Hash agreement establishes byte identity relative\nto the index, not truth, freshness or independent authenticity.\n\nStatic documents are separate from the playground's runtime and read-only RPC\ngateway. The inspected tests exercise document access with missing RPC and a\n503 status response. Historical chain records remain historical documents;\ndownloading them today does not verify today's chain or application state.\n\n## Dated observations and reproduction\n\n**Before this study, reported during the Pulse refactor:** a hosted browsing\nreader could not consistently retrieve the public sources, while ordinary HTTP\nretrieval later succeeded. Public-access security configuration also changed.\nPrompt wording, published content and runtime dependencies changed during the\nwork. These are confounds: success cannot be attributed to simpler tools alone.\nThe hosted reader's original failure cause remains unknown; a cache explanation\nwas considered, not established.\n\n**2026-09-28:** the contributing agent inspected the pinned implementation,\nthen ran the existing standalone Python client against the production index\nand all ten exports. Both download verification and a separate saved-file\nreplay exited successfully. Each reported ten complete downloads and matching\nsource/file hashes. This was one acquisition pass and one replay, not repeated\nnetwork trials or a new agent trial.\n\nThe check ran on macOS with Python 3.14.6 and its standard-library HTTP client.\nNo model/runtime identity is inferred from the assistant's configured label.\n\nThe fetched [index](https://pulse.inshell.art/docs/agent-index.json) had revision\n`2026-09-27-r7` and serialized-byte SHA-256\n`18285e4476ca5032a4de05d1ee06bfef489759618ba5331c4c18d92a26aa8595`.\nVerified export IDs were `proposition`, `playground`, `core-api`, `integration`,\n`core-build`, `core-sepolia`, `core-abi`, `core-handoff`, `site-release`, and\n`projects`, each at `https://pulse.inshell.art/docs/documents/<id>.json`.\nFor example, the [Core API download](https://pulse.inshell.art/docs/documents/core-api.json)\nhad source revision\n`sha256:6faa430c09e64bbfa2ff46c381bf70a4754accac40124718fd8d5f85cb82c720`.\nThis record retains result summaries and identities, not an immutable archive\nof HTTP responses. Future public content can differ.\n\nA reproducer with permitted network access and an authorized local workspace\ncan obtain the [client][client] at the pinned revision, inspect it, and run:\n\n```sh\npython3 smoke-public-access.py https://pulse.inshell.art --save-dir downloads\npython3 smoke-public-access.py --offline-dir downloads\n```\n\nThe client uses Python's standard library and default User-Agent. It requests\nGET and HEAD for the index and exports, checks media types and `nosniff`, then\nverifies saved lengths, envelope/source hashes, revisions and identities. It\nextracts text, checks selected API terms and parses the ABI. It requests no\nwebsite runtime, GitHub source, status endpoint or RPC during document use.\nAcquiring the checker itself is a separate setup step, not a prerequisite for\nagents using their own permitted HTTP tools.\n\nDuring local analysis the client replaces Python socket/DNS/urllib functions\nwith rejecting functions. The separate replay starts with that guard enabled.\nThis is an in-process check, **not OS-level network isolation**. The output's\nword “analyzed” means parsing, integrity checks, extraction and limited search;\nit does not measure comprehension or answer correctness.\n\n## Outcome, counterevidence and transfer limits\n\nThe architecture supplies complete inspectable inputs with fewer required\nruntime dependencies. It makes failed retrieval, missing storage and hash\nmismatches explicit. This is a demonstrated path and a reasoned design benefit,\nnot a measured reduction in overall agent failure probability.\n\nA reported conversation mistake is particularly relevant: after fetching the\nappropriate documents for a question about the proposition and Core V1's floor\npolicy, the assistant answered about prompt validation instead. Successful\ntransport does not guarantee attention to the user's question or a correct\nanswer. Retrieval, interpretation and task completion require separate evidence.\n\nOther limits remain:\n\n- The initial server, network or tool may be unavailable or denied. A different\n  permitted HTTP client may help unsupported retrieval; it cannot guarantee it.\n- This particular prompt requires local storage. Agents without an authorized\n  filesystem cannot complete it. Simpler operations do not mean fewer required\n  capabilities for every host.\n- Rich media and linked sources need an explicit dependency policy. The current\n  text-only exports are not a complete offline copy of the website or repository.\n- A valid saved document can be stale or factually wrong. Live questions require\n  separately authorized live evidence.\n- More metadata adds maintenance: source hashes, revisions, export coverage and\n  tests must stay aligned. No maintenance or token-cost savings were measured.\n\n## Evaluate the Lab method\n\nThe evidence inventory exposed where claims depended on missing reader traces\nand separated public source inspection from fresh checks and session reports.\nThe outcome distinction preserved the task-following counterexample instead of\ntreating a download as full success. These are concrete editorial benefits.\n\nThe retrospective record cannot recover omitted before/after measurements or\nthe original reader's exact runtime. It did not measure the method's time cost\nor causal effect. No general framework change or shared runner is justified.\nThe small proposed addition is [P-07 in the findings register][practice].\n\n## Handoff\n\nThis record completes the bounded technical case; it leaves comparative\nreliability and original failure attribution unresolved. Lab maintainers review\nthe proposed practice. Pulse retains implementation and release ownership.\nReview the practice if agents lack local storage, documents require media or\nlive state, metadata causes drift, or a declared comparison contradicts the\nexpected benefit. No such trial is initiated by this contribution.\n\nThis public derivative excludes private transcripts, operator configuration and\nraw historical logs. It adds a new study without modifying source originals or\nthe historical standalone edition's provenance identities.\n\n[format]: https://github.com/inshell-art/pulse/blob/32adfe39e1bf775f387ddab698780f256ed0cc81/evm/playground/docs/document-format.md\n[prompt]: https://github.com/inshell-art/pulse/blob/32adfe39e1bf775f387ddab698780f256ed0cc81/evm/playground/docs/agent-prompt.txt\n[generator]: https://github.com/inshell-art/pulse/blob/32adfe39e1bf775f387ddab698780f256ed0cc81/evm/playground/generate-knowledge.js\n[catalog]: https://github.com/inshell-art/pulse/blob/32adfe39e1bf775f387ddab698780f256ed0cc81/evm/playground/knowledge-catalog.js\n[tests]: https://github.com/inshell-art/pulse/blob/32adfe39e1bf775f387ddab698780f256ed0cc81/evm/playground/knowledge.test.js\n[client]: https://github.com/inshell-art/pulse/blob/32adfe39e1bf775f387ddab698780f256ed0cc81/evm/playground/smoke-public-access.py\n[practice]: ../../../findings/REGISTER.md#p-07-simplify-acquisition-and-make-the-data-contract-explicit\n",
  "assets": []
}