1 files changed, 33 insertions, 0 deletions
diff --git a/docs/design/storage-analysis.md b/docs/design/storage-analysis.md
new file mode 100644
index 0000000..59fbcde
--- /dev/null
+++ b/docs/design/storage-analysis.md
@@ -0,0 +1,33 @@
+# bounds and lifetime findings
+
+## what the compiler knows
+
+the compiler records constant element counts for `new(n)`, `new(T, n)`, fixed arrays, and newly created array handles. a direct local alias shares the allocation's facts. a definite `free` or `recycle` ends that allocation's lifetime; closing a scope ends its stack storage and automatically released owned objects.
+
+an index outside a known length produces a warning. dereferencing, indexing, or accessing a field after a recorded lifetime end also produces a warning. these findings apply to unchecked code too. existing ownership errors and fixed-array index errors keep their current behavior. warnings do not prevent compilation.
+
+```zc
+unchecked fn example() {
+    let p = new(int, 3);
+    let q = p;
+    q[3] = 1;       // warns: index 3 is outside length 3
+    free(p);
+    return q[0];    // warns: this allocation was freed
+}
+```
+
+## what stays unknown
+
+this is basic analysis of local facts, not a proof of the whole program. branches, loops, short-circuit operators, raw assembly, and nested compilation discard facts instead of merging uncertain paths. unknown callees invalidate facts about allocations passed to them. array mutations invalidate recorded lengths. pointer arithmetic, explicit casts, pointer-valued fields, stored aliases, and function return contracts are not inferred by this pass.
+
+an unknown fact does not produce a definite warning. runtime array checks still run. the pass may miss an error across one of these boundaries; silence is not a safety guarantee. the broader analysis in [BORROW.md](../BORROW.md) remains a design plan.
+
+## editor previews
+
+array and pointer hovers show the known element count and lifetime at that reference. a live stack allocation names its scope exit as its lifetime end. a live heap allocation ends when freed or released by its owner. a reference after a recorded end names that line. unavailable sizes and lifetimes say `unknown`.
+
+facts are copied into each reference's editor record while the compiler parses it. a later `free` therefore does not make an earlier hover claim the object was already dead. block comments and inferred type text remain part of the same markdown preview.
+
+## focused checks
+
+`node tests/drivers/storage_analysis_test.js bin/zclsp` checks known bounds, packed elements, direct aliases, free and scope lifetimes, hover metadata, and safe or uncertain neighboring cases.