Skip to content

Commit

Permalink
docs: update md files to include titles against relative path hrefs
Browse files Browse the repository at this point in the history
  • Loading branch information
mujahidkay committed Aug 30, 2024
1 parent 67141a1 commit ab06490
Show file tree
Hide file tree
Showing 5 changed files with 7 additions and 9 deletions.
3 changes: 1 addition & 2 deletions packages/pass-style/doc/copyArray-guarantees.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,8 +17,7 @@ The input validation check `assertCopyArray(arr)` asserts that `passStyleOf(arr)
# How do I enumerate thee, let me list the ways

Why these properties restrictions?
JavaScript has a [tremendous number of different constructs for enumerating the
properties](enumerating-properties.md) of an object, with different semantics
JavaScript has a [tremendous number of different constructs for enumerating the properties](enumerating-properties.md "https://github.com/endojs/endo/blob/master/packages/pass-style/doc/enumerating-properties.md") of an object, with different semantics
of what subset they choose to enumerate.
Once an object passes `assertCopyArray(arr)`, all of these are guaranteed to
agree except for `length`.
Expand Down
3 changes: 1 addition & 2 deletions packages/pass-style/doc/copyRecord-guarantees.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,8 +26,7 @@ If `r` is a proxy, then, if this plan goes as we expect, this test will throw wi
# How do I enumerate thee, let me list the ways

Why only string-named own enumerable data properties?
JavaScript has a [tremendous number of different constructs for enumerating the
properties](enumerating-properties.md) of an object, with different semantics
JavaScript has a [tremendous number of different constructs for enumerating the properties](enumerating-properties.md "https://github.com/endojs/endo/blob/master/packages/pass-style/doc/enumerating-properties.md") of an object, with different semantics
of what subset they choose to enumerate.
Once an object passes `assertRecord(r)`, all of these are guaranteed to agree.

Expand Down
2 changes: 1 addition & 1 deletion packages/patterns/docs/marshal-vs-patterns-level.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

We have three very distinct abstraction levels in our system in which to describe the passable data types and the operations on them. On the left is the higher ***`kindOf`*** level, containing the passable data types and operations of concern to the normal application programmer. A document intended for those application programmers would explain the `kindOf` level in a self contained manner. This is not that document.

In the middle is the lower ***`passStyleOf`*** level of abstraction, which defines the [core data model of the language-independent OCapN protocol]((https://github.com/ocapn/ocapn/issues/5#issuecomment-1549012122)). The `passStyleOf` level provides the data types and operations used to implement the `kindOf` level, but without being specific to the `kindOf` level. The OCapN core data types, the `passStyleOf` level, and the [`@endo/pass-style`](https://www.npmjs.com/package/@endo/pass-style) and [`@endo/marshal`](https://www.npmjs.com/package/@endo/marshal) packages can support independent co-existing higher layers like this `kindOf` level.
In the middle is the lower ***`passStyleOf`*** level of abstraction, which defines the [core data model of the language-independent OCapN protocol](https://github.com/ocapn/ocapn/issues/5#issuecomment-1549012122). The `passStyleOf` level provides the data types and operations used to implement the `kindOf` level, but without being specific to the `kindOf` level. The OCapN core data types, the `passStyleOf` level, and the [`@endo/pass-style`](https://www.npmjs.com/package/@endo/pass-style) and [`@endo/marshal`](https://www.npmjs.com/package/@endo/marshal) packages can support independent co-existing higher layers like this `kindOf` level.

On the right is the *JavaScript* level, explaining how these map onto JavaScript language. This mapping determines how JavaScript values round trip or not through the protocol. Only hardened JavaScript values can be passable. The mapping of protocol concepts to JavaScript should serve as an example of how to map the protocol onto the concepts of other languages.

Expand Down
6 changes: 3 additions & 3 deletions packages/ses/docs/lockdown.md
Original file line number Diff line number Diff line change
Expand Up @@ -184,7 +184,7 @@ wrapped `console`.
In addition, the virtual `console` has a special relationship with
error objects and with the SES `assert` package, so that errors can report yet
more diagnostic information that should remain hidden from other objects. See
the [error README](../src/error/README.md) for an in depth explanation of this
the [error README](../src/error/README.md "https://github.com/endojs/endo/blob/master/packages/ses/src/error/README.md") for an in depth explanation of this
relationship between errors, `assert` and the virtual `console`.

```js
Expand All @@ -211,7 +211,7 @@ LOCKDOWN_CONSOLE_TAMING=unsafe
The `consoleTaming: 'safe'` setting replaces the global console with a tamed
console, and that tamed console is safe to endow to a guest `Compartment`.
Additionally, any errors created with the `assert` function or methods on its
namespace may have [redacted details](../src/error/README.md): information
namespace may have [redacted details](../src/error/README.md "https://github.com/endojs/endo/blob/master/packages/ses/src/error/README.md"): information
included in the error message that is informative to a debugger and made
invisible to an attacker.
The tamed console removes redactions and shows these details to the original
Expand Down Expand Up @@ -308,7 +308,7 @@ magic powers of the v8 `Error` constructor—those consistent with the
level of disclosure of the proposed `getStack`. In all cases, the `Error`
constructor shared by all other compartments is both safe and powerless.

See the [error README](../src/error/README.md) for an in depth explanation of
See the [error README](../src/error/README.md "https://github.com/endojs/endo/blob/master/packages/ses/src/error/README.md") for an in depth explanation of
the relationship between errors, `assert` and the virtual `console`.

When running TypeScript tests on Node without SES,
Expand Down
2 changes: 1 addition & 1 deletion packages/ses/src/error/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -83,7 +83,7 @@ However, the above description violates one of our constraints: The automatic lo
This section explains our *plans* to build a logging experience on top of this system that supports local and distributed asynchrony. Also tracked at [Support deep stacks for local asynchronous log-based debugging #1862](https://github.com/Agoric/agoric-sdk/issues/1862) and [Support distributed deep stacks for log-based debugging #1864](https://github.com/Agoric/agoric-sdk/issues/1864).

JavaScript itself is not a dustributed language, but it is a highly asynchronous language. Our distributed computational model—communicating event loops—pushes much of our code into making heavy use of this asynchrony. For such code, individual synchronous call stacks are often short and uninformative. [Causeway](https://github.com/Agoric/agoric-sdk/issues/1318#issuecomment-662127549) shows that the asynchronous and distributed analog of synchronous stack traces is a directed acyclic graph of prior causal events, each with their local synchronous stack at their moment of causation. To capture this well requires instrumenting the promise system in ways impossible for user code. However, the most important causal paths are
* the [eventual-send](https://github.com/tc39/proposal-eventual-send) operations by [handled promise](../../../eventual-send/README.md), whether expressed by `E()` or `~.`.
* the [eventual-send](https://github.com/tc39/proposal-eventual-send) operations by [handled promise](../../../eventual-send/README.md "https://github.com/endojs/endo/blob/master/packages/eventual-send/README.md"), whether expressed by `E()` or `~.`.
* the `.then` operation. However, we replace the builtin `Promise.prototype.then` at our peril. Many built in operations implicitly invoke the original binding of `Promise.prototype.then` in ways we cannot override. However, our same eventual-send package already provides a safer alternative `E.when` operation.

Restricting the instrumentation to these two operations gives predictability and preserves platform independence, but at the loss of some useful diagnostic information. This loss may encourage programmers to shift from their current habits to eventual-send and `E.when`, which would be a good thing anyway.
Expand Down

0 comments on commit ab06490

Please sign in to comment.